Quickstart

Install the plugin and the veris CLI, sign in, then run your tests against twins.

Install the plugin, install the veris CLI, sign in with veris login, run setup, run your tests. At the end your existing test command runs against twins instead of the live vendor.

You need a repository with tests that call at least one third-party API, and Docker running for the container tier — setup’s usual path, which runs your tests in a container. A repository whose code already reads each vendor’s URL from a variable production sets takes the direct path instead, and that one needs no container. Setup chooses which one this repository gets.

Hand it to your agent

Paste this into Claude Code or Codex, from the repository you want to test. It checks each item first and does only what is missing.


Connect this repository to Veris.

Work through these in order, checking each one first. Skip anything already in place.

1. Work out which coding agent you are.

2. Install the Veris plugin `veris` from the `veris-ai/plugins` marketplace,
   using your own plugin commands. It carries three commands: setup, build, fix.

3. Install the Veris CLI, then check that `veris version` answers.

   macOS and Linux:
     curl -LsSf https://raw.githubusercontent.com/veris-ai/veris-cli/main/scripts/install.sh | sh
   Windows:
     powershell -c "irm https://raw.githubusercontent.com/veris-ai/veris-cli/main/scripts/install.ps1 | iex"

4. Sign me in with `veris login`, then wait until I have approved it in the
   browser before carrying on. It prints a pairing code and a console link. The
   key is saved to ~/.veris/twin.yaml — there is no key to copy and no shell
   profile to edit.

Leave my application code alone. This touches nothing else. If a step fails,
tell me which one and how to fix it, then stop.

When everything checks out, make your new commands available and run Veris setup,
naming the services this repository calls.

Or step through it yourself

Install the plugin

The marketplace is veris-ai/plugins and the plugin is veris. Each agent has its own plugin commands:


claude plugin marketplace add veris-ai/plugins
claude plugin install veris@veris


codex plugin marketplace add veris-ai/plugins
codex plugin add veris@veris

That adds three commands: setup, build and fix. Claude Code names them /veris:setup, /veris:build and /veris:fix. Codex names a plugin’s skills after the plugin too, so ask for $veris:setup rather than $setup.

Install the CLI


curl -LsSf https://raw.githubusercontent.com/veris-ai/veris-cli/main/scripts/install.sh | sh

On Windows:


powershell -c "irm https://raw.githubusercontent.com/veris-ai/veris-cli/main/scripts/install.ps1 | iex"

No root and no package manager. On macOS and Linux the binary lands in ~/.local/bin. Check it with veris version; if the shell cannot find it, that directory is not on your PATH.


veris login

Signing in pairs this machine with an organisation you already belong to, so you need a Veris account in one before this step. The command prints a pairing code and a console link. Approve the pairing there for the organisation you want, and it finishes on its own, saving the key under a profile in ~/.veris/twin.yaml. veris whoami says which key, organisation and plane a command will use.

Make the plugin’s commands available

They load when a session starts, so a session that was already open does not have them yet. Reload plugins, or start a new session. The CLI needs neither.

Run setup


/veris:setup

Setup reads your code for the vendors it calls, creates an environment for this project in .veris/twin.yaml, works out how your tests run against it, and is not finished until something shows your own code’s calls arriving at the twins — one run’s receipt naming each vendor with a count above zero on the container path, and the twin’s own trace on the direct path, where the run is your test command against the sandbox rather than a veris run. On the container path the run settings go into that same file — the test command as run.command, the services a run has to reach as require_service, the test image as proxy.image — and the full command line and what setup measured go into .veris/NOTES.md. Name the services yourself if you already know them: /veris:setup stripe asana.

Run your tests


veris up
veris run
veris down

up starts a sandbox of the project’s environment, run puts your own test command through it and prints a receipt of what the sandbox received, and down deletes the sandbox. A bare veris run replays what setup wrote into .veris/twin.yaml, so it is your own test command that goes through. Setup records require_service there too, and a run inherits it: if the sandbox did not receive that service’s traffic, the run exits non-zero however the tests themselves went.

Spell the run out when you want a different command, or a different set of services. What the command line names stands in for what the file says rather than adding to it, so a --require-service here has to name every service this run must reach:


veris run --require-service stripe -- pytest -q

In CI, veris run --fresh does all three in one process.

That is the container tier’s loop. The direct tier has no proxy and no image to run, so its loop is a different one, and setup carries it.

If a step will not go through, veris doctor runs its checks in one pass, marks each line ✓, ! or ✗, and names the command that fixes whatever failed. Troubleshooting lists what it looks at.