Formats
ReferencePreview manifest reference
Every key of volobox.app.yaml and volobox.workspace.yaml: steps, verify checks, services, preview settings and placeholders.
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.
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. |
init | list of steps | no | Steps that run on every Start preview, before the services. See init. |
verify | list of steps | no | Checks an agent's change must pass before its pull request opens. See verify. |
services | list of services | yes | The processes the preview runs. At least one, and exactly one marked primary. See Services. |
preview | object | no | Start timeout, idle timeout, background preparation and parallel start. See 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:
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
inputschange. Withoutinputs, Volobox watches the lockfiles and project files under the step'scwd.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. prepcannot use${preview.*}or${service.*}placeholders, because preview addresses do not exist yet.- In the background, a step receives only the secrets it names:
$NAMEin its command, or${env.NAME}in its ownenv. Name a secret a tool reads implicitly, such asNPM_TOKENfor a private registry, in the step'senv. - Set
preview.backgroundPrep: falseto runpreponly 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.
inputson averifystep means "run only when a file the branch changed matches one of these globs" (relative to the step'scwd). A step withoutinputsalways 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 duringverify, so such a step fails. - A step receives only the secrets it names (
$NAMEin its command, or${env.NAME}in its ownenv), and their values are hidden in the output Volobox keeps. - Reuse what
prepinstalled: writedotnet build --no-restoreornpm run lint, not a second restore ornpm 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.
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:
version: 1
workspace:
primary: storefront
apps:
- path: apps/storefront
- path: apps/admin