# The volobox command in coding sandboxes

Every coding session's sandbox has a `volobox` command. A coding agent uses it to read Volobox's own guide, check a preview manifest, and see the state of the session's preview. The command only reads: it works without the network, cannot sign in to Volobox, and changes nothing in Volobox. This page lists the subcommands documented for it and the line an agent writes when the work needs another repository.

## Who can run it

| Composer mode | OpenCode | Cursor, Codex, Claude Code |
| --- | --- | --- |
| **Agent** | Runs `volobox` | Runs `volobox` |
| **Ask** and **Plan** | Runs no commands in these modes; reads the same material as files instead | Run `volobox`, because it only reads |

Claude Code sessions run on your own machine; the command is the same there.

You rarely type the command yourself. Ask the agent in your own words ("Check volobox.app.yaml against Volobox's manifest rules and fix what is wrong") and it runs what it needs.

## Commands

| Command | What it prints |
| --- | --- |
| `volobox docs search <words>` | The sections of the Volobox guide that match the words. |
| `volobox docs read <page>` | One page of the Volobox guide, by section. |
| `volobox manifest check` | Problems in the repository's preview manifest: YAML errors, keys Volobox ignores (with the key you probably meant), values of the wrong shape, and `dependsOn` names that match nothing. |
| `volobox manifest reference` | Every preview manifest key and what it does. |
| `volobox preview status` | The session's preview and the state of each of its services. |
| `volobox preview logs <service>` | The recent log of one preview service, with credential-shaped text masked. |

The guide the command reads is the one for the Volobox version your workspace runs. It is replaced on the next turn after an upgrade, so it can differ for a moment from what you read elsewhere.

### Check a manifest

```bash
volobox manifest check
```

`volobox manifest check` checks keys and shape, not behavior: it cannot tell that a command, a connection string or a health path is wrong. A manifest that passes still has to be run once (the `/init-preview-manifest` command has the agent do that).

Volobox also runs this check by itself after an **Agent** turn that changed `volobox.app.yaml` or `volobox.workspace.yaml`, whether or not the turn committed. When it finds problems, a **Volobox found … problems in the preview manifest** card appears under the agent's reply, and your next message carries the findings to the agent.

### Read a preview log

```bash
volobox preview status
volobox preview logs api
```

The service name is the `name` of a service in the manifest. The agent can read a preview's state and logs but cannot start or stop a preview; you do that from **Runner**.

## Repository needed

A coding agent works only in the session's repository and its companion repositories. When it finds that the work needs a change in a repository it cannot reach, it writes a line of its own that starts with `Repository needed:`, names the repository as `owner/name`, and gives the reason in one short sentence after a dash, then finishes what it can in the current repository.

```text
Repository needed: example-org/billing-api - The invoice total is computed in the billing API.
```

Volobox takes that line out of the reply and shows a **This needs another repository** card instead. From the card, the session's owner chooses **Continue in {repository}** to open a new session on that repository, which starts from a handoff of the work so far. Everyone else reads that the session's owner can continue it there.

## What the command cannot do

- Read tasks, chats, other projects or other repositories. The agent sees only the session's sandbox, plus the linked task's new title and description when the task is edited after the agent started. Paste anything else it needs into your message.
- Change Volobox settings, start a preview, or post a comment.
- Be committed. The material it reads lives outside the repository.

## Related

- [Preview manifest reference](/docs/preview-manifest)
- [Write a preview manifest](/docs/write-preview-manifest)
- [Guide coding agents](/docs/guide-coding-agents)
- [Coding sessions and the task-to-PR loop](/docs/coding)
