Coding
GuideWrite 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.
- Open a coding session on the repository.
- On the session's Runner tab, select Generate in Volobox. The composer fills in
/init-preview-manifestin Agent mode. Review it and send it; Volobox does not send it for you. - The agent reads the repository (scripts, project files, compose files, the README, CI checks), writes the files, and proves they run: it runs the
prepandinitsteps, starts each service once with its real command, checks that it answers, fixes what fails, and stops what it started. - 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
- Select Download skill for your editor on Previews, on a branch preview without a manifest, or on Runner when the manifest is missing.
- Unzip the archive. It contains
SKILL.md. - Put that folder in your editor's skill directory (Cursor, Claude Code, or another tool that reads agent skills).
- Ask your editor's agent to write
volobox.app.yamlfor the repository.
To write it by hand, start from the smallest file that runs the app:
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 ininit. - Mark exactly one service
primary: true, and give eachcommandservice aport. Bind servers to0.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
envand pass them to a step or service as${env.NAME}.
Check the manifest
- 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, anddependsOnnames that match nothing. - 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.
- 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
- Commit and push the manifest. Previews and branch previews read it from the pushed branch.
- Open Previews in the Coding side panel, or the project's Code → Previews tab.
- Find the repository and branch, select the app, and select Start.
- Follow Starting preview. Setup steps lists every
prepandinitstep: the ones running, done, skipped as up to date, and still to come. - 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.
- Add a
verifylist tovolobox.app.yamlwith a few fast commands. - Reuse what
prepinstalled:dotnet build --no-restoreornpm run lint, not a second restore ornpm ci. - 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'scwd. A step withoutinputsalways runs. - Commit the manifest.
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. |