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 vendors
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.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"
}
}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: 'ada@example.com', name: 'Ada' });
assert.equal((await stripe.customers.retrieve(made.id)).email, 'ada@example.com');
assert.equal(made.created, Date.parse('2026-01-15T12:00:00Z') / 1000);
console.log('create, read and frozen timestamp passed');Install and select
npm install
./node_modules/.bin/volter world init --name acme-webInspect the detected vendor, the reason for it, and .volter/world.json. Its Stripe service must name @volter/twin-stripe and 3.0.2. This example declares only Stripe. 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 an app with several SDKs or optional features, select only the vendors this workflow needs. For example, a customer-creation command can use Stripe while the app's email SDK stays unused:
./node_modules/.bin/volter world init --name my-app --twins stripe --source stripe=@volter/twin-stripeRun this instead of the automatic init above, before the first boot. The pinned CLI supports
both flags for existing apps. The installed Stripe package supplies the exact source version;
inspect the generated service to confirm it. Additional installed SDKs do not add twins to this
explicit selection. A later workflow that also calls another vendor needs its own deliberate
selection and installed twin; this command does not make an untwinned call succeed.
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 command
./node_modules/.bin/volter world up
./node_modules/.bin/volter world clock set 2026-01-15T12:00:00Z
./node_modules/.bin/volter world run -- node check.mjscreate, read and frozen timestamp passed./node_modules/.bin/volter world log
./node_modules/.bin/volter world downFor 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 publishers
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.2" }An alternative publisher uses its own package name with the same vendor ID. Installing several packages does not establish interchangeable state. Choose the installed implementation before fresh initialization:
$ ./node_modules/.bin/volter world init --name my-app --twins stripe --source stripe=@publisher/twin-stripeReplace the publisher package with the exact installed choice and inspect the generated source pin. Do not remove a saved pin or rely on package scan order. For an already initialized World, keep its config and discovery selection; stop your own World before changing dependencies, and trial an update separately.