Coding

Guide

Write a preview manifest

Have a coding agent draft volobox.app.yaml or write it yourself, check it, start a branch preview, and add verify steps for agent pull requests.

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.

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:

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.

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

SymptomFix
Start preview and Sandbox environment are missingThe 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 nothingVolobox 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 answeringEvery 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 errorsexpectStatus defaults to any, which accepts any HTTP answer. Write expectStatus: 2xx.
prep steps run one after another although they do not need each otherGive each step a name and a dependsOn listing the earlier steps it needs ([] for none).
Services start one after anotherGive each service a dependsOn listing only what it needs (dependsOn: [] for none).
Runner shows Latest changes not appliedA 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 startBuild 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 addressesverify runs without a preview. Move that check out of verify.
Verification says the checks could not finishThey 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