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

# Cloud coding agents

> Start cloud coding agents with stable request IDs and inspect runner turns and conversation state.

Run cloud coding agents on a machine with the `agents`, `computer`, or devbox tool payload. Check the published [template catalog](https://docs.bead.run/templates/overview.md) before selecting an image.

## Prepare the directory

```bash theme={null}
bead exec ID 'mkdir -p /root/project'
```

Upload or clone your code there. A prompt's `cwd` must exist; the CLI defaults to `/root`.

## Send a prompt

Select a saved [credential profile](https://docs.bead.run/agents/credentials.md). Keep a stable request UUID before dispatch:

```bash theme={null}
bead prompt ID 'Inspect the project and report the failing tests' \
  --cwd /root/project --profile PROFILE_UUID \
  --request-id 72d04cb0-305e-49d0-8d88-d92a9b381fd3
```

The prompt API accepts `requestId`, `prompt`, `cwd`, optional `profileId`, and optional `model`. Use `--model` when you need a model supported by the installed runner and provider.

The CLI prints the request UUID before sending the prompt. Reuse it with the same prompt if the response is lost. A newly generated UUID identifies new work.

## Watch and inspect

```bash theme={null}
bead events ID --follow
bead status ID
```

Events show the turn's progress. `status` reads conversation and turn state through `GET /sandboxes/{id}/conversation`. Read terminal events before concluding the task succeeded.

MCP exposes `bead:runner_prompt`, `bead:runner_events`, and `bead:runner_status`. These use the same authenticated routes.

## Control the turn

You can [steer, interrupt, or answer approvals](https://docs.bead.run/agents/control.md) while work runs. Credential snapshot permission is explicit: `--allow-credential-snapshot` authorizes that policy for delivered credentials. Do not enable it for a source you do not intend to capture with credentials.

For a complete repository workflow, see [run an agent on your repository](https://docs.bead.run/use-cases/agent-on-repo.md). For browser and native application work, see [desktop use](https://docs.bead.run/agents/desktop.md).


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