How do I publish a new version?

There is no publish command and nothing to promote. Your agent's version is the container image tag, so shipping a new version means deploying a new image and registering it.

Build the deliverable first. stackbone package writes a deploy folder holding your compiled workspace, a Dockerfile, a compose file, an .env, an .env.example and a README. Whoever runs your infrastructure brings that folder up with docker compose up -d. The .env carries generated secrets, so the folder runs untouched. The .env.example is the same template with placeholders, safe to commit next to the folder.

--target decides what the folder holds. The default, byoc, writes the agent on its own, and you register it from app.stackbone.ai afterwards. --target self-host writes the control plane and Studio beside it, for a customer whose network reaches nothing outside itself.

Take stackbone build instead when you already own the image and only want the workspace bundle to copy into a Dockerfile of your own. The bundle carries the compiled deep agents and workflows, your migrations, and the configuration schema extracted from config.schema.ts. A packaged agent renders the same config form the local run does.

Then register what you deployed:

stackbone link \
  --agent support \
  --installation <installation-id> \
  --url https://support.acme.example.com \
  --secret "$STACKBONE_HMAC_SECRET" \
  --tag 1.4.0

--installation names the cloud installation this box answers for: a cloud row of the agent in stackbone agents list. Re-running link for the same installation updates the existing deployment rather than creating a second one, so it is safe to call on every deploy. An installation has one box, so the new URL, secret and tag replace whatever was there. A second installation of the same template is a second box with its own link.

link works in order, and it fails closed. It reads the box's public handshake first and refuses a box that speaks an agent protocol older than version 15. Then it proves your --secret against the running box, tells the box which organization and installation it answers for, and registers the deployment last. If it cannot reach the box or cannot teach it, it registers nothing, so you never end up with a record pointing at a box that refuses every call.

Your database migrations ship inside the bundle, and the container applies them on boot, under an advisory lock and a journal. There is nothing to run against production by hand, and a restart applies nothing twice.

Not every change needs a new image. An agent's instruction lives in the prompt catalogue, not in your code, and each prompt keeps immutable versions with one of them live. Rewrite the text and make the new version live. The agent runs it with no build and no deploy.

stackbone package: the deploy folder and the three things to tell whoever runs it.
stackbone link: the flags, the secret check, and what it refuses.
stackbone.database: how migrations are applied at boot, and how to opt out.
stackbone.prompts: changing an agent's instruction without a deploy.

How do I publish a new version?

Read more