Volter World

Use Volter World with a coding agent

Have your coding agent set up a world for your app, run its tests there, and show you what the app did at each vendor.

A coding agent is optional; manual setup teaches the same workflow without one. Use Node 22.6 or newer and npm.

Claude Code, Cursor, VS Code and Codex drive Volter World through volter mcp, an MCP server whose tools are the volter command's own verbs, and learn it from the volter-world skill. One command installs both into the agents on your machine. Then you ask in plain words.

The app

An app that creates a Stripe customer with the real Stripe SDK, and names its key in .env.example:

package.json
{
  "name": "acme-web",
  "private": true,
  "type": "module",
  "dependencies": {
    "stripe": "17.7.0"
  },
  "devDependencies": {
    "@volter/world": "3.0.169",
    "@volter/twin-stripe": "3.0.2",
    "@volter/world-core": "3.0.156",
    "@volter/world-runtime": "3.0.166",
    "@volter/world-console": "3.0.152",
    "@volter/world-ui": "1.0.156"
  }
}
.env.example
STRIPE_SECRET_KEY=
signup.mjs
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const customer = await stripe.customers.create({ email: 'ada@example.com' });
console.log(`created ${customer.id}`);

1. Install the command and the twin

npm install
./node_modules/.bin/volter --version

2. Give your agent the tools

./node_modules/.bin/volter agents install finds the coding agents on your machine and puts the skill and the MCP server into each: Claude Code (claude mcp add, and ~/.claude/skills/volter-world), Cursor (~/.cursor/mcp.json), VS Code (.vscode/mcp.json in this project) and Codex (~/.codex/config.toml and ~/.codex/AGENTS.md). Name one to set up only that agent. Here it is VS Code, whose server entry lives in the project:

./node_modules/.bin/volter agents install --vscode --yes
for      VS Code
skill    volter-world
.vscode/mcp.json: added the volter server

It changes only its own volter entry and its own skill folder; running it again changes nothing when the same installation is still in place. The printed server command uses this installation's absolute CLI path and runtime, so an older global volter does not replace your project's pinned tools. If you move or remove that installation, update the server entry in your agent's configuration. Without a flag it sets up every agent it finds, and without --yes it asks first:

$ ./node_modules/.bin/volter agents install
for      Claude Code, Cursor
skill    volter-world
server   /path/to/node /path/to/app/node_modules/@volter/world/dist/src/cli.js mcp

Install? [y/N]

Restart the agent so it starts the server.

3. Ask

Paste this into your agent. The platform's Get started and a world's Connect menu offer the same text with your platform's address filled in.

Set up Volter World for the workflow I want to run in this app. Select only the vendors that workflow deliberately substitutes with local twins. Keep the app's real SDKs.

1. You have the Volter World tools (volter mcp). Keep an app's existing pinned World tools. If the `volter` command is missing, install it: `npm install -g @volter/world`.
2. Read the app's manifests, env names and any .volter/world.json. Show me the likely vendors and why, before keeping them. Preserve a saved World and its state; do not initialize it again to resume. For a new World, choose the exact catalog releases and initialize only the selected vendors with world_init with vendors and sources (`volter world init --twins <selected-vendors> --source <vendor>=<package>`).
3. Start it with world_up, then run my usual app command inside it: world_run (`volter world run -- <the app command>`). Use throwaway credentials. Diagnose a failure as routing, data, scenario, unsupported operation or runtime; preserve the refusal's evidence rather than bypassing it.
4. Tell me what the app did at each vendor (world_log (`volter world log`)), and give me the dashboard link (world_view).

The agent's tools run the same commands you would, and answer what they answer. Here are those commands, as the agent runs them.

./node_modules/.bin/volter world init
  stripe | installed 3.0.2 | injector | STRIPE_TWIN_URL | env: STRIPE_SECRET_KEY; npm: stripe
COVERED: every detected vendor has a twin in world acme-web.
./node_modules/.bin/volter world up
./node_modules/.bin/volter world run -- node signup.mjs
created cus_twin_1
./node_modules/.bin/volter world log
stripe   customer.create        customer:cus_twin_1

For the dashboard the agent calls world_view, which runs the world with its dashboard and hands you the link; ./node_modules/.bin/volter world view is the same from a terminal.

4. Share it with your team

A world on your machine is yours. To share one, your agent signs the command in to your team's platform, and you approve the sign-in in your browser: the agent cannot. Then it links this world to one on the platform, making it there from this world's vendors, and pushes:

$ volter login https://your-platform.example
approve    https://your-platform.example/-/cli/approve?code=QWER-TYUI
$ volter remote add origin acme/web --create
$ ./node_modules/.bin/volter world changeset -m "The signup flow"
$ ./node_modules/.bin/volter world push

The MCP tools are platform_login, remote_link (with create: true), world_changeset and world_push. Use the hosted product covers the platform itself.

Clean up

./node_modules/.bin/volter world down

The tools and flags are in the CLI reference.

Keep the selected implementation

Give the agent the exact catalog package/version you chose and ask it to preserve that source in .volter/world.json. Review detected vendors before keeping them; never use a real credential to pass SDK validation. If a call fails, use recovery to distinguish routing, data, scenarios, unsupported operations and runtime failures. To open a dashboard, use inspect a World; to test forms and sessions, use browser testing. Platform sign-in still requires the person’s browser approval.

View Markdown source

On this page