Decide which claims localhost2137 can establish and when a scenario needs another runtime or external test.
This page describes current behavior. localhost2137 runs the surface an installed plugin documents; it does not make every property of an external service local.
| A local scenario can establish | It cannot establish by itself | Canonical detail |
|---|---|---|
| Installed plugin behavior for the exact tested request, response, state transition, event, and client version | Broader provider parity | Provider compatibility |
| Application traffic crossing its normal SDK or HTTP boundary | The same claim when setup or inspection operations replace that traffic | Operations and emulated APIs |
| Provider-shaped callbacks accepted by one configured receiver | External dashboard setup, internet delivery, or receiver routing the application cannot express | Callbacks and webhooks |
| Independent plugin state, clocks, logs, and tracked work per instance | Different plugin config, callback destinations, processes, users, or permissions | Instances and isolation |
| Explicit clock windows and plugin reconciliation | Application clocks, system time, untracked work, or provider schedulers | Virtual time and asynchronous work |
| Plain loopback HTTP in one developer or CI environment | DNS, TLS, load, regions, production networking, or provider availability | Choose the right test boundary |
| Bearer authorization on control routes except health | Authorization added by the runtime to provider-shaped routes, or a code sandbox | Local security model |
| Required difference | Use |
|---|---|
| Service state, clock, logs, tracked work | Another instance in the same runtime |
| Host, port, storage root, service set, plugin config, callback destination | Another runtime with another config |
| Trust, process permissions, user, filesystem, or network policy | An OS or CI isolation boundary |
One runtime is one loopback process, resolved config, control token, and storage root. Every instance uses the same service keys and plugin config. Plugins execute inside that runtime process; an instance is not a process or code sandbox.
A service key owns its public route, CLI selector, typed handle, and durable storage namespace. A service-key change is not itself a migration. It removes one mount, creates another with separate state, and leaves the removed key's data stored until a deliberate plugin-supported migration moves it.
| Constraint | Current behavior | Consequence |
|---|---|---|
| Network | 127.0.0.1, localhost, or ::1; plain HTTP | Suitable for local development and isolated CI, not public or production network claims. |
| Config loading | Once at startup; executable trusted Node.js code | Save does not hot-reload. Restart; control commands reject a fingerprint mismatch. |
| Storage ownership | One runtime owns one root at a time | Use normal shutdown or the exact lock-recovery procedure; never delete a broad directory to silence a lock. |
| Persistence | Development worlds reopen; temporary test storage follows test-runtime cleanup | Reset/destroy affect one selected world. Local state is not a backup or shared database. |
| Installation | Node.js 24 and pnpm; plugins may use native dependencies | A missing prebuilt binary may require a compiler toolchain before runtime behavior can be tested. |
Configuration imports and plugins have the Node process's filesystem and network privileges. Keep them trusted and free of unrelated import-time side effects. Configuration covers validation and restart effects; Local security model covers authority and data handling.
Persistent and temporary storage should stay out of source control and build artifacts. If startup reports a lock, follow the exact recovery procedure. For failures after startup, preserve the first broken boundary and use Diagnose a failing scenario.