How it works

Your code runs unmodified. Its dependencies are twins.

Your test command runs where it already runs, in your test container or on a laptop, and your code is neither modified nor told: same production hostnames, same credentials, same client library, same SDK. You change no base URLs and swap no credentials, unless your code already reads a vendor’s base URL from a variable production sets — setup points that variable at the sandbox, which edits no code and leaves the shipped path under test.

Its outbound calls land on twins instead of the vendor, because the proxy runs beside your code rather than inside it and reroutes the traffic. Your coding agent drives the sandbox from the shell — veris up and veris down for its lifecycle, veris sandbox data, veris sandbox clock and veris sandbox trace for what is in it — so seeding a row or arming a failure never touches your source either.

The terms used below are defined on Core concepts.

The workflow

Create an environment

Pick the twins your code calls: veris env create checkout --services stripe,postgres. Once per project. The name and its settings are recorded in .veris/twin.yaml, committed with the repository.

Create a sandbox

veris up deploys one isolated running copy of that environment and waits until every twin answers. Every twin in it boots with a seeded world, or from a baseline or a snapshot you saved earlier. Ready in seconds, and it has a TTL so it cannot be left running.

Arrange the world

Seed the exact rows the case needs with veris sandbox data add, arm a failure the real vendor will not produce on demand — a fault is a row, added the same way — or move the clock with veris sandbox clock set. Optional: the default world already covers an ordinary path.

Run your tests

Run your own test command, unchanged, through the proxy: veris run -- pytest -q. Every outbound call to a twinned vendor reaches the twin instead. Nothing in your source changes and no credentials are swapped.

Read the receipt and the trace

The receipt veris run prints says what the sandbox received, and veris sandbox trace says what your code actually sent, with the headers and bodies of one entry under --body.

Reset and repeat

veris sandbox reset restores every twin to its boot seed, so the same test runs again; veris down tears the sandbox down. Same world in, same answers out, generated ids included.