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

# Launch an Agent

> Launch a catalog coding agent in a sandbox from the CLI, work in its terminal, and confirm the sandbox is destroyed.

`boxrouter launch codex --rm` creates a sandbox that already has the agent installed and attaches the
agent's terminal to yours. When you detach or the session ends, `--rm` requests sandbox deletion. The request returns
before deletion finishes, so the end state is `destroyed` only after you check it.

**Before You Begin:** A BoxRouter API key allowed to create sandboxes ([set up your account](https://boxrouter.ai/docs/setup.md)) and a client: [Python](https://boxrouter.ai/docs/python.md), [TypeScript](https://boxrouter.ai/docs/typescript.md), or the [CLI](https://boxrouter.ai/docs/cli.md#install) with `jq`. Run the CLI in an interactive terminal.

## Pick an Agent

```python Python theme={"theme":"css-variables"}
from boxrouter import BoxRouter

with BoxRouter() as client:
    for agent in client.agents.list().agents:
        print(agent.name)
```

```typescript TypeScript theme={"theme":"css-variables"}
import { BoxRouter } from '@boxrouter/sdk';

const client = new BoxRouter();
try {
  const page = await client.agents.list();
  for (const agent of page.agents) console.log(agent.name);
} finally {
  await client.close();
}
```

```bash CLI theme={"theme":"css-variables"}
boxrouter agents | jq -r '.agents[].name'
```

Output

```text theme={"theme":"css-variables"}
claude-code
claude-managed-agents-worker
codex
cursor
hermes
junie
kilocode
openai-agents-environment
openclaw
opencode
pi
t3code
```

Choose an agent name from the list. The
[Claude Managed Agents](https://boxrouter.ai/docs/integrations/claude-managed-agents.md) worker and
[OpenAI Agents API](https://boxrouter.ai/docs/integrations/openai-agents-api.md) environment run without a terminal.
[Catalog agents](https://boxrouter.ai/docs/launch/agents.md) covers interactive agents.

## Launch It

```python Python theme={"theme":"css-variables"}
from boxrouter import BoxRouter

with BoxRouter() as client:
    with client.sandboxes.launch("codex") as box:
        print("Sandbox:", box.id)
```

```typescript TypeScript theme={"theme":"css-variables"}
import { BoxRouter } from '@boxrouter/sdk';

await using client = new BoxRouter();
await using box = await client.sandboxes.launch('codex');
console.log('Sandbox:', box.id);
```

```bash CLI theme={"theme":"css-variables"}
boxrouter launch codex --rm
```

Output

```text theme={"theme":"css-variables"}
Launch queued
Launch running: create running
Launch running: create completed, setup running
Launch running: create completed, setup completed, setup running
Launch succeeded: create completed, setup completed, setup completed
Connected to terminal <TERMINAL_ID>. Sandbox <SANDBOX_ID>. Ctrl-] detaches; --rm requests sandbox deletion.
```

The output above is the CLI's. Its progress lines go to stderr while the sandbox prepares. Its
connection message identifies your sandbox; note the ID so you can check cleanup.

The interactive agents come preinstalled, so a launch typically takes a few seconds.
The first launch on a provider can take longer because of a one-time preparation.

The SDK waits until the launch is ready and returns the sandbox, the same handle `create` returns. It does
not attach your keyboard. The examples print `Sandbox: <SANDBOX_ID>` and leave the block, which requests
sandbox deletion. Call `box.open_terminal()` in Python or `box.openTerminal()` in TypeScript to start the agent in a terminal.

When the terminal attaches, the CLI starts
the agent, and Codex opens its sign-in screen because no model key was selected. To skip sign-in, launch
with a saved key ([Catalog agents](https://boxrouter.ai/docs/launch/agents.md#give-an-agent-model-access)).

Press `Ctrl-]` to detach the terminal when you are done.

## Confirm Cleanup

Replace `SANDBOX_ID` with the sandbox ID from the connection message.

```python Python theme={"theme":"css-variables"}
from boxrouter import BoxRouter

with BoxRouter() as client:
    print(client.sandboxes.get("SANDBOX_ID").state)
```

```typescript TypeScript theme={"theme":"css-variables"}
import { BoxRouter } from '@boxrouter/sdk';

const client = new BoxRouter();
try {
  console.log((await client.sandboxes.get('SANDBOX_ID')).state);
} finally {
  await client.close();
}
```

```bash CLI theme={"theme":"css-variables"}
boxrouter api sandboxes get SANDBOX_ID | jq -r '.state'
```

Output

```text theme={"theme":"css-variables"}
destroyed
```

Deletion is requested, not finished, when the terminal detaches, so the first check can print `destroying`.
Run the command again until it prints `destroyed`; only `destroyed` confirms cleanup. If the state stays
live, run `boxrouter destroy SANDBOX_ID` and check again. If the CLI cannot confirm cleanup, run the
`boxrouter destroy` command it prints.

Without `--rm`, the sandbox can keep running and billing past the end of its lifetime (300
seconds by default). Run `boxrouter destroy ID` and check its state when you no longer need it.

## If It Fails

| Message | Cause and Fix |
| - | - |
| `Launch requires an interactive terminal for this agent.` | Pipes and CI jobs have no terminal. Run the command in one. |
| `409 no_eligible_route` | No provider route can take the sandbox. Connect a provider key or buy Credits. |
| A phase shows `failed` | Launch requests sandbox deletion. Check cleanup and external effects before retrying. [Recover a preparation failure](https://boxrouter.ai/docs/launch/manifest.md#recover-a-preparation-failure). |

## Next Steps

> [card] [Launch Your Own Agent](https://boxrouter.ai/docs/launch/your-own-agent.md)
>
> Run your code with a catalog agent, or launch your own manifest.

> [card] [Supply an Agent's Secrets](https://boxrouter.ai/docs/launch/secrets.md)
>
> Pass a model key into the sandbox without putting it in a manifest.

> [card] [Choose a Catalog Agent](https://boxrouter.ai/docs/launch/agents.md)
>
> The agents you can launch without writing a manifest.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.