---
name: deploy-try
description: "Give the owner a chat with the exact version built from a pushed branch's head commit, without changing what staging or production serves. Use when a deployed agent's branch should be tried before it lands, as after improve-propose."
metadata:
  min-cli-version: "0.87.0"
  next: ""
---

# Deploy: try

Let the owner talk to the change itself, not to whatever a lane serves. The platform makes a version of the agent's runtime from the branch; find the one built from the head commit and hand the owner a chat on it. This step changes nothing live, but the push may already have: a branch's version takes staging when staging is free.

## Before you start

You need the runtime's slug, a login to its project (`introspection whoami`), and the branch pushed to the runtime's repository (`git push origin pr/<name>`). On GitHub, open the pull request first: the platform makes the branch's version only once it is open.

## 1. Find the head commit's version

Look the version up by the head commit alone, never by branch:

```sh
introspection runtimes versions <slug> --sha $(git rev-parse pr/<name>) \
  --query "[0].[id, recipe_ref, image_build_status]" -o json
```

It prints `null` until the platform has made the head's version. Read again every 20 seconds for about two minutes. A `pending` version is found: go on at once, never wait for it to build.

Still `null` after that: the platform failed to make a version, so stop. Never ask the owner how to go on; tell them it is a platform problem, with the pull request's link or the branch's name, and offer to report it with `introspection report-error`, naming the runtime, the commit and the branch. In a platform task, record it on the task's issue too, as `platform-issues` says, so the platform's investigation picks it up.

## 2. Check its connections in staging

The chat runs with staging's connections, and a change can declare a server staging lacks:

```sh
introspection bindings mcp list --runtime-id <version-id> --environment staging --query "[].[mcp_server_id, connected]"
```

A required server not connected there: tell the owner which, go to `deploy-connect` to connect it for staging, then come back. Never hand over a link that can't work.

## 3. Build the link

```sh
introspection open --runtime <slug> --print
```

Add the version to that URL, never a path you put together otherwise: `<that URL>/recipe?runtime_id=<version-id>`. That Recipe Chat runs this exact version in staging, recorded apart from production's conversations.

## 4. Hand it to the owner

With four things to know:

- **What staging serves:** read it, never assume it is unchanged: `introspection runtimes get <slug> --resolve --query staging_pin.ref`. When it names the version's `recipe_ref`, the push put the branch in staging, not this step, and staging keeps serving it until the owner unpins it once the branch lands (deploy-create). Production serves `main` either way.
- **The first reply may be slow:** a `pending` version is built by its first message.
- **Start a fresh chat from the link for each try:** after a restart, such as an idle timeout, a chat's next turn runs whatever staging serves.
- **Each later push has its own version:** find it again and give the new link.

## Guardrails

- **Never pin, unpin or yank a version, or push to `main`,** to make one appear: the owner lands the branch through its pull request.
- **Never start the chat as the owner:** the link is theirs to open.

## Done when

- The owner has the link to chat with the version built from the branch's head commit, and staging has every server it requires. Improve ends here.
