veris.yaml Reference

The .veris/veris.yaml file is the main configuration file for your Veris sandbox. It declares which mock services to enable, how the simulated user communicates with your agent, and how to start your agent.

Full Schema

.veris/veris.yaml


version: "1.0"                       # Optional version
 
services:                            # Mock services to enable
  - name: calendar                   # Service identifier
    dns_aliases:                     # Domains routed to mock
      - www.googleapis.com
      - calendar.google.com
    config:                          # Service-specific env vars
      SOME_KEY: some_value
    port: 8003                       # Optional port override
    description: "Custom desc"       # For generic services
 
actor:                               # Simulated user config
  channels:                          # Communication channels
    - type: http                     # http | ws | email
      url: http://localhost:8008
      method: POST
      headers:
        Content-Type: application/json
      request:
        message_field: message
        session_field: session_id
        static_fields:
          prompt_type: default
      response:
        type: json                   # json | sse
        message_field: response
        session_field: session_id
  config:                            # Actor behavior config
    RESPONSE_INTERVAL: "2"
    POLL_INTERVAL: "15"
    REFLECTION_INTERVAL: "3"
 
agent:                               # Your agent config
  code_path: /agent                  # Code location (default: /app)
  entry_point: python -m app.main    # Startup command
  port: 8008                         # Listen port (default: 8008)
  environment:                       # Runtime env vars
    DATABASE_URL: postgresql://postgres:postgres@localhost:5432/SIMULATION_ID
    LLM_PROVIDER: ${LLM_PROVIDER}

Services

Available services

Name	Protocol	Default Port	Mocks
`calendar`	HTTPS	8003	Google Calendar API
`salesforce`	HTTPS	8002	Salesforce REST API
`mcp/stripe`	HTTP	8004	Stripe (MCP server)
`mcp/shopify-storefront`	HTTP	8011	Shopify Storefront
`mcp/shopify-customer`	HTTP	8012	Shopify Customer Account
`postgres`	TCP/HTTP	5432/8005	PostgreSQL database
`oracle`	HTTP	8006	Oracle Fusion Cloud
`atlassian/jira`	HTTPS	8007	Jira Cloud API
`atlassian/confluence`	HTTPS	8009	Confluence Cloud API

dns_aliases

List of domains your agent calls. These are added to /etc/hosts and routed to the mock service via nginx. Only needed for HTTPS services.


services:
  - name: salesforce
    dns_aliases:
      - myorg.my.salesforce.com
      - login.salesforce.com

config

Service-specific environment variables passed to the mock service process.

Actor

The actor section configures the simulated user (persona). You can also use persona: as a top-level key — it’s an alias for actor:.

Init (pre-connection setup)

Use init when your agent requires a setup step before messaging — like creating a conversation, obtaining a session token, or authenticating.


actor:
  init:
    type: http
    method: POST
    url: http://localhost:8080/api/v1/conversations
    body:
      banker_id: "B001"
      branch_id: "BR01"
    response:
      message_field: content           # Capture initial message from response
  channels:
    - type: http
      url: http://localhost:8080/api/v1/conversations/{conversation_id}/messages
      request:
        message_field: content
      response:
        message_field: content

The init step makes a single HTTP call, captures all response fields as variables, and substitutes {variable} placeholders in channel URLs, headers, and static_fields.

Migrating from start_url: If your config uses start_url / start_request / start_response on a channel, move that logic to an init block on the actor. The old fields still work but are deprecated.

Channel types

HTTP


actor:
  channels:
    - type: http
      url: http://localhost:8008
      method: POST
      headers:
        Content-Type: application/json
        Authorization: Bearer test-token
      request:
        message_field: message        # JSON field for user message
        session_field: session_id      # Session tracking field
        static_fields:                 # Extra fields per request
          prompt_type: default
      response:
        type: json                     # json or sse
        message_field: response        # Field containing agent reply
        session_field: session_id

WebSocket


actor:
  channels:
    - type: ws
      url: ws://localhost:8008/ws
      request:
        message_field: message
        session_field: session_id
      response:
        message_field: response

Email


actor:
  channels:
    - type: email
      email_address: agent@ea.veris.ai

SSE Streaming

