# Write a preview manifest

At the end of this guide, your repository has a `volobox.app.yaml` that Volobox can start as a branch preview, and `verify` steps that check the pull request of agent work on a task before it opens. Anyone who can start a coding session on the repository can do this; you do not need to be an administrator.

## Before you begin

- The repository registered in Volobox, and access to start a coding session on it.
- The commands that install, build and start your app, and the ports it listens on.
- The names of the secrets the app needs (a connection string, a license key). Their values are saved in Volobox, never in the manifest.

Most repositories need only `volobox.app.yaml` at the root. Add `volobox.workspace.yaml` only when the repository has several previewable apps or needs other repositories cloned beside it. Every key is in the [Preview manifest reference](/docs/preview-manifest).

## Let the coding agent write it

A coding session starts without a manifest, so the agent can write one for you.

1. Open a coding session on the repository.
2. On the session's **Runner** tab, select **Generate in Volobox**. The composer fills in `/init-preview-manifest` in **Agent** mode. Review it and send it; Volobox does not send it for you.
3. The agent reads the repository (scripts, project files, compose files, the README, CI checks), writes the files, and proves they run: it runs the `prep` and `init` steps, starts each service once with its real command, checks that it answers, fixes what fails, and stops what it started.
4. When the manifest has no problems, a **Preview manifest ready** card follows the agent's reply. Select **Start preview** on the card.

You can also start from **Previews** in the **Coding** side panel, or from a branch preview with no manifest: select **Create with coding session**. The new session is named **Add preview manifest** and its prompt is already `/init-preview-manifest`.

**Runner** lists the app at once, before anything is pushed, because it reads the manifest from the session's own files while the session's sandbox runs.

## Or write it in your own editor

1. Select **Download skill for your editor** on **Previews**, on a branch preview without a manifest, or on **Runner** when the manifest is missing.
2. Unzip the archive. It contains `SKILL.md`.
3. Put that folder in your editor's skill directory (Cursor, Claude Code, or another tool that reads agent skills).
4. Ask your editor's agent to write `volobox.app.yaml` for the repository.

To write it by hand, start from the smallest file that runs the app:

```yaml title="volobox.app.yaml"
name: my-app

prep:
  - run: npm ci
    inputs: [package-lock.json]

services:
  - name: web
    kind: command
    command: npm run dev -- --host 0.0.0.0 --port 5173
    port: 5173
    primary: true
    dependsOn: []
```

Keep these rules in mind:

- Restore and install go in `prep`. Migrations, seeding and anything that needs a preview address (`${preview.origin(name)}`) go in `init`.
- Mark exactly one service `primary: true`, and give each `command` service a `port`. Bind servers to `0.0.0.0`.
- Every service must answer its health check, or the preview fails. Mark a service the app can run without `optional: true`.
- List secrets by name under `env` and pass them to a step or service as `${env.NAME}`.

## Check the manifest

1. In a coding session, ask the agent to run `volobox manifest check`. It reports YAML errors, keys Volobox ignores (with the key you probably meant), values of the wrong shape, and `dependsOn` names that match nothing.
2. After any **Agent** turn that changes the manifest, Volobox checks it for you. A **Volobox found … problems in the preview manifest** card appears when something is wrong; send your next message as usual ("Fix those") and the agent receives the findings with it.
3. Read the **Improve this preview** note under the app picker on **Runner** or a branch preview. It points at the step to move or remove, or the service whose settings contradict each other. **Fix with agent** writes one prompt that covers every suggestion.

`volobox manifest check` checks keys and shape. Only running the preview shows that the commands, connection strings and health paths are right. See [Sandbox command](/docs/sandbox-cli).

## Start a branch preview

1. Commit and push the manifest. **Previews** and branch previews read it from the pushed branch.
2. Open **Previews** in the **Coding** side panel, or the project's **Code** → **Previews** tab.
3. Find the repository and branch, select the app, and select **Start**.
4. Follow **Starting preview**. **Setup steps** lists every `prep` and `init` step: the ones running, done, skipped as up to date, and still to come.
5. When the preview is **Running**, open the service links it shows.

If the preview needs secrets that are not saved yet, add them under **Secrets** in your personal settings, or ask an administrator to add them for the organization, then select **Check secrets again**.

## Add verify steps

`verify` steps are the build, test and lint commands an agent's change must pass before Volobox opens the pull request of agent work on a task.

1. Add a `verify` list to `volobox.app.yaml` with a few fast commands.
2. Reuse what `prep` installed: `dotnet build --no-restore` or `npm run lint`, not a second restore or `npm ci`.
3. In a repository with several apps, give each step `inputs`. The step then runs only when the branch changed a file matching one of them, relative to the step's `cwd`. A step without `inputs` always runs.
4. Commit the manifest.

```yaml
verify:
  - dotnet build --no-restore
  - dotnet test --no-build
  - run: npm run lint
    cwd: web
    inputs: ["src/**"]
```

`verify` steps never run on **Start preview** or in the background. They cannot use `${preview.*}` placeholders, because no preview runs during the checks, and a step receives only the secrets it names (`$NAME` in its command, or `${env.NAME}` in its own `env`). Keep end-to-end suites and anything that needs the network out of `verify`.

## Check that it works

- The branch preview reaches **Running**, which means every required service answered its health check.
- The next pull request of agent work on a task has a **Verification** section listing each check with its result and time, instead of **Not checked**.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| **Start preview** and **Sandbox environment** are missing | The branch has no `volobox.app.yaml` Volobox can find. Write one at the root, or list the app in a root `volobox.workspace.yaml`. |
| A setting seems to do nothing | Volobox ignores keys it does not know, such as `depends_on`. Keys are camelCase; the **Improve this preview** note lists each ignored key and the one you probably meant. |
| The preview failed although its main page was answering | Every service has to answer its health check, not only the primary one. Open **Show log** under the failed service, fix it, or mark it `optional: true`. |
| An API counts as healthy while it answers errors | `expectStatus` defaults to `any`, which accepts any HTTP answer. Write `expectStatus: 2xx`. |
| `prep` steps run one after another although they do not need each other | Give each step a `name` and a `dependsOn` listing the earlier steps it needs (`[]` for none). |
| Services start one after another | Give each service a `dependsOn` listing only what it needs (`dependsOn: []` for none). |
| **Runner** shows **Latest changes not applied** | A `prep` step failed for the newest commit, and the preview keeps serving the previous build. Fix the error shown, then select **Rebuild**. |
| A .NET preview rebuilds on every start | Build in the last `prep` steps with `dotnet build`, and start `init` and services with `dotnet run --no-build`. |
| A `verify` step fails with a message about preview addresses | `verify` runs without a preview. Move that check out of `verify`. |
| **Verification** says the checks could not finish | They ran out of time, lost the sandbox, or could not read a secret. That is not a verdict on the code. Keep the checks short. |

## Next steps

- [Preview manifest reference](/docs/preview-manifest)
- [From a task to a pull request](/docs/task-to-pull-request)
- [Sandbox command](/docs/sandbox-cli)
