# Preview manifest reference

A preview manifest is a YAML file in your repository that tells Volobox how to prepare, start and check your app. Branch previews and a coding session's **Runner** start the app from it, and agent work on a task runs its `verify` checks before the pull request opens. This page lists every key. For a walkthrough, see [Write a preview manifest](/docs/write-preview-manifest).

## Files

| File | Where | When you need it |
| --- | --- | --- |
| `volobox.app.yaml` | The repository root, or the folder of each app | Always. One file describes one previewable app. |
| `volobox.workspace.yaml` | The repository root | Only when the repository has more than one previewable app, or needs other Git repositories cloned beside it. |

Volobox lists the `volobox.app.yaml` at the repository root, or the apps that a root `volobox.workspace.yaml` lists. A `volobox.app.yaml` in a subfolder is found only through a workspace manifest.

A coding session can start without a manifest. Starting a preview needs one.

> **Note:** Keys are camelCase. Volobox ignores keys it does not know (such as `depends_on` instead of `dependsOn`) and names each ignored key, with the key you probably meant, in the **Improve this preview** note. Never write secret values in a manifest: `env` lists names only.

## `volobox.app.yaml` top-level keys

| Key | Type | Required | Meaning |
| --- | --- | --- | --- |
| `version` | integer | no | Manifest schema version. `1` is the only version. |
| `name` | string | yes | The app's id, unique in the repository. The app picker shows it. |
| `description` | string | no | Label shown in the app catalog. Does not affect how the app runs. |
| `group` | string | no | Grouping label in the app catalog. Does not affect how the app runs. |
| `env` | list of strings | no | Names of the secrets the app needs. Values come from the secrets saved in Volobox, never from the file. |
| `prep` | list of steps | no | Cacheable setup: restore, install, build. See [prep](#prep). |
| `init` | list of steps | no | Steps that run on every **Start preview**, before the services. See [init](#init). |
| `verify` | list of steps | no | Checks an agent's change must pass before its pull request opens. See [verify](#verify). |
| `services` | list of services | yes | The processes the preview runs. At least one, and exactly one marked `primary`. See [Services](#services). |
| `preview` | object | no | Start timeout, idle timeout, background preparation and parallel start. See [preview](#preview). |

`image` and `completion` are accepted for compatibility. Write setup work in `prep` instead of `image.setup`; `completion` currently has no effect.

## Steps

`prep`, `init` and `verify` are lists of steps. A step is either a bare string, which is the command, or an object:

```yaml
prep:
  - npm ci
  - run: dotnet restore
    cwd: src
    inputs: ["**/*.csproj"]
```

| Key | Type | Applies to | Meaning |
| --- | --- | --- | --- |
| `run` | string | all | Shell command to run. |
| `cwd` | string | all | Working directory, relative to the app folder (the repository root for a root app). |
| `env` | map | all | Environment variables for this step. Reference a secret as `${env.NAME}`. |
| `inputs` | list of globs | `prep`, `verify` | Globs relative to `cwd`. Their meaning differs per list; see below. |
| `onlyForInit` | boolean | `prep` | The step is needed only by `init` (for example the build of a database migrator), so it runs only when `init` runs. Such steps must come last. |
| `name` | string | `prep` | The name other steps use in `dependsOn`. |
| `dependsOn` | list of names | `prep` | Earlier steps this one needs. `[]` for none. |

### prep

`prep` steps run in the background once the session's workspace is ready, and **Start preview** finishes any that have not run before it starts `init`. Put restore, install and build here, never in `init`.

- A step re-runs when its command or its `inputs` change. Without `inputs`, Volobox watches the lockfiles and project files under the step's `cwd`. `inputs: []` re-runs the step only when its command changes.
- Without any `dependsOn`, steps run one after another, and a step that re-runs also re-runs every step after it. Put the step whose inputs change most often last.
- Once any step declares `dependsOn`, steps whose dependencies are done run side by side, and a re-run step re-runs only the steps that need it. A step can wait only for an earlier one; a name that matches no earlier step is ignored.
- `prep` cannot use `${preview.*}` or `${service.*}` placeholders, because preview addresses do not exist yet.
- In the background, a step receives only the secrets it names: `$NAME` in its command, or `${env.NAME}` in its own `env`. Name a secret a tool reads implicitly, such as `NPM_TOKEN` for a private registry, in the step's `env`.
- Set `preview.backgroundPrep: false` to run `prep` only when someone starts a preview.

### init

`init` steps run on every **Start preview**, after `prep` and before the services. Put database migrations, seeding, and anything that needs a preview address (`${preview.origin(name)}`) here. Give a migrator its connection string explicitly in the step's `env`.

### verify

`verify` lists the checks an agent's change must pass before Volobox opens the pull request of agent work on a task: a build, the unit tests, a lint or type check.

- The steps run in order in the session's sandbox after the agent's turn. The first failure stops the run, and the agent gets a turn to fix it before the checks run again. If they still fail, the pull request opens with the failure marked.
- They never run on **Start preview** and never in the background.
- `inputs` on a `verify` step means "run only when a file the branch changed matches one of these globs" (relative to the step's `cwd`). A step without `inputs` always runs. In a repository with several apps, scope each app's checks to its folder this way.
- A step cannot use `${preview.*}` or `${service.*}`: no preview runs during `verify`, so such a step fails.
- A step receives only the secrets it names (`$NAME` in its command, or `${env.NAME}` in its own `env`), and their values are hidden in the output Volobox keeps.
- Reuse what `prep` installed: write `dotnet build --no-restore` or `npm run lint`, not a second restore or `npm ci`. The whole run has a time budget, so keep checks fast and deterministic and leave out end-to-end suites.

The pull request's **Verification** section shows each check with its result and time, the commit they ran at, and the end of a failing check's output. A repository without `verify` steps gets **Not checked**.

## Services

Each entry in `services` is one process of the preview.

| Key | Type | Meaning |
| --- | --- | --- |
| `name` | string | Service name, unique in the manifest. Used by `dependsOn` and `${preview.origin(name)}`. |
| `kind` | string | `command` (default), `compose` or `aspire`. |
| `cwd` | string | Working directory, relative to the app folder. |
| `command` | string | Shell command that starts a `command` service. Bind the server to `0.0.0.0`. |
| `port` | integer | Port the service listens on. Gets a preview address unless `expose` is `false`. Every `command` service needs one. |
| `healthcheck` | string or object | A path such as `/health`, or an object (below). Defaults to `/` when `port` is set. |
| `dependsOn` | list of names | Services that must be healthy before this one starts. `[]` starts it at once. A service without `dependsOn` waits for every service listed before it. |
| `restartPolicy` | string | `watch` (default, no restart), `on-change` (restart when committed files match `watchPaths`) or `manual`. |
| `watchPaths` | list of globs | For `on-change`: globs whose committed changes restart the service. |
| `env` | map | Environment variables. Reference a secret as `${env.NAME}` and a service address as `${preview.origin(name)}`. |
| `previewEnv` | object | A file written before the service starts, holding preview addresses for a client app (below). |
| `primary` | boolean | The service the preview opens. Mark exactly one. |
| `optional` | boolean | The preview can run without it: its failure is shown but does not fail the preview. Ignored on the primary service. |
| `expose` | boolean | Whether the port gets a preview address. Default `true` when `port` is set. |

A preview is **Running** only when every service that is not `optional` answers its health check, not only the primary one.

### healthcheck object

| Key | Type | Default | Meaning |
| --- | --- | --- | --- |
| `path` | string | `/` | HTTP path to probe. Use a path the app really maps. |
| `timeoutSeconds` | integer | `120` | Seconds to wait for a healthy answer. |
| `intervalMs` | integer | `1500` | Milliseconds between probes. |
| `expectStatus` | string | `any` | `any`, `2xx`, or status codes such as `200,204`. `any` accepts any HTTP answer, a 5xx included; write `2xx` when the app answers 2xx once it is ready. |

### previewEnv object

| Key | Type | Meaning |
| --- | --- | --- |
| `sink` | string | File to write, for example `web/public/dynamic-env.json`. In a `.json` file, dotted keys become nested objects. |
| `values` | map | Key to templated value, for example `${preview.origin(api)}`. |

### compose and aspire services

A `kind: compose` service starts services from a Docker Compose file (Compose v2: write `docker compose`, never `docker-compose`, in commands). Its keys: `file` (the compose file), `profile` (the profile to start), `projectName`, `wait` (services that must be healthy) and `waitTimeoutSeconds`.

A `kind: aspire` service starts a .NET Aspire AppHost. Its keys: `apphost` (the AppHost file, for example `apphost.cs`) and `aspireExpose`, a list of resources to publish as preview addresses, each with `resource`, `port`, `healthcheck` (a path) and `primary`.

## preview

| Key | Type | Default | Meaning |
| --- | --- | --- | --- |
| `startTimeoutMinutes` | integer | `20` | Minutes **Start preview** may take before it fails. |
| `idleTimeoutMinutes` | integer | `60` | Minutes without activity before a branch preview pauses, from `10` to `80`. A coding session's **Runner** preview follows the session instead. |
| `backgroundPrep` | boolean | `true` | `false` runs `prep` only when someone starts a preview. |
| `parallelStart` | boolean | `true` | `false` starts services one after another in manifest order. By default, a service that declares `dependsOn` starts once those services are healthy. |

## Placeholders

| Placeholder | Where | Value |
| --- | --- | --- |
| `${env.NAME}` | Any `env` map | The value of the secret `NAME`. List `NAME` under the top-level `env` too. |
| `${preview.origin(name)}` | `init` step `env`, service `env`, `previewEnv.values` | The public origin of service `name`, without a trailing slash. Use it for redirect URIs, CORS origins and self URLs. |

`${preview.*}` and `${service.*}` placeholders exist only once a preview starts, so `prep` and `verify` cannot use them. In a `run` command, a secret is a shell variable (`$NAME`); `${env.NAME}` belongs in `env` maps.

## `volobox.workspace.yaml` keys

| Key | Type | Meaning |
| --- | --- | --- |
| `version` | integer | Accepted and ignored. |
| `workspace.primary` | string | The app selected by default. Must match an app's `name`. |
| `workspace.apps` | list | Folders that each contain a `volobox.app.yaml`. |
| `workspace.apps[].path` | string | The folder, relative to the repository root. The root app is `.`. |
| `workspace.apps[].kind` | string | `Preview` (default) or `Test`. A test app is marked **Test** in the preview list; it runs the same way. |
| `dependencies.repositories` | list | Other repositories cloned beside this one. |
| `dependencies.repositories[].url` | string | Git clone URL. |
| `dependencies.repositories[].name` | string | Stable id, used when `dynamicRef` is on. |
| `dependencies.repositories[].path` | string | Clone location relative to the repository root, for example `../shared-lib`. |
| `dependencies.repositories[].ref` | string | Required. The branch, tag or commit to check out. |
| `dependencies.repositories[].dynamicRef` | boolean | Lets people pick another branch, tag or commit when they start a preview. |
| `dependencies.repositories[].apps` | list of names | Apps that need this repository. Empty means every app. |

Each app folder needs its own `volobox.app.yaml` with a unique `name`.

## Example: SPA and API

A web front end and an API in one repository, with a database migration, two checks, and the API's address handed to the front end. It assumes npm workspaces, so one `npm ci` at the repository root installs both `api` and `web`; without workspaces, give each folder its own `prep` step with `cwd`.

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

env:
  - ConnectionStrings__Default

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

init:
  - run: npm run db:migrate
    env:
      ConnectionStrings__Default: ${env.ConnectionStrings__Default}

verify:
  - npm test
  - run: npm run lint
    cwd: web
    inputs: ["src/**"]

services:
  - name: api
    kind: command
    cwd: api
    command: npm run start -- --host 0.0.0.0 --port 8080
    port: 8080
    healthcheck:
      path: /health
      expectStatus: 2xx
    dependsOn: []
    env:
      ConnectionStrings__Default: ${env.ConnectionStrings__Default}
      App__SelfUrl: ${preview.origin(api)}
      App__CorsOrigins: ${preview.origin(web)}
  - name: web
    kind: command
    cwd: web
    command: npm run dev -- --host 0.0.0.0 --port 5173
    port: 5173
    primary: true
    dependsOn: []
    previewEnv:
      sink: web/public/dynamic-env.json
      values:
        apis.default.url: ${preview.origin(api)}
```

A repository with two apps lists them in a workspace manifest:

```yaml title="volobox.workspace.yaml"
version: 1
workspace:
  primary: storefront
  apps:
    - path: apps/storefront
    - path: apps/admin
```

## Related

- [Write a preview manifest](/docs/write-preview-manifest)
- [Sandbox command](/docs/sandbox-cli)
- [From a task to a pull request](/docs/task-to-pull-request)
- [Coding sessions and the task-to-PR loop](/docs/coding)
