Deploying agents

A deploy turns a bundle (a zip with a Dockerfile and an agentos.yaml at its top level) into a new version of an agent. Deploying is an admin action in the environment. Everything on this page can also be done with the Deploy API.

​

Deploy a new agent

Open Agents → Deploy agent and drop your zip on the page. The first upload of a name creates the agent: the bundle is checked, built and health-checked, and becomes v1. Click Build v1 to start. agentos.yaml is read on upload, before anything is built: the name, capabilities, schemas and the models in config.models must all resolve. If anything is wrong the page shows The bundle was not accepted with one line per problem (port: must be a whole number between 1 and 65535, capabilities.triage.timeout: …), and nothing is built.

​

Update an agent

Open the agent’s Deploy tab (or Update agent in the bar at the top of the agent page) and drop the new zip. You get two buttons: Only one deploy of an agent runs at a time; the upload button says why it is disabled while another one is running.

​

Promotion checks and the deploy log

While a version builds, the Promotion checks card ticks through its steps:

1. Spec valid: the bundle and agentos.yaml were accepted.
2. Image built: AgentOS built the image from your Dockerfile. The build has internet access but no secrets.
3. Pushed to the registry: the image is stored, so the version can be started again later.
4. Container healthy: the container answered GET /health with a 2xx.

The Deploy log below streams the build output live. If the container exits before it is healthy, the deploy fails at once with its exit code and last output, so the log usually tells you what went wrong.

​

When the config differs from the live version

A version’s config (models.<role>, prompts.<name>, params.<key> in agentos.yaml) can be changed in the panel without a new upload, for example from the Prompts tab or an experiment. So when you upload a bundle whose config differs from the live version’s, AgentOS doesn’t silently overwrite one with the other. Instead the upload card shows a table: Choose per key which value the new version uses (live is pre-selected), then click Deploy live or Deploy as candidate. Your choice is written into the new version’s config; the stored agentos.yaml text stays exactly as uploaded. A key that only one side has isn’t a difference: your code decides which keys exist. The upload waits for your choice for up to an hour.

​

Missing secrets

If the version declares names under secrets: in agentos.yaml that have no value yet, the deploy still succeeds, but it is marked: a warning in the deploy log and a MISSING SECRETS badge on the Deploy and Secrets tabs. Set the values on the agent’s Secrets tab; they apply from the next invocation, with no new deploy. See Secrets.

​

Versions

The Version history lists every version, newest first, with its image digest, status, how many capabilities it has, its port and who deployed it. log opens the deploy that produced it. Runs always finish on the version they started on. An older version’s container that was stopped is started again if one of its runs still needs it (for example a run that was waiting for an approval).

​

Roll back and promote

Older versions keep their image, so going back is fast and needs no rebuild:

• Roll back: pick an older version in the history (or in the version picker of the bar at the top of the agent page) and click Roll back to vN.
• Promote: a candidate has a Promote link in the history.

Either way the version’s container is started and health-checked first, and only then becomes live. If the check fails, the live version stays live.

​

Keeping the live version running

You don’t need to babysit containers. If the live version’s container is missing or stopped, AgentOS starts it again within about 30 seconds.

​

Next steps