Environment variables

What Veris reads from your shell, and what it sets for the code under test.

You sign in with veris login, which saves the key it pairs under a profile in ~/.veris/twin.yaml, and a project’s environments live in .veris/twin.yaml. So none of the variables below is needed to get started. Each is read when it is set, and where a flag says the same thing the flag wins.

Vendor credentials are not among them: your code keeps the ones it already has, and any well-formed value authenticates by default. See Credentials.

What Veris reads

Precedence

Every value takes the most explicit source that says anything:

environment   --env → $VERIS_ENV → the folder's "use" → the project default →
              the profile's default_environment → $VERIS_ENVIRONMENT_ID
profile       --profile → $VERIS_PROFILE → the environment's own "profile" →
              active_profile → "default"
api key       --api-key → $VERIS_API_KEY → the profile
api base      --api-base → $VERIS_API_BASE → the profile → https://svc.api.veris.ai
sandbox       --sandbox → $VERIS_SANDBOX_ID → the sandbox this folder remembers
routing       --config → --sandbox → $VERIS_PROXY_CONFIG → $VERIS_SANDBOX_ID →
              the sandbox this folder remembers

Not every command defines every flag named there. --profile is a global of the command tree, and the three commands that parse their own flags — run, serve and check — take none; --api-key is the other way round, a flag of run and serve that no tree command defines, and check defines neither. A flag a command does not define is a usage error rather than a no-op, so across that line the variable is the way in: $VERIS_PROFILE picks the login a run resolves with, and $VERIS_API_KEY the key any command sends. veris <command> --help lists what that command takes.

Layers never merge. A local file naming an environment hides the project’s default entirely, rather than filling in around it. The pointer at the end of the routing chain is the one veris up wrote into .veris/twin.local.yaml, which is why a bare veris run in that folder routes at the right sandbox with no flag at all.

Installing

The install script reads two of its own: VERIS_INSTALL_DIR for where the binary goes, ~/.local/bin otherwise, and VERIS_PROXY_VERSION to pin a version instead of taking the latest release.

What Veris sets

Inside a run, so the code under test needs no change of its own:

Alongside those, a run sets the proxy and certificate variables each runtime reads — HTTP_PROXY and its lowercase twin, NO_PROXY, NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, SSL_CERT_FILE, CURL_CA_BUNDLE and the rest — and JAVA_TOOL_OPTIONS when a JKS truststore is in play. With --image the redirect moves into the kernel and the routing half is left out, since the container needs only to trust the certificate.

The last row is the twin whose traffic is not intercepted at all: a database or another data plane, or any twin the control plane serves no vendor hostname for. Your code keeps reading the variable name it already reads, and the run sets that name to the twin’s URL, announcing each one as veris: <service>: not proxied; handed <VAR>=<url>. A variable you set yourself with -e is never overwritten. veris sandbox exports prints every twin’s variable name and URL for a sandbox that is up, handed over or not.

veris check proves the proxy in front of a command belongs to this run rather than to an older one, and exits 2 when it does not. It reads $VERIS_PROXY_URL and $VERIS_CANARY, or takes --proxy and --expect-canary.

The runner image

ghcr.io/veris-ai/veris-cli:runner is the proxy as its own container, which veris run --image starts for you. Started by hand — from a compose file, or a CI job that wires the containers itself — it takes its instructions the same way:

It runs veris serve, which reads VERIS_API_KEY, VERIS_API_BASE and VERIS_TUNNEL_TOKEN inside the container exactly as it would outside one.

With neither a sandbox nor an environment named, it routes from the config file — /veris/config.json, or wherever VERIS_CONFIG points — and refuses to start when there is none. Before it runs your command it sets VERIS_PROXY_URL and runs veris check against that proxy, and refuses the command when interception is not live.

Read next

• veris
• Through the proxy
• Credentials