Use a catalog twin
Run the implementation and exact version you selected in the catalog. Your application keeps the vendor's real SDK. This guide applies to any selected release; the release's README owns its supported calls, synthetic credentials and starting data. Local use needs no Volter platform account or real vendor credential.
Keep your selection
Open the selected release's Setup tab and copy its complete installation command. It pins
the World tools and the selected twin in your app folder. Use Node 22.6 or newer; installing
dependencies needs package-registry access. Keep the resulting package manifest and lockfile.
You do not need a globally installed CLI when using ./node_modules/.bin/volter from the app folder after installation.
Keep the package and version visible while you work. Overview contains the README from that release's artifact. Versions compares alternatives. Evidence describes what was measured and the versions used for that assessment; those historical tool versions need not be the current starter cohort.
If you are learning without an existing app, choose a complete example instead of inventing a client and seed:
- Customer onboarding: a browser form, customer, email and application SQL state, including refusal and retry.
- Workplace handoff: an issue, related ticket and channel update, including partial completion.
- Search a synthetic page: Tavily search, extraction and an absent-page result. Its data is local; it does not search the public web.
- More complete examples: AI messages, managed app data, email and separate CI workers.
Each example names its own exact releases and scope. A link to an example does not establish that another package or version was exercised.
Use several twins together
On the catalog cards or an exact release page, choose Add to World stack for each vendor your workflow needs. Your stack keeps one implementation and exact version per vendor as you browse. Adding another release for the same vendor replaces that choice. Remove a choice or clear the stack when it no longer belongs in this workflow.
Open Set up these twins together for one installation command with every selected package
pin and the current World tools, followed by one initialization command naming the selected
vendors and publishers. These commands are for a new World in your app folder; they do not
overwrite an existing World. Keep the resulting lockfile and review each generated
source.package and source.version before starting.
Choices stay in this browser. If a saved release is no longer offered, the page tells you and removes it; it does not substitute a newer version. Check the selected releases’ Node and kernel requirements too. Choosing several releases does not prove they cover your app’s calls.
Without scripting or browser storage, retain each release’s Setup command yourself. Combine
the exact twin package pins into one installation command, naming the World tools once. For
initialization, --twins accepts comma-separated vendor IDs and --source vendor=package can
be repeated for each publisher choice; see the CLI reference.
Select the World vendors
From your app's folder, follow Setup's ./node_modules/.bin/volter world init command. It names the chosen
vendor and implementation. Review the detection report and .volter/world.json before
starting; include only the vendors this workflow deliberately substitutes.
The service's source.package and source.version must agree with the release you installed.
Keep the rest of the generated service definition. A vendor ID and a publisher's npm package
name are different identities; another publisher can supply an implementation for the same vendor.
If the app already has a World, preserve its configuration and state. Stop your own running
World before changing dependencies and trial an update separately.
Do not run init --force to erase an existing selection.
Supply the data your app needs
Read the selected README for supported operations, SDK setup, default records and required
seed data. Declare the credential names your app reads in .env.example with empty values.
The World supplies throwaway credentials. A locally parsed credential must have the required
structure; never substitute a real key to pass SDK validation.
Create stored records through the vendor's API with its real SDK, inside the World. Use the project's handler files for authored model replies, stateless lookups and faults. Handlers never stand in for a successful stored mutation. Seed and reset and shape behavior own those tasks.
Node SDKs use injected routing. Python and native clients may need their supported proxy, CA or endpoint setup; client routing explains that boundary. If a call fails, recover it from the evidence; an installed twin does not establish that every API operation is supported.
Run your app and read the result
Start the World, then run your app's own command inside it. For an app whose usual command is
npm start:
$ ./node_modules/.bin/volter world up
$ ./node_modules/.bin/volter world run -- npm startKeep long-running app work in its terminal. Stop the app before stopping the World. In another terminal in the same app folder, inspect the recorded changes:
$ ./node_modules/.bin/volter world log
$ ./node_modules/.bin/volter world diffRead the resulting records through the real SDK too. A log entry is a stored effect, not proof of every read or every application outcome. Inspect a World explains Records, Changes and the screens that the selected release actually declares.
Stop, resume or repeat
$ ./node_modules/.bin/volter world downdown stops compute and retains state. Ordinary up resumes a stopped branch. Reset is a
deliberate return to default data; repeat the same seeds, handlers and clock for a repeatable
workflow. Your app's own database and browser state have their own lifecycle.
Continue with your existing app, resume saved work or script a failure. Existing pins do not change when the catalog selects a new default.