Volter World documentation
Develop your app against services whose data and behavior you can control. Volter runs a World: the twins of the vendors you select, together with their state and environment. A twin answers a vendor's API locally, so your app can use its real SDK to create and read data. You can return to known data, script a failure or branch a World to reproduce a problem.
Start locally without a platform account, then pick a guide for the task you want to complete. Use your app's real SDKs. Select the vendors to substitute, give them the data and behavior your workflow needs, and run the app inside the World.
Start here
| Your situation | Start with | What you will have |
|---|---|---|
| I want to understand it by trying it | Your first local World | An SDK write, a read-back assertion and a repeatable starting state |
| I already have an application | Use your existing app | Selected twins and your usual app command running inside a World |
| I use a Python or native SDK | Route your client | The client's supported proxy and trust settings, with a real Python SDK example |
| I want to control World from my own tool | Use the Node library | Local imports, owned lifecycle, app exit codes and retained state |
| I work with a coding agent | Use your coding agent | The same CLI workflow, with the agent doing the setup |
| A teammate invited me | Join a team's World | The right platform, organization and shared workflow |
| I want a complete app to try | Customer onboarding | Stripe, email and SQL outcomes, including partial completion |
| I need a hosted payment flow | Checkout and customer portal | A payment, decline and retry, then trial billing with SDK read-back |
| I build a tool-using agent | Workplace starter | A repository, team, channel and resumable issue handoff |
| I need to exercise an AI tool call | Run a tool and stream its result | A scripted OpenAI tool call, actual GitHub issue and streamed confirmation |
| I combine parallel workers | Baseline and integration | Isolated workers with explicit changeset destinations |
| I need a repeatable presentation | Demo a workflow | A baseline, refusal, retry and explicit reset |
| I have used a World before | Resume your World | Your saved branch and data, without starting over |
Local use needs no Volter platform account or real vendor key. A platform adds team access and shared Worlds; publishing a twin is a separate contributor task. Check a release's supported operations before relying on it. Node SDKs use injected routing; other clients may need their supported proxy, CA or endpoint setup. What a twin is explains the behavior and limits.
After your first success
Run your app, inspect its writes, then control its starting data. Add responses and failures for the cases you need to exercise. When the workflow is repeatable, use it for browser work, CI or team collaboration. If a call fails, recover a failed call starts with the evidence.
Learn
- Getting started — create a customer, read it back, assert the result, reset and repeat with a real SDK and a local twin.
- Inspect a World — read its log and state, or open the dashboard and vendor screens.
Choose twins
- Choose a twin — compare implementations for the operations your app needs; understand supported surface, exercised coverage and publisher identity.
- Use a catalog twin — keep your selected vendor and exact release through installation, setup and your own app command.
- Update a twin — compare a candidate, try it separately, and change dependencies and World pins deliberately.
Develop and test
- Resume a World — continue with saved state, choose reset deliberately and stop without discarding data.
- Use a World with an existing app — manual setup, selected vendors, exact sources and the app’s unchanged command.
- Control a World from Node — use the locally installed SDK to own boot, run the app command and stop with retained state.
- Recover a failed call — diagnose routing, data, handlers, credentials and pins.
- Test an app in the browser — forms, sessions, state and eight explicit workflow assertions.
- Test signed webhooks — registered callbacks, signature verification and refusal.
- Reproduce a failure — history branches plus the seed, clock, handler and assertion.
- Use Volter World with a coding agent — one command gives Claude Code, Cursor, VS Code or Codex the tools; then ask it to set up a world for your app.
- Seed and reset — get a known state, and get back to it.
- Shape the world for a test — the record your test needs, the call that has to fail.
- Run your test suite — point your tests at the twins, and read the log when one fails.
- Run a full stack — app, database and twins together, for browser and end-to-end work.
- Use in CI — locked dependencies, independent worker state and teardown on success or failure.
- Route Python and native clients — real vendor hostnames, supported proxy and CA settings, and a Stripe Python SDK example.
Collaborate
-
Join a team’s World — platform access and the right shared workflow, without host administration.
-
Branch a world — a variant for a feature, a teammate, a CI shard.
-
Share a world — one world for the team: everyone clones from it, everyone pushes to it.
-
Work from a shared world — start from the team's history, keep it fresh, and know what you are holding.
-
Point an app at a shared world — run the app against the team's world and reach the vendor through it: scoped access and recorded state effects, a check in the way.
-
Read the vendor through a shared world — keep a copy of the account in the team's world, read it from every clone, rebase when it moves.
-
Deploy from a shared world — get what your app wrote to the vendor, with receipts under the real root’s deployment policy.
Examples
- Cookbook — complete starter examples and larger application case studies, with prerequisites and limits.
- Search a synthetic page — Tavily's real SDK reads local page content and an absent-page result.
- Customer onboarding — one application across Stripe, email and SQL, with browser and command entries.
- Hosted Checkout and the customer portal — a payment and trial through vendor pages, paired with stored SDK results.
- Workplace handoff — linked GitHub, Linear and Slack results, including a refused notification and retry.
- Shared baseline and integration — independent worker histories delivered to an explicit integration destination.
- Browser signup and webhooks — a complete small application with deterministic browser assertions.
- Repeatable data and behavior — stored records, a one-time fault, retry, reset and time.
- Isolated CI workers — separate roots, exact dependencies and guaranteed teardown attempts.
- Users and sessions — create a Clerk user and session, verify the token, revoke and read retained state.
- Redis data and quotas — store a customer, refuse an exhausted budget, resume it and open the next clock-driven window.
- Object storage — upload and read an R2 file through the real S3 SDK, then resume its retained data.
- Transactional email — Resend's real SDK, a local inbox and retained messages after restart.
- AI messages and streaming — read and stream an authored response through Anthropic's real SDK.
- Run a tool and stream its result — consume an OpenAI tool call, create the actual GitHub issue and resume its stored result.
Administer a platform
- Host worlds for a team — many worlds under one URL, each with its own token, provisioned through the HTTP API, and a console that shows them all.
- Self-host the platform — the host and the platform on your own machines: people sign in with your identity provider, make orgs and open Worlds as themselves.
- Use the hosted product — sign in, get a token, push from your machine to a platform your team can reach. This needs a platform URL and account; local Worlds and self-hosting do not require a Volter cloud subscription.
Look up
- CLI — every
volterverb and flag, and the operator'svolter-world. - Config —
.volter/world.json, field by field. - SDK —
WorldandTwinLogfrom@volter/world. - HTTP API — what a twin and a remote serve beside the vendor's API.
- Platform API — the hosted product's own endpoints: orgs, worlds, members, billing, tokens, activity, support; generated from one table.
- Refusals — every refusal a world gives, the side that refused, and the one change that fixes it.
- Coverage — what supported, exercised and unmeasured coverage mean for your app.
- Glossary — every word a user meets, and no other.
Understand
- What a twin is — how faithful, what it never does, why it refused that route.
- The model — Neon for every SaaS: the log, checkpoints, branches as positions, the root, push against deploy, checks.
- Worlds — what
upactually starts, the env your app sees, why worlds are cheap. - Data and keys — where your data lives, credential and token authority, and what uses the network.
Contribute
- Publish your own twin — use released authoring tools from an independent repository; catalog Actions prepares evidence, trusted publishers need no separate review, and other submissions receive human assessment.
- Contributing — the two-paragraph version.
- Architecture — the contract, and the procedure a twin is built by; gates — how a change is verified; style; the console's pages; the build glossary.
- Publish the documentation — canonical Markdown, Fumadocs preview and hosting.
- First-use surfaces — user journeys, comparable products and the design contract for product, docs and catalog pages.
- Standing in pre-commit — the delegated scope for checking the published report.
- Kept PGlite database opening — retained Rallly readings and the declared identity receipt.
- PostgreSQL fork ceiling — why the catalog build retains EXEC_BACKEND and which memory mechanism would lift that limit.