---
title: 'How do I publish a new version?'
description: 'There is no publish command. The container image tag is the version, so you deploy a new image and re-register it.'
position: 4
---

# 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 freshly minted secrets, so the
folder runs untouched. The `.env.example` is the same template with placeholders,
safe to commit next to the folder.

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`, so a packaged agent renders the same
config form the local run does.

Then register what you deployed:

```sh
stackbone link \
  --agent support \
  --url https://support.acme.example.com \
  --secret "$STACKBONE_HMAC_SECRET" \
  --tag 1.4.0
```

Re-running `link` for the same agent updates the existing deployment rather than
creating a second one, so it is safe to call on every deploy. An agent template
has one box, so the new registration replaces whatever was there.

`link` works in three steps, in this order: it proves your `--secret` against
the running box, tells the box which organization and installation it answers
for, then registers the deployment. It fails closed. 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.

## Read more

- **[`stackbone package`](/docs/cli/reference/package)**: the
  deploy folder and the three things to tell whoever runs it.
- **[`stackbone link`](/docs/cli/reference/link)**: the flags,
  the secret check, and what it refuses.
- **[`stackbone.database`](/docs/sdk/data/database)**: how migrations are applied
  at boot, and how to opt out.