For agents that stream responses via Server-Sent Events:


actor:
  channels:
    - type: http
      url: http://localhost:8008/chat
      method: POST
      request:
        message_field: message
      response:
        type: sse
        chunk_event: chunk          # SSE event name for chunks
        chunk_field: chunk          # Field in chunk event data
        done_event: end_turn        # SSE event signaling completion

Voice

For agents that handle phone/voice interactions:


actor:
  channels:
    - type: voice

Browser-use

For agents with a web UI that users interact with via a browser:


actor:
  channels:
    - type: browser-use
      url: http://localhost:3000

Actor config

Variable	Default	Description
`RESPONSE_INTERVAL`	`2`	Seconds between actor turns
`POLL_INTERVAL`	`15`	Email polling interval (seconds)
`REFLECTION_INTERVAL`	`3`	Turns between actor self-reflection

Agent

Fields

Field	Default	Description
`code_path`	`/app`	Directory where your agent code lives
`entry_point`	—	Command to start your agent (required)
`port`	`8008`	Port your agent listens on
`environment`	—	Environment variables (key-value map)

Environment variable expansion

Values in environment support shell-style expansion:


agent:
  environment:
    LLM_PROVIDER: ${LLM_PROVIDER}   # From container env
    DB_NAME: myapp_${SIMULATION_ID}  # Dynamic per simulation

Variables set with veris env set on the platform take precedence over values defined here. Use veris env set --secret for API keys and other sensitive values — never put secrets in veris.yaml.

Complete Examples

Calendar agent (HTTP)

.veris/veris.yaml


services:
  - name: calendar
    dns_aliases:
      - www.googleapis.com
      - calendar.google.com
 
actor:
  channels:
    - type: http
      url: http://localhost:8008/chat
      method: POST
      request:
        message_field: message
        session_field: session_id
      response:
        type: json
        message_field: response
 
agent:
  code_path: /agent
  entry_point: python -m app.main
  port: 8008
  environment:
    GOOGLE_APPLICATION_CREDENTIALS: /certs/mock-service-account.json

Email support agent (Salesforce + Postgres)

.veris/veris.yaml


services:
  - name: salesforce
    dns_aliases:
      - myorg.my.salesforce.com
  - name: postgres
 
actor:
  channels:
    - type: email
      email_address: support@ea.veris.ai
  config:
    POLL_INTERVAL: "10"
 
agent:
  entry_point: python -m app.server
  port: 8008
  environment:
    DATABASE_URL: postgresql://postgres:postgres@localhost:5432/support

WebSocket chat agent (Stripe MCP)

.veris/veris.yaml


services:
  - name: mcp/stripe
  - name: postgres
 
actor:
  channels:
    - type: ws
      url: ws://localhost:8008/ws
      request:
        message_field: content
        session_field: thread_id
      response:
        message_field: content
 
agent:
  entry_point: uvicorn app.main:app --host 0.0.0.0 --port 8008
  port: 8008

Banking agent with init (conversation creation)

.veris/veris.yaml


services:
  - name: hogan
    dns_aliases:
      - api.hogan.dxc.com
 
actor:
  init:
    type: http
    method: POST
    url: http://localhost:8080/api/v1/conversations
    body:
      banker_id: "B001"
      branch_id: "BR01"
      customer_ecn: "ECN123"
  channels:
    - type: http
      method: POST
      url: http://localhost:8080/api/v1/conversations/{conversation_id}/messages
      request:
        message_field: content
      response:
        message_field: content
 
agent:
  code_path: /agent
  entry_point: uv run --no-sync uvicorn app.main:app --port 8080
  port: 8080

Validation

veris.yaml is validated at load time using a Pydantic model (VerisConfig). Invalid configs produce clear error messages pointing to the exact field.

Legacy format support

Legacy syntax	Equivalent	Notes
`persona:`	`actor:`	Top-level alias
`modality:` (singular dict)	`channels: [...]` (list)	Auto-wrapped
`init.request.url` (nested)	`init.url` (flat)	Auto-flattened
`email_address` on channel	`agent_inbox`	Auto-renamed
`type: websocket`	`type: ws`	Auto-normalized

All legacy formats are accepted and silently normalized. No migration is required.