# Agents

> Start a coding agent, close the laptop, and let it work. An agent is an ordinary process on a machine you already pay for, so nothing it does is metered.

URL: https://prized.dev/docs/agents

## Start an agent [#start-an-agent]

```bash
prized agents run claude
```

This starts Claude Code in a detached tmux session named `claude` on the box, in your synced project, and prints the reattach command; closing the lid changes nothing. If the session already exists, `run` says so instead of starting a duplicate.

| Flag        | What it does                                                                                                                            |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--attach`  | Land in the session as it starts. Otherwise reattach later with `prized ssh -s claude`.                                                 |
| `--dir`     | Working directory. Defaults to your only synced project; a [clone](https://prized.dev/docs/sync#add-a-project) is not one, so pass `--dir ~/code/<name>`. |
| `--session` | Session name, for a second concurrent run of the same agent.                                                                            |
| `-- ARGS`   | Everything after `--` goes to the agent.                                                                                                |

> A working agent holds off [auto-pause](https://prized.dev/docs/boxes#auto-pause): its output and CPU count as activity. What a pause does to the process depends on the box size; see [Pause and resume](https://prized.dev/docs/boxes#pause-and-resume).

Copy out of an agent with its own copy action (Claude Code: select, then **c**) and the text lands on your clipboard through `prized ssh`; see [Copy out](https://prized.dev/docs/sessions#copy-out).

## The four agents [#the-four-agents]

| Agent                   | On the box                                 | Runs on the box |
| ----------------------- | ------------------------------------------ | --------------- |
| Claude Code (`claude`)  | Preinstalled.                              | Yes             |
| Codex CLI (`codex`)     | Preinstalled.                              | Yes             |
| Cursor (`cursor`)       | Installed on demand (`--install-cursor`).  | Yes             |
| ChatGPT app (`chatgpt`) | Drives `codex` over SSH from your machine. | No              |

`chatgpt` is a connection, not a process on the box: its tasks stop when your machine sleeps, so `prized agents run chatgpt` refuses; run `prized agents run codex` for a session that survives a closed laptop. Setting the app up is [Codex remote](https://prized.dev/docs/codex).

## See what is set up [#see-what-is-set-up]

```bash
prized agents ls
```

One row per agent: installed and signed in on your machine and on the box, MCP servers found, and where it is running. Read-only; takes `--json`.

## Hand credentials to the box [#hand-credentials-to-the-box]

```bash
prized agents handoff claude codex
```

Copies the named agents' sign-in and MCP config to the box, listing what would travel and asking first; `prized setup` runs the same step. Re-run it after changing MCP config. Claude requires a readable local sign-in to copy settings or MCP configuration; otherwise it leaves the box unchanged. `--gh` adds your GitHub CLI token and git identity; `--install-cursor` installs Cursor's CLI first. What travels per tool is in [Credentials](https://prized.dev/docs/credentials).

## Drive it remotely [#drive-it-remotely]

```bash
prized prompt --provider claude "fix the failing tests and run them again"
```

`prized prompt` runs the agent headless on the box, streams its events to your terminal, and exits with the verdict; `prized events` and `prized interrupt` follow and stop a run, and the same surface is an HTTP API. See [Prompt an agent remotely](https://prized.dev/docs/remote-agents).

## Several agents at once [#several-agents-at-once]

One session per agent by default (`claude`, `codex`, `cursor`), each in its own project via `--dir`. For two runs of the same agent, name the sessions:

```bash
prized agents run claude --session claude-api --dir ~/code/api
prized agents run claude --session claude-web --dir ~/code/web
prized ssh --ls
```

## Bring your own agent [#bring-your-own-agent]

The box is a normal Linux machine, so any CLI agent runs on it. Pick `other` in setup's agent step and it prints this pattern with your box's name filled in:

1. `prized ssh` opens the box, waking it if needed.
2. Install the agent's CLI in that shell.
3. Sign in there. The credential stays on the box disk, once per box; Prized never sees it.
4. Run it detached: `prized ssh -s myagent` opens a named session to start it in, or `tmux new-session -d -s myagent 'the-agent'` from any box shell. Reattach with `prized ssh -s myagent`.

For an agent that wants an API key, prefer a [Connector](https://prized.dev/docs/connectors) over a key in a file: the box gets a placeholder and the real value never touches its disk. The handoff and `prized agents run` do not know the agent; sessions work the same.

## Review from your machine [#review-from-your-machine]

For a synced project, the agent's edits stream into the folder on your machine as it works, so you read the diff in your own editor. This is why [sync](https://prized.dev/docs/sync#conflicts-the-box-wins) lets the box win conflicts: a stray local save should not revert an agent's work. A clone has no mirror; review it over git.

> An agent on your machine can do the Prized setup itself: paste the prompt from [Agent setup](https://prized.dev/docs/agent-setup). Every CLI command speaks JSON for scripts; see [CLI](https://prized.dev/docs/cli#for-agents-and-scripts).