setup

Wire a repository to an environment. Once.

/veris:setup
/veris:setup stripe asana

In Codex that is $veris:setup.

Run it from the repository you want to test. Setup works out which vendors your code calls, creates an environment holding a twin of each, and wires your test suite to reach them. Service names are optional: they are a starting list, and setup reads the code either way and shows you the final list before it creates anything.

The two tiers

How your tests reach those twins depends on what your code does with a vendor’s address, and setup settles that before it builds anything. There are two tiers, and this page is where the rest of the documentation sends you for them.

Your application is not edited on either of them, and the addresses Veris sets are ones your code already reads. The container tier reroutes outbound traffic from outside the process, so a call to a vendor hostname the control plane serves keeps that hostname. A twin the plane serves no hostname for — a database or another data plane, and any vendor twin whose hostnames the plane does not carry — is reached the other way on either tier: its URL is handed to your code in the environment variable production already sets for it. On the container tier the run names that twin and the variable its value went to; on the direct tier that handoff is the whole wiring.

The container tier needs Docker running. Everything else setup checks itself — that the veris CLI is installed and signed in with veris login, that the environment exists, and, where a container is involved, that there is a usable test image — and it reports what is missing in one pass rather than one failure at a time. It asks before it installs anything or creates an environment.

Every check it makes, and the order it makes them in, is in the setup skill.

What it leaves behind

.veris/twin.yaml holds this project’s environments and, under each, the settings a run inherits: the test image, the service a run has to reach, the recorded test command. veris run fills in from there whatever its command line leaves out. .veris/twin.local.yaml is per-machine and remembers the sandbox this folder is using. Dockerfile.veris appears only if getting a working test image took real work.

.veris/NOTES.md is worth reading. It records what the twin cannot represent, how identity and matching work for this vendor, which errors your code should expect, and where your existing tests do not actually reach the vendor. Each item is marked as measured or not measured, so you can tell what was checked from what was assumed.

Running what it wired

The container tier’s loop is three commands:

veris up
veris run
veris down

veris run takes the test command, the image and the service the run has to reach from .veris/twin.yaml, so the daily line carries none of them as flags. veris run --fresh does the three in one process, for CI. Both are covered in Running tests.

The direct tier has no proxy to put in front of the command, so the sandbox’s addresses go into the environment your application already reads and your tests run the way they always ran:

veris up
eval "$(veris sandbox exports)"
pytest -q

veris sandbox exports prints one export NAME='url' line per twin, valued at this sandbox, and nothing else on stdout; --format dotenv prints KEY=value lines for an env file, and a twin with no variable to publish is named on stderr rather than skipped silently. Set them wherever your application’s environment actually comes from — a shell, an env file, a platform’s secrets pane.

The names are the plane’s, one per twin, and veris services lists them beside the twin they belong to. They have to be the names your application already reads. This tier is the one where a mismatch is silent: nothing is intercepted, so a variable your code ignores leaves that call going to the real vendor under a green test. Check the names against your own configuration before the first run, and let the trace below settle it rather than the test’s exit code.

There is no receipt on this tier, so the twin’s own trace is the evidence. Trace ids are each twin’s own sequence, so read that twin’s newest id before the run and read back above it after:

veris sandbox trace --service stripe --limit 1 --json
veris sandbox trace --service stripe --since <id>

An empty trace under a green test means the call went to the real vendor. A sandbox wired this way is bound to a running application, so it lives until you rotate it: veris up again, export again, restart the application. Give it a TTL that outlasts the session you need it for, with veris up --ttl <minutes>.

What it does not change

Setup adds files under .veris/ and, if needed, a Dockerfile. It does not edit your application, your tests, or your dependency configuration. If it cannot wire the repository without changing your code, it stops and tells you why.

Re-running

Safe. It checks each precondition and skips what is already done, so re-running after adding a service or changing your test image does the minimum.

Read next

• Running tests
• build
• fix