Codebases & bundles

Most Orvanta scripts are self-contained: one file, its dependencies resolved from a lockfile at deployment. A codebase is the alternative for scripts that are part of a real repository — where the entry point imports from ../lib/, shares types with the rest of the project, and only makes sense alongside the code around it.

With a codebase, the CLI bundles the entry point and everything it imports into a single artefact, uploads that artefact, and Orvanta runs the pre-built bundle instead of resolving imports at runtime.

Before you start: is this available to you?

Codebases have a narrower reach than most Orvanta features, and it is worth checking before you restructure a repository around them.

Requirement	Detail
Language	Bun only. Deno, Python, Go, PHP, Rust, C#, Java, Bash and the rest have no codebase path. Only the Bun and Bun-native executors accept a bundle.
Interface	CLI only. There is no editor page, no workspace setting, and no UI for creating one. The web editor shows a bundle badge on such scripts and disables Edit and Fork.
Edition	Business or Enterprise (OEE) build, or a standalone-mode deployment. See below.
Licence tier	Distributed storage is refused on the Teams tier, which in practice disables codebases on a multi-worker Teams deployment. Trial and Enterprise are not refused.
Storage	An instance object store must be configured, unless you are running in standalone mode.

This is not a beta feature, and it will not prompt you to upgrade

Codebases are not part of Orvanta’s feature catalogue, so they are not hidden behind ORVANTA_BETA and they produce no “upgrade your plan” message. On a build or tier that cannot support them, an upload fails at execution time with the error codebase is an OEE feature. If you see that message, the cause is your build or your storage configuration — not a malformed bundle.

Edition and storage in detail

The upload and pull paths are compiled only into builds that carry both the enterprise and the object-store capabilities. Orvanta’s published container images are built as Enterprise (enterprise_edition) — the same OEE image that both the Business and Enterprise editions run, per the licence’s tier-to-binary mapping — so they include them. A Teams-only build (--features teams, also used by Solo) compiles the fallback arm, which raises codebase is an OEE feature.

There is one exception that does not require an Enterprise build: if the deployment runs in standalone mode and no object store is configured, bundles are written to and read from local disk under ~/.orvanta/standalone_bundle instead. This makes codebases usable on a single-binary deployment, but it does not survive multiple workers on separate hosts — each worker would need its own copy.

On a Business or Enterprise build with more than one worker, configure an instance object store. The bundle is stored under script_bundle/{workspace}/{digest} and pulled by whichever worker picks up the job, then cached on that worker’s local disk.

How it works

1. You declare a codebase in orvanta.yaml, describing which directory it covers and how to bundle it.
2. The CLI bundles it. orvanta script push and orvanta sync push run esbuild over the entry point with bundle: true and packages: "bundle", producing a single artefact. You can substitute your own bundler.
3. The CLI computes a digest of the directory’s contents plus the codebase configuration. That digest becomes the artefact’s identity — for example a1b2c3….esm.tar. The suffix encodes the shape: .esm for ESM output, .tar when assets are included.
4. The CLI uploads the artefact together with the script metadata in a single multipart request, and the digest is recorded against the script.
5. A worker pulls the bundle when the script runs, caches it locally, unpacks it into the job directory, and executes it.

Because the digest is derived from the directory’s contents, changing any file in the codebase changes the digest, which is how the CLI knows to re-push. orvanta sync pull deliberately does not rewrite the digest — pulling a workspace never claims your local bundle is current.

What changes at deployment

A codebase script skips lock generation entirely. There is no dependency resolution and no lockfile, because the bundle already contains everything. Orvanta also skips its usual relative-import dependency mapping for these scripts, for the same reason.

That is the trade-off in one sentence: you move dependency resolution from Orvanta’s deployment step to your own build step. You get reproducibility and your repository’s real import graph; you give up Orvanta resolving and locking dependencies for you, and you give up editing the script in the browser.

Configuring a codebase

Codebases are declared in orvanta.yaml under a top-level codebases: array. Run orvanta init to scaffold the file — it emits this block, commented out.

codebases:
  - relative_path: src/jobs
    includes:
      - "src/jobs/**/*.ts"
    excludes:
      - "**/*.test.ts"
    format: esm
    assets:
      - from: src/jobs/templates
        to: templates
    external:
      - aws-sdk
    define:
      BUILD_ENV: '"production"'

Every field, as the CLI reads them:

Field	Type	Purpose
relative_path	string, required	Directory this codebase covers, relative to the repository root.
includes	string[]	Glob patterns for files belonging to the codebase. Defaults to everything under relative_path.
excludes	string[]	Glob patterns to leave out — tests, fixtures, local scratch files.
assets	{ from, to }[]	Non-code files to carry alongside the bundle. Their presence forces the .tar artefact form.
format	"cjs" | "esm"	Output module format. cjs targets Node 20; esm targets esnext.
customBundler	string	Shell command to run instead of esbuild. Use this if your project already has a build pipeline.
external	string[]	Modules to leave unbundled.
define	object	Compile-time constant replacements.
inject	string[]	Files injected into every bundled module.
banner	object	Text prepended to the output, keyed by output type.
loader	object	Per-extension loader overrides.

Only .ts files are matched against a codebase, and the first matching entry wins — so order your codebases: entries from most specific to most general.

Working with codebases

# Scaffold orvanta.yaml, then add a codebases: block to it
orvanta init

# Bundle and deploy a single codebase script
orvanta script push src/jobs/reconcile.ts

# Bundle and deploy everything the sync configuration covers
orvanta sync push

# Run a codebase script locally without deploying it
orvanta script preview src/jobs/reconcile.ts

orvanta dev also resolves codebases, so the local development loop works against the same bundling configuration.

Known gap

Flow preview and orvanta dev cannot currently inline codebase assets. A script whose bundle depends on assets: entries may behave differently under preview than when deployed. This is a limitation in the CLI’s local execution path, noted in the source.

When not to use a codebase

• Your script is a single file. The ordinary deployment path is simpler, keeps the browser editor working, and gives you Orvanta-managed lockfiles.
• You are not writing TypeScript for Bun. There is no equivalent for other runtimes; use workspace dependencies or a custom worker image instead.
• You want people to edit the script in Orvanta. Codebase scripts are read-only in the editor by design — the source of truth is your repository.
• You are on the Teams tier with multiple workers. Distributed bundle storage is not available to you.

Related

• Scripts: the ordinary, single-file deployment model.
• Object storage: configuring the instance object store that bundles are kept in.
• Git sync: keeping a workspace in step with a repository.