---
title: Volter World documentation
---

# Volter 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](./getting-started.md) | An SDK write, a read-back assertion and a repeatable starting state |
| I already have an application | [Use your existing app](./guides/use-with-an-existing-app.md) | Selected twins and your usual app command running inside a World |
| I work with a coding agent | [Use your coding agent](./guides/use-with-a-coding-agent.md) | The same CLI workflow, with the agent doing the setup |
| A teammate invited me | [Join a team's World](./guides/team-onboarding.md) | The right platform, organization and shared workflow |
| I have used a World before | [Resume your World](./guides/resume-a-world.md) | 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](./concepts/what-a-twin-is.md) explains
the behavior and limits.

## After your first success

Run your app, [inspect its writes](./guides/inspect-a-world.md), then
[control its starting data](./guides/seed-and-reset.md). Add
[responses and failures](./guides/shape-the-world-for-a-test.md) for the cases you need to exercise.
When the workflow is repeatable, use it for [browser work](./guides/test-in-the-browser.md),
[CI](./guides/use-in-ci.md) or [team collaboration](./guides/team-onboarding.md).
If a call fails, [recover a failed call](./guides/recover-a-failed-call.md) starts with the evidence.

## Learn

- [Getting started](./getting-started.md) — create a customer, read it back, assert the result,
  reset and repeat with a real SDK and a local twin.
- [Inspect a World](./guides/inspect-a-world.md) — read its log and state, or open the dashboard
  and vendor screens.

## Choose twins

- [Choose a twin](./guides/choose-a-twin.md) — compare implementations for the operations your
  app needs; understand supported surface, exercised coverage and publisher identity.
- [Use a catalog twin](./guides/use-a-catalog-twin.md) — install an exact release and run the
  real SDK with synthetic page data, including an absent-page failure.
- [Update a twin](./guides/update-a-twin.md) — compare a candidate, try it separately, and change
  dependencies and World pins deliberately.

## Develop and test

- [Resume a World](./guides/resume-a-world.md) — continue with saved state, choose reset deliberately and stop without discarding data.
- [Use a World with an existing app](./guides/use-with-an-existing-app.md) — manual setup, selected vendors, exact sources and the app’s unchanged command.
- [Recover a failed call](./guides/recover-a-failed-call.md) — diagnose routing, data, handlers, credentials and pins.
- [Test an app in the browser](./guides/test-in-the-browser.md) — forms, sessions, state and eight explicit workflow assertions.
- [Test signed webhooks](./guides/test-signed-webhooks.md) — registered callbacks, signature verification and refusal.
- [Reproduce a failure](./guides/reproduce-a-failure.md) — history branches plus the seed, clock, handler and assertion.
- [Use Volter World with a coding agent](./guides/use-with-a-coding-agent.md) — 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](./guides/seed-and-reset.md) — get a known state, and get back to it.
- [Shape the world for a test](./guides/shape-the-world-for-a-test.md) — the record your test
  needs, the call that has to fail.
- [Run your test suite](./guides/run-your-test-suite.md) — point your tests at the twins, and read
  the log when one fails.
- [Run a full stack](./guides/run-a-full-stack.md) — app, database and twins together, for
  browser and end-to-end work.
- [Use in CI](./guides/use-in-ci.md) — locked dependencies, independent worker state and teardown on success or failure.
- [Route a CLI through the world](./guides/route-a-cli-through-the-world.md) — make `gh`,
  `stripe`, `aws` and any other tool hit the twins.

## Collaborate

- [Join a team’s World](./guides/team-onboarding.md) — platform access and the right shared workflow, without host administration.

- [Branch a world](./guides/branch-a-world.md) — a variant for a feature, a teammate, a CI shard.
- [Share a world](./guides/share-a-world.md) — one world for the team: everyone clones from it,
  everyone pushes to it.
- [Work from a shared world](./guides/work-from-a-shared-world.md) — start from the team's
  history, keep it fresh, and know what you are holding.
- [Point an app at a shared world](./guides/point-an-app-at-a-shared-world.md) — 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](./guides/read-the-vendor-through-a-shared-world.md) —
  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](./guides/deploy-from-a-shared-world.md) — get what your app wrote
  to the vendor, with receipts under the real root’s deployment policy.
## Examples

- [Cookbook](../cookbook/README.md) — complete starter examples and larger application case studies, with prerequisites and limits.
- [Browser signup and webhooks](../cookbook/browser-signup/README.md) — a complete small application with deterministic browser assertions.
- [Repeatable data and behavior](../cookbook/repeatable-workflow/README.md) — stored records, a one-time fault, retry, reset and time.
- [Isolated CI workers](../cookbook/ci-workers/README.md) — separate roots, exact dependencies and guaranteed teardown attempts.
- [Transactional email](../cookbook/email/README.md) — Resend's real SDK, a local inbox and retained messages after restart.

## Administer a platform

- [Host worlds for a team](./guides/host-worlds-for-a-team.md) — 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](./guides/self-host-the-platform.md) — 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](./guides/use-the-hosted-product.md) — sign in, get a token, push from
  your machine to a world Volter runs for your org.

## Look up

- [CLI](./reference/cli.md) — every `volter` verb and flag, and the operator's `volter-world`.
- [Config](./reference/config.md) — `.volter/world.json`, field by field.
- [SDK](./reference/sdk.md) — `World` and `TwinLog` from `@volter/world`.
- [HTTP API](./reference/http-api.md) — what a twin and a remote serve beside the vendor's API.
- [Platform API](./reference/platform-api.md) — the hosted product's own endpoints: orgs, worlds, members, billing, tokens, activity, support; generated from one table.
- [Refusals](./reference/refusals.md) — every refusal a world gives, the side that refused, and the one change that fixes it.
- [Coverage](./reference/coverage.md) — what supported, exercised and unmeasured coverage mean
  for your app.
- [Glossary](./reference/glossary.md) — every word a user meets, and no other.

## Understand

- [What a twin is](./concepts/what-a-twin-is.md) — how faithful, what it never does, why it
  refused that route.
- [The model](./concepts/the-model.md) — Neon for every SaaS: the log, checkpoints, branches as
  positions, the root, push against deploy, checks.
- [Worlds](./concepts/worlds.md) — what `up` actually starts, the env your app sees, why worlds
  are cheap.
- [Data and keys](./concepts/data-and-keys.md) — where your data lives, credential and token authority, and what uses the network.

## Contribute

- [Publish your own twin](https://github.com/volter-ai/twin-catalog-open/blob/main/docs/contributing.md)
  — 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](../CONTRIBUTING.md) — the two-paragraph version.
- [Architecture](./contributing/architecture.md) — the contract, and the procedure a twin is built by;
  [gates](./contributing/gates.md) — how a change
  is verified; [style](./contributing/style.md); [the console's pages](./contributing/console.md); the [build glossary](./contributing/glossary.md).
- [Publish the documentation](./contributing/documentation.md) — canonical Markdown, Fumadocs preview and hosting.