Formats

Reference

Preview 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

FileWhereWhen you need it
volobox.app.yamlThe repository root, or the folder of each appAlways. One file describes one previewable app.
volobox.workspace.yamlThe repository rootOnly 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

KeyTypeRequiredMeaning
versionintegernoManifest schema version. 1 is the only version.
namestringyesThe app's id, unique in the repository. The app picker shows it.
descriptionstringnoLabel shown in the app catalog. Does not affect how the app runs.
groupstringnoGrouping label in the app catalog. Does not affect how the app runs.
envlist of stringsnoNames of the secrets the app needs. Values come from the secrets saved in Volobox, never from the file.
preplist of stepsnoCacheable setup: restore, install, build. See prep.
initlist of stepsnoSteps that run on every Start preview, before the services. See init.
verifylist of stepsnoChecks an agent's change must pass before its pull request opens. See verify.
serviceslist of servicesyesThe processes the preview runs. At least one, and exactly one marked primary. See Services.
previewobjectnoStart 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:

YAML
prep:
  - npm ci
  - run: dotnet restore
    cwd: src
    inputs: ["**/*.csproj"]
KeyTypeApplies toMeaning
runstringallShell command to run.
cwdstringallWorking directory, relative to the app folder (the repository root for a root app).
envmapallEnvironment variables for this step. Reference a secret as ${env.NAME}.
inputslist of globsprep, verifyGlobs relative to cwd. Their meaning differs per list; see below.
onlyForInitbooleanprepThe 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.
namestringprepThe name other steps use in dependsOn.
dependsOnlist of namesprepEarlier 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.

KeyTypeMeaning
namestringService name, unique in the manifest. Used by dependsOn and ${preview.origin(name)}.
kindstringcommand (default), compose or aspire.
cwdstringWorking directory, relative to the app folder.
commandstringShell command that starts a command service. Bind the server to 0.0.0.0.
portintegerPort the service listens on. Gets a preview address unless expose is false. Every command service needs one.
healthcheckstring or objectA path such as /health, or an object (below). Defaults to / when port is set.
dependsOnlist of namesServices that must be healthy before this one starts. [] starts it at once. A service without dependsOn waits for every service listed before it.
restartPolicystringwatch (default, no restart), on-change (restart when committed files match watchPaths) or manual.
watchPathslist of globsFor on-change: globs whose committed changes restart the service.
envmapEnvironment variables. Reference a secret as ${env.NAME} and a service address as ${preview.origin(name)}.
previewEnvobjectA file written before the service starts, holding preview addresses for a client app (below).
primarybooleanThe service the preview opens. Mark exactly one.
optionalbooleanThe preview can run without it: its failure is shown but does not fail the preview. Ignored on the primary service.
exposebooleanWhether 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

KeyTypeDefaultMeaning
pathstring/HTTP path to probe. Use a path the app really maps.
timeoutSecondsinteger120Seconds to wait for a healthy answer.
intervalMsinteger1500Milliseconds between probes.
expectStatusstringanyany, 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

KeyTypeMeaning
sinkstringFile to write, for example web/public/dynamic-env.json. In a .json file, dotted keys become nested objects.
valuesmapKey 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

KeyTypeDefaultMeaning
startTimeoutMinutesinteger20Minutes Start preview may take before it fails.
idleTimeoutMinutesinteger60Minutes without activity before a branch preview pauses, from 10 to 80. A coding session's Runner preview follows the session instead.
backgroundPrepbooleantruefalse runs prep only when someone starts a preview.
parallelStartbooleantruefalse starts services one after another in manifest order. By default, a service that declares dependsOn starts once those services are healthy.

Placeholders

PlaceholderWhereValue
${env.NAME}Any env mapThe value of the secret NAME. List NAME under the top-level env too.
${preview.origin(name)}init step env, service env, previewEnv.valuesThe 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

KeyTypeMeaning
versionintegerAccepted and ignored.
workspace.primarystringThe app selected by default. Must match an app's name.
workspace.appslistFolders that each contain a volobox.app.yaml.
workspace.apps[].pathstringThe folder, relative to the repository root. The root app is ..
workspace.apps[].kindstringPreview (default) or Test. A test app is marked Test in the preview list; it runs the same way.
dependencies.repositorieslistOther repositories cloned beside this one.
dependencies.repositories[].urlstringGit clone URL.
dependencies.repositories[].namestringStable id, used when dynamicRef is on.
dependencies.repositories[].pathstringClone location relative to the repository root, for example ../shared-lib.
dependencies.repositories[].refstringRequired. The branch, tag or commit to check out.
dependencies.repositories[].dynamicRefbooleanLets people pick another branch, tag or commit when they start a preview.
dependencies.repositories[].appslist of namesApps 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.

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:

volobox.workspace.yaml
version: 1
workspace:
  primary: storefront
  apps:
    - path: apps/storefront
    - path: apps/admin