stackbone build

stackbone build runs inside a project folder and targets no installation, so it takes no --agent. Its --json payload uses the standard envelope and it exits with the shared exit codes.

Compile the project into the workspace bundle: the directory your container image serves the agent from. The running image carries no TypeScript and no bundler, so build compiles every agent and workflow here, ahead of time.

Reach for build over stackbone package when you already own the image and the deployment and only want the workspace bundle.

stackbone build                       # writes dist/workspace-bundle
stackbone build --out-dir out/bundle  # anywhere else (relative to the project)

Flag	Type	Description
--out-dir	string	Where to write the bundle. Relative paths resolve against the project. Default: dist/workspace-bundle.

What lands in the output directory:

dist/workspace-bundle/
  .well-known/workspace.json                    # the manifest the runtime reads first
  .well-known/config/v1/config-schema.json      # your config.schema.ts, as JSON Schema
  .well-known/workflow/v1/step.mjs              # your compiled workflow steps
  .well-known/workflow/v1/workflow.vm.js        # the workflow bundle the VM runs
  .well-known/workflow/v1/manifest.json         # workflow ids, schemas, schedules
  .well-known/workflow/v1/workflow-schemas.mjs  # the live validators `/start` checks input with
  .well-known/migrations/v1/                    # your database migrations, copied verbatim
  deep-agents/<name>/index.mjs                  # one prebuilt module per deep agent

workflow-schemas.mjs makes the deployed container reject a bad POST /api/workflows/:name/start the same way stackbone dev does, instead of starting the run and failing somewhere inside it. The build compiles it from your inputSchema / outputSchema exports with the same zod your workflows use, and the result is not self-contained: it re-imports those packages (zod, @stackbone/sdk, anything your workflow module pulls in at the top level) from the image's own node_modules at boot. If one of them is not there, the container logs a warning naming the file and starts runs unvalidated, so production accepts a start your laptop rejects. Grep for that warning after a deploy.

config-schema.json is your config.schema.ts, converted to JSON Schema at build time. The container has no TypeScript, so it reads this file to render the config form in the dashboard and to validate every save. Write no config.schema.ts and the build ships no file, which is fine: config stays free-form. Write one the build cannot convert and it warns instead of failing, ships without the file, and the dashboard falls back to a raw JSON field with no validation on save. See stackbone.config.

The build bundles each deep agent with its own dependencies inlined, except for the packages that must stay a single copy per process. If one of your dependencies cannot survive bundling, keep it out with build.external. See Keeping a package out of the bundle. You install anything you list there into your image by hand, and the build prints the list so you know what to add.

If your agent has a database, the build copies .stackbone/migrations/ into the bundle and the container applies it on the first boot, straight off disk. There is nothing to download, so a container with no outbound network still comes up with your tables in place. Applying is idempotent: a restart adds nothing, and a database that was already migrated logs that it found nothing to do. See stackbone.database. A workspace with no schema file, or with a migrations folder you never generated into, ships no migrations and the boot says so.

If the project is linked (see stackbone link), the manifest also records the agent and organization it was built for, so the deployed container needs fewer environment variables.

Two workflows always come along, the same two stackbone dev gives you: rag-ingest (it turns an uploaded document into searchable chunks) and mapping-suggest (the dashboard's Auto-map runs it). The build writes the platform version of each into .stackbone/managed-workflows/ unless you wrote your own at workflows/rag-ingest.workflow.ts or workflows/mapping-suggest.workflow.ts, in which case yours wins. Leave them out and a document upload fails in the container while it still works on your laptop.

A workspace with only agents builds fine, and so does one with only workflows. Anything you did not write stays out of the manifest, and the runtime skips it.

A workflow that fails to compile does not fail the build. It ships in the manifest marked degraded, carrying its own compile error, so the deployed box lists it with the reason instead of serving a shorter catalog that explains nothing. The build names each degraded workflow in its summary. An agent that fails to compile still fails the whole build.

Copy the directory into your image (the runtime reads it from /app/workspace) and deploy. The variables that image boots on are listed at What you set on the deployed container.

Requirements: your project must have esbuild installed (for agents) and @workflow/builders (for workflows, which every bundle has because of the two above). The build resolves both from your own node_modules, so it builds the bundle with the exact versions your agent runs.

JSON payload

{
  "schema_version": 1,
  "outDir": "/abs/path/dist/workspace-bundle",
  "deepAgents": ["support", "billing"],
  "workflows": ["onboarding", "rag-ingest", "mapping-suggest"],
  "degradedWorkflows": [], // shipped but not runnable; each entry carries { name, message }
  "migrations": true, // false when the workspace ships no migrations
  "external": ["sharp"], // what you must install into the image yourself
  "manifestVersion": 2,
  "minImageVersion": "0.3.0", // the oldest runtime image that can read this manifest
}

Exit codes: 0 ok, 1 an agent compile failed (the message names the agent at fault; a failed workflow ships degraded instead, see above), or the build could not resolve esbuild or @workflow/builders from your project.