Skip to Content
Quickstart

Quickstart

Get your first simulation running in under 10 minutes.

This guide assumes you have an AI agent with an HTTP or WebSocket interface and Docker installed. For a detailed walkthrough with explanations of every concept, see the Full Walkthrough.

Install the CLI

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

Log in

veris login

This opens your browser for Google OAuth. For CI environments, use an API key:

veris login YOUR_API_KEY

Initialize your project

Navigate to your agent’s project directory:

cd your-agent-project
veris init --name "my-agent"

This creates a .veris/ directory with three files:

  • Dockerfile.sandbox — packages your agent for the sandbox
  • veris.yaml — declares services and communication config
  • .dockerignore — excludes unnecessary files from the build

Edit veris.yaml

Open .veris/veris.yaml and configure which mock services your agent needs and how the simulated user should talk to it:

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

Edit the Dockerfile

Open .veris/Dockerfile.sandbox and add your agent’s code and dependencies:

.veris/Dockerfile.sandbox
FROM us-central1-docker.pkg.dev/veris-ai-prod/veris-sandbox/veris-gvisor:latest
 
COPY requirements.txt /agent/
RUN pip install -r /agent/requirements.txt
 
COPY app /agent/app
 
WORKDIR /app

Set environment variables

If your agent needs API keys (e.g., for an LLM provider):

veris env set OPENAI_API_KEY=sk-... --secret

Push your agent

veris env push

This builds the Docker image and pushes it to the Veris registry.

Generate scenarios

Let Veris analyze your agent’s code and generate test scenarios and graders:

veris scenarios generate

You can also create scenarios in the Console under Scenarios & Graders.

Run simulations

veris run create

This starts an interactive prompt where you select the scenario set and concurrency. Monitor progress in the Console under Simulations.

Evaluate and report

# Run graders against completed simulations
veris evaluation-runs create
 
# Generate a report
veris reports create

What’s Next?

IntroductionTemplates