# Volter documentation

Volter runs your app against a **world**: the twins of the SaaS your app depends on, running
together on your machine with fake keys. A **twin** is one vendor's replica, faithful on the wire
and stateful. **Volter** is the tool that runs worlds.

Pick the page by what you are doing.

## Learn

- [Getting started](./getting-started.md) — your first world, in ten minutes. Every command on
  the page is executed as a test, so it cannot drift from the product.

## Do

- [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) — the same world on every pull request, with the GitHub Action, and a preview World for each pull request.
- [Branch a world](./guides/branch-a-world.md) — a variant for a feature, a teammate, a CI shard.
- [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.
- [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: no key in the app, every call logged,
  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 a receipt for every change, and a check in the way.
- [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 — 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 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.
- [Coverage](./reference/coverage.md) — every vendor, how complete its twin is, and why it is
  built in that order.
- [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

- [Contributing](../CONTRIBUTING.md) — the two-paragraph version.
- [Architecture](./contributing/architecture.md), [adding a twin](./contributing/adding-a-twin.md),
  [conformance](./contributing/conformance.md), [gates](./contributing/gates.md),
  [coverage](./contributing/coverage.md), [test depth](./contributing/test-depth.md),
  [adoption evaluations](./contributing/adoption-evaluations.md), [style](./contributing/style.md),
  and the [build glossary](./contributing/glossary.md).

Planned development is listed in the [roadmap](../ROADMAP.md).

Runnable examples live in [`cookbook/`](../cookbook/README.md).