---
name: deploy-create
description: "Put an agent on the platform: register or create its repository, push the reviewed branch and create its runtime, or for a change pin staging to the branch's version. The second step of deploy."
metadata:
  min-cli-version: "0.81.0"
  next: "deploy-connect deploy-test"
---

# Deploy: runtime

Take the agent from this machine to a running version on the platform. The owner says yes to each step that leaves this machine.

## Before you start

deploy-connect has checked the CLI, the login and the scopes, knows whether this is a first deploy or a change, and has connected the required servers. If it hasn't run, start there. Each step below that leaves this machine needs the owner's yes, as it says.

## 1. Choose the repository

Use the choice onboarding or the owner already made. Otherwise offer a new private hosted repository first, which needs nothing set up, then any the clone or project already has:

```sh
git remote -v                             # where the clone already pushes
introspection repositories list -o table  # one the project has
```

Look for GitHub repositories (`introspection integrations repositories --type github`) only when the owner asks for GitHub. Never pick for the owner.

**Ask everything this deploy needs in one turn,** with one `ask_user_question` per decision: the repository; for a first runtime, the model provider and, with several manifests, which one, as [before the first runtime](references/repository.md#before-the-first-runtime) says; then the go-ahead to create or register the repository, push and create the runtime, naming each. A repository onboarding chose isn't asked again. Record the answers and the go-ahead in Part B's change log and [the record](references/record.md).

Then create or register it as [the repository reference](references/repository.md) says. A repository the GitHub integration doesn't reach needs the GitHub App on its organization first: say so and stop. A hosted one is ready to push when `repositories list` shows it `ready`.

## 2. Push and land on `main`

A runtime follows `main`: production serves it and each push builds a version. Land the reviewed branch with a push (a login can push but can't merge):

```sh
git push origin pr/<name> pr/<name>:main
```

A Recipe already on `main` needs no push.

**Which git access:** try, don't ask.

- In an Introspection sandbox (`INTROSPECTION_PREINSTALLED` is set), Git is already set up for the project's hosted repositories: set `origin` as [the repository reference](references/repository.md) says and push. Never run `git-credential configure` there.
- On the owner's machine, if `ssh -T git@github.com` greets them (it exits 1), set `origin` to `git@github.com:<owner>/<name>.git`.
- Otherwise, run once:

  ```sh
  introspection git-credential configure
  ```

If the push is refused, stop and show the owner the exact error, with the two fixes: add an SSH key to their GitHub account, or give the organization's GitHub App access to the repository. Never force-push or rewrite history.

## 3. Create the runtime

BYOK's LLM binding and a chat connector need the runtime: deploy-connect connects them after this step.

<!-- rule: R-first-runtime-prod-bootstrap -->

### A first runtime

With the model provider and the go-ahead from step 1:

```sh
git fetch origin && git checkout -B main origin/main && git remote set-head origin --auto
introspection runtimes list --query "[].slug"   # still none
introspection runtimes create --yes
```

With several manifests, add `--manifest .introspection/<the one the owner chose>.yaml`. The first version is `main`'s commit, live in staging and production at once: nothing to pin. If it warns it couldn't read the default branch, the clone isn't on `main` with its head set: fix that and create again.

<!-- rule: R-no-second-runtime-group -->

### An agent that already has a runtime

A later change, or improve-propose's branch. Never run `runtimes create` again (it splits the agent's history), and never push to `main` (it goes live in production). Push only the branch, as `deploy-try`'s "Before you start" says; the owner lands it through its pull request:

```sh
git push origin pr/<name>
introspection runtimes versions <slug> --sha $(git rev-parse pr/<name>) \
  --query "[0].[id, image_build_status]"   # null until the platform has made it
introspection runtimes pin <version-id> --sha <head-commit>    # once ready: staging runs it
```

After every later push to the branch, pin the new head commit's version the same way.

**Still `pending` after about five minutes:** a branch's version builds only once it claims a free staging lane. Read who holds staging:

```sh
introspection runtimes get <slug> --resolve --query staging_pin
```

When another ref holds it, tell the owner which one and offer, with the question tool, to unpin it (`introspection runtimes unpin <id> --yes`, production's version id from `--resolve --query environments.production.version_id`); don't blame the data plane. Only when staging is free and the version still hasn't started does step 4's diagnosis apply. If no version of the head commit appears, stop as deploy-try's step 1 says. deploy-test runs on that version (`--runtime-id <version-id>`). Once the pull request has landed:

```sh
introspection runtimes unpin <version-id>   # staging follows main again
```

## 4. Wait for the version

Wait for the commit you pushed, not the newest row: a push can make more than one version of a commit, and one may sit `queued` while another is `ready`.

```sh
introspection runtimes versions <slug> --query "[?git_commit_sha=='<sha>'].[id, image_build_status]"   # the full sha, git rev-parse HEAD
```

It's deployed once any version of the commit is `ready`. In a first build, hand over the chat link only once its smoke tests and review have passed too. Check between other work rather than in a `sleep` loop, and stop after about five minutes with none `ready`, telling the owner what you see.

- **`failed`:** show the owner the message and stop.
- **"warmup was not delivered":** the platform couldn't reach the data plane. Once it's up, make a new version (a push to `main`, or a retry from the Runtime's page).
- **`pending` with no build metadata after about a minute** (a branch's version: check who holds staging first, as above): the version hasn't started. Stop and tell the owner.

Write the runtime, the version id and its commit in [the record](references/record.md):

```sh
introspection runtimes versions <slug> --query "[0].[id, git_commit_sha]"
```

<!-- rule: R-registration-not-readiness -->

A ready version can still be missing connections its Recipe needs: deploy-connect is next for those.

## Guardrails

- **The owner chooses every target:** the repository, its name, whether to push, the runtime.
- **Deploy what passed `check`:** push the branch as it is. A fix from the smoke tests or the review is a new commit, pushed the same way; a change found here goes back through draft.
- **Never force-push, rewrite history or delete a branch.** Remove a file that shouldn't have been committed with a new commit, and tell the owner.
- **Never handle credentials:** login holds them; one the platform lacks is the owner's to set up.

<!-- rule: R-runtime-resources-from-observation -->

- **Leave runtime resources unset** unless a run showed a need.

## Done when

- The Recipe is on `main` in the repository the owner chose.
- A runtime serves it, its version's image is ready, and the record names the runtime, version and commit.
- **A first deploy** goes back to `deploy-connect` for what needed the runtime (BYOK, a chat connector, a per-environment binding), then `deploy-test`; **a change** goes to `deploy-test`, on the pinned version.
