# Coding agents

> Run Claude Code, Codex or OpenCode on a task in a sandbox with cloudex prompt and reattach with cloudex attach, or without a terminal with cloudex agents, the API and the SDKs.

Every sandbox has Claude Code, Codex and OpenCode installed. `cloudex prompt` gives one of them a task in a tmux session inside the sandbox, so it keeps working after you disconnect. [`cloudex agents`](#without-a-terminal) and the [SDKs](#from-code) start agents with no terminal instead: you follow what they do, and send them follow-ups.

## Sign in once

Sign in to each agent once in a sandbox:

```sh
cloudex ssh
claude      # or: codex, opencode
```

Follow the agent's own sign-in steps. The login is saved in your home directory with the sandbox's disk, so it survives stop and resume, it's in backups, and [forks](https://cloudex.build/docs/forks.md) copy it. A new sandbox made with `cloudex new` needs signing in again.

To skip signing in, store a provider's API key with `cloudex keys set`: Anthropic for Claude Code, OpenAI for Codex, and any of them for OpenCode, which also works with OpenRouter, Google, Groq, Mistral, xAI and DeepSeek. Every sandbox then uses it, and the key itself stays outside them. While a provider's key is stored, its agent uses the key even where someone has signed in with a subscription. See [Provider keys](https://cloudex.build/docs/keys.md).

For an agent to clone, push and open pull requests on GitHub, give the sandbox a token with `cloudex env set GH_TOKEN=...`; `git` and `gh` use it. See [Settings](https://cloudex.build/docs/settings.md#github).

## Give an agent a task

```sh
cloudex prompt "make the tests pass"
cloudex prompt web --agent codex "add a dark mode"
cloudex prompt --agent opencode "write a README"
cloudex prompt -d "upgrade the dependencies"
```

`cloudex prompt` starts the agent in a new tmux session in the home directory, then attaches your terminal to it. Name the directory to work in as part of the task if the code isn't in the home directory.

| Flag | Default | Effect |
|---|---|---|
| `--agent` | `claude` | `claude`, `codex` or `opencode` |
| `-d`, `--detach` | off | Start the agent without attaching |

Press Ctrl-b d to detach. The agent keeps working. When it finishes, the session drops to a shell and stays open until you exit it.

Agents run without their own permission prompts: Claude Code with `--dangerously-skip-permissions`, Codex with `--dangerously-bypass-approvals-and-sandbox` and OpenCode with `--auto`. The sandbox is the boundary. On a [node](https://cloudex.build/docs/nodes.md) under plain Docker, that boundary is weaker: give agents there only work you'd trust them with on the machine itself. Claude Code's warning about this mode is accepted for you, by `"skipDangerousModePermissionPrompt": true` in `~/.claude/settings.json`; set it to `false` to be asked. Don't put anything in a sandbox that the agent shouldn't be able to read or change.

## Reattach

```sh
cloudex attach                       # the newest agent session
cloudex attach web agent-1029-142501 # a given session in a given sandbox
```

Sessions are named `agent-<month><day>-<time>`. To list them:

```sh
cloudex exec -- cloudex-agent list
```

You can also reach a session from a shell in the sandbox with `tmux attach -t <session>`.

## Long tasks

An agent session counts as activity for [idle stop](https://cloudex.build/docs/sandboxes.md#idle-stop) while it's producing output: once a minute, the sandbox checks for agent sessions with output in the last 10 minutes. With [provider keys](https://cloudex.build/docs/keys.md), the agent's calls to its provider count too. An agent that's waiting for your answer doesn't count, so the sandbox stops after `--idle`.

Cloudflare's [6-hour limit](https://cloudex.build/docs/sandboxes.md#the-6-hour-limit) still applies when nothing is connected. For a task that may run longer, keep a connection open, for example `cloudex attach` in a terminal, or run it on a [node](https://cloudex.build/docs/nodes.md), which has no such limit.

Stopping a sandbox ends the agent. After `cloudex resume`, its files and history are on disk, but the session has to be started again.

## Without a terminal

`cloudex agents` runs an agent with no terminal, one turn per message, and prints what it does: its messages, the commands it runs with the end of their output and their exit code, the files it reads and changes, and how each turn ends, with its time and, for Claude Code, its cost.

```sh
cloudex agents start "make the tests pass"
```

```text
Started ag-1a2b3c4d (claude). Ctrl-C stops following; the agent keeps working.
> make the tests pass
I'll run the tests first.
$ npm test
  … 38 more lines
  ✕ adds negative numbers
  Tests: 1 failed, 11 passed
  Time: 1.9s
  exit 1
Read /home/cloudex/app/src/math.ts
Edit /home/cloudex/app/src/math.ts
$ npm test
  … 40 more lines
  Tests: 12 passed
  Time: 1.8s
All 12 tests pass now.
-- turn 1 done in 48s, $0.21
```

| Command | Effect |
|---|---|
| `cloudex agents [sandbox]` | List the sandbox's agents, their state and last message |
| `cloudex agents start [sandbox] <task>` | Start an agent and follow it until it finishes; `-d` only starts it |
| `cloudex agents logs [sandbox] [agent]` | Print what an agent did; `-f` keeps following while it works |
| `cloudex agents send [sandbox] [agent] <message>` | Send a follow-up and follow it; `--interrupt` steers |
| `cloudex agents interrupt [sandbox] [agent]` | Stop the running turn and drop queued messages |

Commands that take an agent use the sandbox's most recently active one when you leave it out. `start` takes `--agent codex` or `--agent opencode`, `--model` and `--cwd`, where `app` and `~/app` both mean `/home/cloudex/app`, and a task of `-` is read from standard input. Following ends when the agent has nothing left to do, with the last turn's exit code; Ctrl-C stops following and leaves the agent working. With `--json`, `logs` prints the raw events, one per line.

- **Turns.** Each message is one turn: `claude -p --output-format stream-json`, `codex exec --json` or `opencode run --format json`, run as the `cloudex` user in a login shell, so [provider keys](https://cloudex.build/docs/keys.md) and [settings](https://cloudex.build/docs/settings.md) work. Later turns resume the same conversation.
- **Messages.** A message sent while a turn runs waits for it. With `--interrupt`, the running turn stops and queued messages are dropped first, which is how to steer an agent. `interrupt` only stops.
- **On the disk.** An agent and its conversation live in `~/.cloudex/agents/<id>` and in the agent's own session files, so they survive stop and resume, and a [fork](https://cloudex.build/docs/forks.md) gets a copy it can take somewhere else. A turn that's running when the sandbox stops, or is forked, ends as interrupted; send a message to carry on.
- **Activity.** A running turn counts as activity for [idle stop](https://cloudex.build/docs/sandboxes.md#idle-stop) while the agent has written events in the last 10 minutes.

## OpenCode

OpenCode works with many providers, so it takes its model as `provider/model`, such as `anthropic/claude-sonnet-5-5` or `openrouter/deepseek/deepseek-chat`. `opencode models` in a sandbox lists them.

```sh
cloudex agents start --agent opencode --model anthropic/claude-sonnet-5-5 "fix the flaky test"
```

Without `--model`, OpenCode picks a model from the providers it has a key or a login for. Cloudex gives it a `~/.config/opencode/opencode.json` that leaves out OpenCode's own free models, which it would otherwise pick and soon run out of; edit or delete that file to use them, or to set a default model of your own. Cloudex writes the file only when there isn't one already.

Each [`cloudex agents`](#long-tasks) turn runs `opencode run --standalone`, with OpenCode's server as part of the turn, so an interrupt stops the commands it started too.

## From code

The [SDKs](https://cloudex.build/docs/sdk.md) and the [HTTP API](https://cloudex.build/docs/api.md#agents) drive the same agents from programs.

```ts
const agent = await box.prompt("make the tests pass", { cwd: "app" }); // { agent: "codex" } for Codex, "opencode" for OpenCode
for await (const e of agent.events()) {
  if (e.type === "event") console.log(e.event); // the agent's own JSON events
}
console.log(agent.lastMessage);

await agent.send("now update the docs"); // waits for a running turn
await agent.send("stop, fix the build first", { interrupt: true });
await agent.wait();
```

A turn's log is a `prompt` event, then the agent's own JSON events (`event`) and any other output lines (`output`), then an `end` with the exit code and, if the turn failed, why. `lastMessage` is the agent's final message in the last finished turn. An agent started from code shows up in `cloudex agents`, and the other way round.

Agents without a terminal don't appear in `cloudex attach`, and `cloudex prompt` sessions don't appear in `cloudex agents`. Both use the same agent logins and settings.

## On a node

Agents work the same in a sandbox on a [node](https://cloudex.build/docs/nodes.md), with [provider keys](https://cloudex.build/docs/keys.md) too. Their calls to the provider go through the node's agent and your deployment, which adds the key, so the key never reaches the node. The node's agent does see the prompts and the provider's answers in plain text; see [What a node can see](https://cloudex.build/docs/nodes.md#what-a-node-can-see).
