Launch an Agent - BoxRouter

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) and a client: Python, TypeScript, or the CLI with jq. Run the CLI in an interactive terminal.

Pick an Agent

from boxrouter import BoxRouter

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

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();
}

boxrouter agents | jq -r '.agents[].name'

Choose an agent name from the list. The Claude Managed Agents worker and OpenAI Agents API environment run without a terminal. Catalog agents covers interactive agents.

Launch It

from boxrouter import BoxRouter

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

import { BoxRouter } from '@boxrouter/sdk';

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

boxrouter launch codex --rm

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). Press Ctrl-] to detach the terminal when you are done.

Confirm Cleanup

Replace SANDBOX_ID with the sandbox ID from the connection message.

from boxrouter import BoxRouter

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

import { BoxRouter } from '@boxrouter/sdk';

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

boxrouter api sandboxes get SANDBOX_ID | jq -r '.state'

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.

Next Steps

Launch Your Own Agent

Run your code with a catalog agent, or launch your own manifest.

Supply an Agent's Secrets

Pass a model key into the sandbox without putting it in a manifest.

Choose a Catalog Agent

The agents you can launch without writing a manifest.