Use a World with an existing app

Keep your app's SDKs and code. Select the vendors you want to substitute, then run your normal command inside the World. A coding agent is optional. Local use needs no platform account.

Review the app before selecting vendorsCopy Anchor Link

Read its manifests and .env.example. Distinguish the application's vendors from build downloads, optional features and tools. Install the exact releases you chose in the catalog; compare their measured operations with your app's calls. Do not include every detected vendor automatically.

This small existing app uses Stripe. Use Node 22.6 or newer in an empty directory; these exact packages make the walkthrough reproducible.

{
  "name": "acme-web",
  "private": true,
  "type": "module",
  "dependencies": {
    "stripe": "17.7.0"
  },
  "devDependencies": {
    "@volter/world": "3.0.63",
    "@volter/twin-stripe": "3.0.1"
  }
}

STRIPE_SECRET_KEY=

import assert from 'node:assert/strict';
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, { maxNetworkRetries: 0 });
const made = await stripe.customers.create({ email: '[email protected]', name: 'Ada' });
assert.equal((await stripe.customers.retrieve(made.id)).email, '[email protected]');
assert.equal(made.created, Date.parse('2026-01-15T12:00:00Z') / 1000);
console.log('create, read and frozen timestamp passed');

Install and selectCopy Anchor Link

npm install
npx volter world init --name acme-web

Inspect the detected vendor, the reason for it, and .volter/world.json. Its Stripe service must name @volter/twin-stripe and 3.0.1. This example declares only Stripe. On CLI versions whose help lists ordinary init selection, use --twins stripe to restrict a larger app deliberately. The empty key above declares the name the app reads; the World supplies a throwaway credential. Never copy production secrets to satisfy SDK validation.

For your own app, keep its manifests; add the CLI and the exact twin packages as development dependencies. Commit the lockfile and project-owned .volter/world.json, seeds and handlers. Keep instance state ignored.

Run the app's unchanged commandCopy Anchor Link

npx volter world up
npx volter world clock set 2026-01-15T12:00:00Z
npx volter world run -- node check.mjs

create, read and frozen timestamp passed

npx volter world log
npx volter world down

For your application, replace node check.mjs with its usual npm test or npm start. Run seeds through the vendor SDK too. Stop app consumers before down; state remains for the next up. Inspect a World opens the dashboard. Recover a failed call explains the next step when the app refuses a request.

Select one of several installed publishersCopy Anchor Link

Each vendor service's source.package and source.version select its implementation explicitly. Use the exact values on your chosen release page; retain the rest of the init-generated service definition:

"source": { "package": "@volter/twin-stripe", "version": "3.0.1" }

An alternative publisher uses its own package name with the same vendor ID. Installing several packages does not establish interchangeable state. When your installed CLI's help lists --source, you can choose an installed implementation before fresh initialization:

$ npx volter world init --name my-app --twins stripe --source stripe=@publisher/twin-stripe

Replace the publisher package with the exact installed choice. Older CLI versions may accept --twins only for bare Worlds: install only the chosen implementation initially, inspect the generated config and set its discovery selection before booting additional vendors. Do not remove a saved pin or rely on package scan order. Stop your own World before changing dependencies, and trial an update separately.