# 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](https://world.volter.ai/twins); 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.

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

```text file=.env.example
STRIPE_SECRET_KEY=
```

```js file=check.mjs
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

```bash
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 command

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

```text
create, read and frozen timestamp passed
```

```bash
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](./inspect-a-world.md) opens the dashboard. [Recover a failed call](./recover-a-failed-call.md) 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:

```json
"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:

```console
$ 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](../reference/config.md#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](./update-a-twin.md).

<!-- Fenced tutorial executor: packages/cli/src/journeys/tutorial.ts. Execution scope is recorded separately. -->