Quickstart

You’ve already seen Veris work in the console with an example agent. This page walks through the same flow with your own agent: package it as a container, push it to Veris, generate scenarios, run simulations, produce a report.

Most people reach for their coding agent first to set this kind of thing up. If that’s you, use the integration skill — it’s the fastest path. If you’d rather walk through it yourself, the manual walkthrough is below.

Prerequisites

An agent with a real production interface — HTTP, WebSocket, email, CLI (for cron-driven or single-shot commands), or a callable Python/Node function exposed as part of its public API (for agents triggered by webhooks, schedules, or other agents). Veris talks to your agent through the same interface it uses in production, not through a wrapper.
Docker running locally.
Python 3.11+ (for the CLI).

Install and authenticate


uv tool install veris-cli     # or: pip install veris-cli
veris login

veris login opens a browser for Google OAuth. For CI, pass an API key: veris login $VERIS_API_KEY.

Integrate your agent

Coding agent (recommended)

Point your coding agent at the Veris agent-integration skill. It analyzes your repo, classifies your dependencies, picks the right integration channel, writes .veris/veris.yaml and .veris/Dockerfile.sandbox, and pushes. Most decisions are made for you; checkpoints ask for approval before anything irreversible (creating the environment, setting secrets, pushing).

Install it with the skills CLI, which autodetects your coding agent (Claude Code, Cursor, Codex, and 40+ others) and puts the files in the right place:


npx skills add veris-ai/veris-skills/skills/agent-integration

Then, from inside your agent repo:


/agent-integration

Typical time: 15–30 minutes of guided work. When it finishes, skip to Generate scenarios below.

No coding-agent access? Use the Manual walkthrough tab above — you’ll end up in the same place.

Manual walkthrough

This is the detailed path — you’ll scaffold .veris/ and fill in the config yourself. Happy path is an HTTP or WebSocket agent. For LangGraph Platform deploys and other function-channel cases, see Frameworks at the end.

Scaffold `.veris/`


veris env create --name "my-agent"

Drops placeholder .veris/veris.yaml, .veris/Dockerfile.sandbox, .veris/.dockerignore, and .veris/config.yaml into your repo and registers the environment.

The scaffolded files are placeholders, not runnable. You have to edit them before pushing.

Configure `veris.yaml`

This is the step that trips up most people. veris.yaml tells the sandbox three things:

Which mock services your agent needs (Salesforce, Calendar, Stripe, Postgres, etc.)
How the simulated user talks to your agent (HTTP, WebSocket, email, or function callable)
How to start your agent inside the container

Example for an HTTP agent that calls Google Calendar:

.veris/veris.yaml


services:
  - name: google/calendar
    dns_aliases:
      - www.googleapis.com
      - calendar.google.com
 
actor:
  channels:
    - type: http
      url: http://localhost:8008
      method: POST
      request:
        message_field: message
      response:
        type: json
        message_field: response
 
agent:
  code_path: /agent
  entry_point: python -m app.main
  port: 8008

services — each entry enables a mock for that API. dns_aliases lists the real domains your agent calls in production; Veris intercepts those via DNS and routes to the mock. Your agent code needs zero changes. Full services list: services catalog.

actor — how the simulated user (or triggering event) talks to your agent. Channels: http, websocket (ws), email, function (for agents exposed as a Python/Node callable), and cli (for agents whose production entry point is a command-line program — a cron-driven binary, a shell-invoked tool, a single-shot command). request and response tell the actor how to format messages and parse replies.

agent — where your code lives inside the container (code_path, default /agent), how to start it (entry_point), and the port it listens on. For function and cli channel agents, omit entry_point and port — the container skips agent startup because each turn either calls your function or spawns the configured command directly.

Full schema: veris.yaml reference. For complete working agents, see the cookbook .

Configure the Dockerfile

.veris/Dockerfile.sandbox extends the Veris base image (which already has Python 3.12, uv, and Node.js) and adds your agent’s code and dependencies.

.veris/Dockerfile.sandbox


ARG VERIS_BASE
FROM ${VERIS_BASE}
 
COPY requirements.txt /agent/
RUN pip install -r /agent/requirements.txt
 
COPY app /agent/app
 
WORKDIR /app

If you’re on uv:

.veris/Dockerfile.sandbox (uv)


ARG VERIS_BASE
FROM ${VERIS_BASE}
 
COPY pyproject.toml uv.lock /agent/
WORKDIR /agent
RUN uv sync --frozen --no-dev
 
COPY app /agent/app
 
WORKDIR /app

The final WORKDIR /app is required. The Veris entrypoint script lives at /app and must be the working directory when the container starts.

More patterns (Node.js, schema seeding for Postgres, bundled infra with start.sh): Dockerfile reference.

Set runtime env vars


veris env vars set OPENAI_API_KEY=sk-... --secret
veris env vars set ANTHROPIC_API_KEY=sk-ant-... --secret

Non-secret defaults can go in agent.environment inside veris.yaml. Secrets should always use veris env vars set --secret.

Push


veris env push

Builds the image locally, uploads it, registers a tag in your environment. Default tag is latest.

You now have

Regardless of which path you took, you now have:

A pushed environment — your agent containerized and reachable by Veris.
.veris/veris.yaml + .veris/Dockerfile.sandbox in your repo.

Next: generate scenarios, run them, get a report.

Want to understand what these pieces mean before running them? Read Environment, Scenario, Simulation, Evaluation, Report.

Generate scenarios


veris scenarios create
veris scenarios status <SET_ID> --watch

Async job. Explores your repo, infers what the agent is supposed to do, produces test cases plus a matching grader. 2–5 minutes for a small agent.

Run the loop


veris run

Interactively: pick the scenario set, watch simulations run, watch the evaluation, optionally generate a report. veris run chains simulations → evaluations → report in one command. For non-interactive / CI use, pass flags:


veris run \
  --scenario-set-id <SET_ID> \
  --grader-id <GRADER_ID> \
  --report

You can also run each step on its own: veris simulations create, veris evaluations create, veris reports create.

What’s next

Iterate on your agent → Development loop. The simulate → fix → re-simulate cycle, with tips on reading reports.
Framework-specific notes → Frameworks. If you’re on LangGraph Platform, Vercel AI SDK, or hit a framework-specific snag, start here.
See the other use cases → Use Cases. CI regression gating, RL training, SFT training, regulatory QA.
Reference material → veris.yaml schema, CLI commands, services catalog.

Want us to do the integration for you? Reach out about enterprise support — our team can configure .veris/ for your agent.