Data and keys

Where a World's data lives, which credentials grant access, and which operations use the network. The model defines the distinction between a simulated branch and a real root.

Where your data lives

The local product stores configuration and state under .volter/:

.volter/
  world.json            portable configuration
  handlers/ seeds/      scenario rules and seed source
  .gitignore            excludes live state and credentials
  world.env             generated live environment
  current               checked-out branch
  worlds/<branch>/      instance record, service data and process logs

The kernel’s VOLTER_STATE_DIR setting accepts relative directories, including nested paths. Absolute paths and .. components are refused before storage creation or removal.

The log has one entry model. In the file store, inherited entries and branch entries occupy separate segments (events.jsonl and actions.jsonl). Immutable descriptors under views/ retain segment ranges, their hashes and their storage dependencies. A branch records its parent view and position. A URL parent's cache shares unchanged rows in origin.jsonl; origin-head.json selects the latest complete fetch. Older views and checkpoints remain local. These files do not represent independent mirror and action truth systems. Package-specific payloads may occupy additional files.

A World fetched from a real root can hold real records in plain text. Running-state directories are created owner-only (0700) and files owner-only (0600), without encryption at rest. Protect the disk and keep instance data out of version control and diagnostic bundles.

Stopping and deleting

volter world down stops compute and retains state for the next up. down --purge deletes the stopped branch's instance directory after verified teardown. reset discards the current branch's state, boots and seeds default data; it keeps the origin, so a later pull can fetch that history again. Local descendants can still depend on this branch’s history by path: reset and purge refuse while a registered child or a child in the current World tree references it. Ordinary stop retains that history. See branch lifetime and legacy compatibility before removing old storage.

Prune removes eligible stopped instance files separately from stopping. It never infers ownership from age or stops a live World to make room. Failed or uncertain cleanup retains its records. Do not manually remove state behind a live process. See the operator CLI for ownership and cleanup commands.

File deletion is not secure erasure and does not remove backups. Immutable BlobStore payloads may be hardlinked across Worlds on the same filesystem; deleting one owner leaves the other owner's bytes available until the last owning file is removed.

Vendor credentials

Local Worlds use fake credentials. An SDK that parses credentials locally may need a structurally valid throwaway key, produced by the runtime's fake-credential generator. A Stripe webhook endpoint's signing secret, which Stripe mints for the app to verify with, is the World's value: the app's env holds it from boot and the Stripe twin signs with it, so the app verifies its first delivery with no key copied from a dashboard. Other twins that sign deliveries still mint their own secrets; their READMEs say which. Tokens can encode a synthetic identity; the twin manifest explains its authentication behavior.

A real-system root holds the vendor credential sealed beside that World. Refresh and real execution open it through the kernel's custody and executor paths. A client can use that World without receiving the vendor credential. The authority of its World token still matters: a token with write access to a root using auto deployment can cause real vendor writes.

World tokens

A World token grants access to a shared World. A read token grants history and vendor-API reads; it does not grant writes. Clone and remote configuration store tokens in the user's configuration directory (~/.config/volter/credentials.json, or the XDG equivalent), keyed by remote URL. Treat these tokens as credentials and keep them out of committed files and diagnostic output. The HTTP API specifies token scope and the separate host admin token.

Network activity

Simulated vendor requests use local state; they do not call the real vendor. Clone, fetch and push can contact another World. Refresh contacts the configured vendor, and real-system writes or deployment contact it through the root's executor. Installing packages contacts a registry.

The local runtime has no analytics, crash reporting or update check. Sandbox mode governs cooperating clients through injection and proxy settings. Raw sockets and binaries that ignore those settings require a separate enforced network boundary for a zero-egress guarantee.