> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Release agents from CI

> Build your agent container, register a deployment in Tilde from your CI pipeline, roll it out, and start accepting traffic.

Your CI pipeline builds the agent container from a regular Dockerfile and publishes it to your container registry. Before you roll out a new version, you register a deployment in Tilde with `tilde deploy`. The flow is the same for direct and sidecar agents. Only the target differs.

<img src="https://mintcdn.com/tilde/UIZH9VuZaVUMv6QU/images/agent-release-pipeline.drawio.svg?fit=max&auto=format&n=UIZH9VuZaVUMv6QU&q=85&s=3c983e0916983826620889af3903f4e1" alt="Release pipeline from a push in CI, through deployment registration and rollout, to the router sending new conversations to the release" width="1623" height="828" data-path="images/agent-release-pipeline.drawio.svg" />

<div className="zoom-hint"><Icon icon="magnifying-glass-plus" size={13} /> <em>Click to zoom</em></div>

## What your pipeline needs

* A **registration credential**, stored as a CI secret. Expose it only to trusted deploy jobs. See [Registration credentials](#registration-credentials).
* **Network access** to the gateway. For a self-hosted gateway, use a runner inside your network.
* The **agent ID** of the agent you are releasing.

Tilde works with any CI system. We provide a GitHub Action that registers a deployment, and every other system can run the same command.

## Register a deployment

`tilde deploy` loads your agent's entry module without starting it, finds the prompts, tools, and skills your code declares, and registers them with the new deployment. It prints the deployment token.

<CodeGroup>
  ```bash TypeScript theme={"system"}
  npx tilde deploy dist/index.js
  ```

  ```bash Python theme={"system"}
  python -m tilde deploy main.py
  ```
</CodeGroup>

Set `TILDE_URL`, `TILDE_API_KEY`, and `TILDE_AGENT_ID`, or pass them as options. Useful options:

| Option | Effect |
| - | - |
| `--target` | `gateway`, `sidecar`, or `lambda`. |
| `--external-id` | A unique ID for the release, such as the commit SHA. Registering the same ID again returns the same deployment, so the step is safe to retry. |
| `--json` | Prints the deployment ID and token as JSON. |
| `--dry-run` | Prints what would be registered, and contacts nothing. |

Run it after you build, in the same environment as your agent's dependencies, so framework adapters can read your agent. See [Prompts](/docs/prompts/overview#how-prompts-are-registered).

## Registration credentials

<Tabs>
  <Tab title="Cloud and Enterprise">
    Use a [management API key](/docs/operator-access#management-api-keys) that holds the `deploy` action on the agent. A deployer role is enough.
  </Tab>

  <Tab title="OSS">
    Use the agent's deployment registration key, from the agent's **Capabilities** or **Deployment** tab. It can register deployments for that agent only.
  </Tab>
</Tabs>

## How a release works

1. **Push or merge** to your release branch.
2. **Build and test** the agent image: your code, your framework, the core SDK, and its adapter. Node and Python images follow the same steps.
3. **Push the image** to your private registry.
4. **Register the deployment.** Your pipeline runs `tilde deploy`. It registers the release with its prompts, tools, and skills. Tilde returns a deployment ID and a one-time token. The release is registered but offline.
5. **Deploy.** Your pipeline stores the token in your secret manager and rolls out the new release with your usual tooling.
6. **Agent replicas start.** They dial the gateway with the token and send ready heartbeats. The deployment becomes serving.
7. **Routing moves traffic.** New conversations go to the new release according to your [routing](/docs/routing) mode. Existing conversations stay pinned to their original deployment, so keep the old release running until they drain.

## Deployment tokens

Tilde shows a deployment token once and stores only its hash. Your pipeline passes it straight to your secret manager, and every replica of the release uses it. Registration is safe to retry, and you can rotate a token at any time.

## Verify the release

Open the agent's **Deployment** tab. The release shows as serving, with the commit linked. Select it to see the prompts, skills, and tools it shipped. Run a test conversation, then check its [session](/docs/sessions) and [traces](/docs/traces).