# Deploy your agent

Turn a recipe in your repository into a runtime that staging and production can call.

A **runtime** is your recipe deployed. Every commit to the default branch builds a new **version**, and each environment serves one version at a time. Deploy once; after that, merging is shipping.

**You need:** a recipe that passes `introspection check`, `introspection login`, and the GitHub App installed on the repository ([Let the agent work on your code](/ship/repositories#1-install-the-github-app)).

## 1. Add a manifest

```yaml filename=".introspection/support-agent.yaml"
name: support-agent
description: Drafts refund decisions from our policy.
path: apps/support-agent      # the recipe directory
runtime:
  llm_mode: managed           # or byok: your own model keys, see Choose models
```

The filename stem is the runtime's slug: lowercase letters, digits, and single hyphens, up to 63 characters.

## 2. Push to the default branch

```bash
introspection check
git push origin main
```

Pushes to other branches build nothing, except previews for open pull requests (step 5).

## 3. Create the runtime

```bash
introspection runtimes create --manifest .introspection/support-agent.yaml
```

`--manifest` is optional when the repository has one manifest, or when you run the command inside the recipe directory.

The first version serves **staging and production at once**. To keep later
merges out of production, [pin production](/ship/rollback#pin-production-to-a-version)
on version 1 right away.

## 4. Bind what the recipe needs

Model keys, MCP servers, API hosts, and secrets are set per runtime and environment: [Connect services and secrets](/ship/bindings).

## 5. Ship each change

Merge to the default branch. What happens next:

| Event | Result |
| --- | --- |
| Push or merge to the default branch | A new version of **every** runtime registered from that repository. Unpinned staging and production move to it when its build is ready. |
| Pull request opened or updated | A preview version. Unpinned staging switches to it and keeps it until the pull request merges or closes; a second pull request does not take it ([Test before production](/ship/staging)). |
| Build fails | Nothing moves. |
| A required MCP server is down during the build | With `mode: tools`, the build fails and nothing moves, unless the server sets `"discovery": "defer"` ([Connect an MCP server](/build/mcp)). |

A task picks its environment's version when it is created, so a new version only affects new tasks.

## Verify

```bash
introspection runtimes list --runtime support-agent
introspection tasks create --runtime support-agent -e staging --prompt "Reply with ready."
introspection conversations get <task-id>
introspection conversations list --lookback 1h --filter recipe_git_commit_sha=<commit-sha>
```

`<commit-sha>` is the full SHA you pushed (`git rev-parse HEAD`); the last command lists conversations that commit served. A `completed` task alone is not a pass: read the conversation.

Other manifest keys: `strict` (unknown keys become errors), `runtime.resources` (CPU and memory requests and limits, and scratch storage), and `runtime.github` ([Let the agent work on your code](/ship/repositories)).

## Limits

| Not supported | Do this instead |
| --- | --- |
| Running `runtimes create` again | It returns `409`. Merge to ship a new version. |
| Rolling back with `runtimes delete` | It deletes every version. [Yank](/ship/rollback) instead. |

Or ask your agent: "Deploy support-agent to Introspection and verify it in staging."

Deploy your agent

Turn a recipe in your repository into a runtime that staging and production can call.

A runtime is your recipe deployed. Every commit to the default branch builds a new version, and each environment serves one version at a time. Deploy once; after that, merging is shipping.

You need: a recipe that passes introspection check, introspection login, and the GitHub App installed on the repository (Let the agent work on your code).

1. Add a manifest

.introspection/support-agent.yaml


name: support-agent
description: Drafts refund decisions from our policy.
path: apps/support-agent      # the recipe directory
runtime:
  llm_mode: managed           # or byok: your own model keys, see Choose models

The filename stem is the runtime’s slug: lowercase letters, digits, and single hyphens, up to 63 characters.

2. Push to the default branch


introspection check
git push origin main

Pushes to other branches build nothing, except previews for open pull requests (step 5).

3. Create the runtime


introspection runtimes create --manifest .introspection/support-agent.yaml

--manifest is optional when the repository has one manifest, or when you run the command inside the recipe directory.

The first version serves staging and production at once. To keep later merges out of production, pin production on version 1 right away.

4. Bind what the recipe needs

Model keys, MCP servers, API hosts, and secrets are set per runtime and environment: Connect services and secrets.

5. Ship each change

Merge to the default branch. What happens next:

Event	Result
Push or merge to the default branch	A new version of every runtime registered from that repository. Unpinned staging and production move to it when its build is ready.
Pull request opened or updated	A preview version. Unpinned staging switches to it and keeps it until the pull request merges or closes; a second pull request does not take it (Test before production).
Build fails	Nothing moves.
A required MCP server is down during the build	With `mode: tools`, the build fails and nothing moves, unless the server sets `"discovery": "defer"` (Connect an MCP server).

A task picks its environment’s version when it is created, so a new version only affects new tasks.

Verify


introspection runtimes list --runtime support-agent
introspection tasks create --runtime support-agent -e staging --prompt "Reply with ready."
introspection conversations get <task-id>
introspection conversations list --lookback 1h --filter recipe_git_commit_sha=<commit-sha>

<commit-sha> is the full SHA you pushed (git rev-parse HEAD); the last command lists conversations that commit served. A completed task alone is not a pass: read the conversation.

Other manifest keys: strict (unknown keys become errors), runtime.resources (CPU and memory requests and limits, and scratch storage), and runtime.github (Let the agent work on your code).

Limits

Not supported	Do this instead
Running `runtimes create` again	It returns `409`. Merge to ship a new version.
Rolling back with `runtimes delete`	It deletes every version. Yank instead.

Or ask your agent: “Deploy support-agent to Introspection and verify it in staging.”