v1.2.0

Documentation

Everything you need to deploy, monitor, and manage AI agents on your own infrastructure. From first install to production federation.

Getting Started

Install Volra and deploy your first agent in under 5 minutes.

Installation

Three ways to install Volra on macOS or Linux.

Recommended: Install Script

Terminal

$ curl -fsSL https://raw.githubusercontent.com/romerox3/volra/main/install.sh | sh

Homebrew

Terminal

$ brew install romerox3/volra/volra

From Source

Terminal

$ git clone https://github.com/romerox3/volra.git
$ cd volra
$ make build
$ ./bin/volra --version

Tip: After installing, run volra doctor to verify all prerequisites (Docker, Compose, Python) are met.

Quick Start

Deploy your first AI agent in 5 steps.

1. Scaffold a project

Terminal

$ volra quickstart langgraph my-agent

2. Add your API key

Terminal

$ cd my-agent
$ echo "OPENAI_API_KEY=sk-..." > .env

3. Deploy

Terminal

$ volra deploy
✓ Agentfile validated
✓ Docker Compose generated
✓ Image built (12.3s)
✓ Services started
✓ Agent healthy (http://localhost:8000)
✓ Grafana ready (http://localhost:3001)

4. Check status

Terminal

$ volra status

5. Open Grafana

Visit http://localhost:3001 to see your agent's monitoring dashboard. Default credentials: admin / admin.

Note: Volra generates Docker Compose, Prometheus, Grafana, and Blackbox Exporter — all preconfigured. No manual setup needed.

Core Concepts

Key ideas behind how Volra works.

Agentfile

A YAML file that describes your agent — name, framework, port, health endpoint, services, observability level, and more. Like a Dockerfile for AI agents.

.volra/ Directory

Local state directory created by Volra. Contains baselines, audit logs, compliance docs, and the control plane SQLite database.

The Stack

Every deployment generates: your agent container + Prometheus (metrics) + Grafana (dashboards) + Blackbox Exporter (health probes). All wired together automatically.

Framework Detection

Volra auto-detects LangGraph, CrewAI, or Generic frameworks from your dependencies. Priority: LangGraph > CrewAI > Generic.

Framework Guides

Step-by-step guides for each supported agent framework.

LangChain / LangGraph

Deploy a LangGraph ReAct agent with tool-calling.

Scaffold

$ volra quickstart langgraph my-langraph-agent

This creates a LangGraph project with a ReAct agent, tool-calling loop, and FastAPI server. The generated Agentfile:

Agentfile

version: 1
name: my-langgraph-agent
framework: langgraph
port: 8000
health_path: /health
dockerfile: auto
package_manager: pip

env:
  - OPENAI_API_KEY

observability:
  level: 2
  metrics_port: 9101

Tip: Level 2 observability adds LLM-level metrics (token counts, latency per call, tool usage) via the volra-observe Python package.

Deploy & verify

$ cd my-langgraph-agent
$ echo "OPENAI_API_KEY=sk-..." > .env
$ volra deploy
$ curl http://localhost:8000/ask -d '{"question": "What is LangGraph?"}'

CrewAI

Deploy multi-agent crews with role-based task execution.

Scaffold

$ volra quickstart crewai my-crew

Creates a CrewAI project with a multi-agent research crew. Also available: crewai-team (3-agent dev team) and crewai-researcher (single research agent).

Agentfile

version: 1
name: my-crew
framework: crewai
port: 8000
health_path: /health
dockerfile: auto
package_manager: pip

env:
  - OPENAI_API_KEY

Deploy

$ cd my-crew
$ echo "OPENAI_API_KEY=sk-..." > .env
$ volra deploy

OpenAI Agents

Deploy agents using the OpenAI Agents SDK with tools and handoffs.

Scaffold

$ volra quickstart openai-agents my-openai-agent

Creates a project using the OpenAI Agents SDK with tool use and handoff capabilities. Also available: openai-swarm (multi-agent handoffs) and openai-assistant (Assistants API).

Deploy

$ cd my-openai-agent
$ echo "OPENAI_API_KEY=sk-..." > .env
$ volra deploy

Generic / FastAPI

Deploy any Python agent without a specific framework.

Scaffold

$ volra quickstart basic my-agent

Creates a minimal FastAPI agent with health and ask endpoints. Perfect for custom agents, MCP servers, or any Python HTTP service.

Agentfile

version: 1
name: my-agent
framework: generic
port: 8000
health_path: /health
dockerfile: auto

Note: For existing projects, use volra init . to auto-detect your setup and generate an Agentfile.

Deploy & Operate

Docker, Kubernetes, dev mode, monitoring, alerting, and evaluation.

Docker Deploy

The default deployment target. Generates Docker Compose with a full monitoring stack.

Deploy Pipeline

When you run volra deploy, the following happens:

Validate — Parse and validate Agentfile
Generate — Create docker-compose.yml, Dockerfile (if auto), prometheus.yml, Grafana provisioning
Build — Build agent Docker image
Up — Start all containers with docker compose up -d
Health Check — Poll health_path until healthy or timeout

Dry Run

Generate files without deploying:

Terminal

$ volra deploy --dry-run
Generated files:
  → docker-compose.yml
  → Dockerfile
  → prometheus.yml
  → grafana/provisioning/...

Stop Services

Terminal

$ volra down           # Stop containers, keep data
$ volra down -v        # Stop containers and remove volumes

Kubernetes Deploy

Generate K8s manifests and deploy with kubectl.

Deploy to K8s

$ volra deploy --target k8s
✓ Agentfile validated
✓ K8s manifests generated
✓ kubectl apply successful
✓ Agent healthy

Generates: Deployment, Service, ConfigMap, ServiceMonitor (for Prometheus Operator). Use dry-run to inspect:

Terminal

$ volra deploy --target k8s --dry-run

Warning: Requires kubectl configured with access to your cluster. Volra uses kubectl apply — not client-go.

Dev Mode

Hot-reload development with Docker Compose watch.

Terminal

$ volra dev
✓ Development mode started
  Watching for changes...
  Agent: http://localhost:8000
  Grafana: http://localhost:3001

Uses Docker Compose watch mode — file changes are synced to the container and the agent restarts automatically. Press Ctrl+C to stop.

Note: Requires Docker Compose v2.22+ for watch support. Run volra doctor to verify.

Monitoring & Grafana

Two levels of observability — HTTP probes and LLM-level metrics.

Level 1 — HTTP Probes

Default. Blackbox Exporter probes your health endpoint. Metrics: uptime, response time, HTTP status codes. Zero code changes needed.

Level 2 — LLM Metrics

Add volra-observe to your agent. Tracks: token counts, LLM latency, tool calls, error rates. Framework-agnostic.

Enable Level 2

Agentfile

observability:
  level: 2
  metrics_port: 9101

Install Python package

$ pip install volra-observe

Then instrument your agent code with the volra-observe decorators. See the volra-observe README for details.

Alerting

Get notified when your agent has issues — via Slack, email, or webhook.

Agentfile — alerts section

alerts:
  channels:
    - type: slack
      webhook_url_env: SLACK_WEBHOOK_URL
    - type: email
      to: [email protected]
      smtp_env: SMTP_CONFIG
    - type: webhook
      url: https://hooks.example.com/alerts

  rules:
    - name: HighErrorRate
      expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1
      for: 5m
      severity: critical
    - name: SlowResponses
      expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 2
      for: 10m
      severity: warning

Volra generates Alertmanager configuration from your alerts section. Default rules (agent down, high error rate) are included automatically.

Evaluation & Baselines

Track performance over time and detect regressions automatically.

Define Metrics

Agentfile — eval section

eval:
  baseline_window: 1h
  metrics:
    - name: response_time_p95
      query: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
      threshold: 20
      unit: seconds
    - name: success_rate
      query: rate(http_requests_total{status="200"}[5m]) / rate(http_requests_total[5m]) * 100
      threshold: 5
      unit: percent

Record & Run

Terminal

$ volra eval record
✓ Baseline recorded → .volra/baselines/2026-03-09T10:00:00.json

$ volra eval run
Evaluating against baseline...
  response_time_p95: 267ms (+8.9%) ✓ within 20% threshold
  success_rate: 98.8% (-0.4%) ✓ within 5% threshold

Tip: Record a baseline after each successful deployment. Run evaluations in CI to catch regressions before they reach production.

Platform

Control plane, authentication, federation, gateway, and marketplace.

Control Plane & Console

Centralized management API and web dashboard.

Start the server

$ volra server
✓ Control plane started on :4441
  API: http://localhost:4441/api
  Console: http://localhost:4441
  Health: http://localhost:4441/health

The control plane provides:

REST API — Manage agents programmatically (see API Reference)
Web Console — htmx + Alpine.js dashboard at the root URL
SQLite Store — Agent registry, API keys, configuration
Metrics Proxy — Aggregated Prometheus metrics from all agents

Custom port

$ volra server --port 8080

RBAC & API Keys

Role-based access control for the control plane API.

Roles

Role	Description	Endpoints
admin	Full access — create/revoke keys, deploy, stop, view	All
operator	Deploy and manage agents — deploy, stop, view	GET /api/, POST /api/agents//deploy, POST /api/agents/*/stop
viewer	Read-only access — list and view agents	GET /api/*

Manage Keys

Terminal

$ volra auth create-key --name "ci-deploy" --role admin
✓ API key created
  Key: vk_a1b2c3d4e5f6... (save this — shown only once)

$ volra auth list-keys
ID    Name       Role      Created
1     ci-deploy  admin     2026-03-09

$ volra auth revoke-key 1

Using API Keys

Terminal

$ curl -H "Authorization: Bearer vk_a1b2c3d4e5f6" \
  http://localhost:4441/api/agents

Federation

Connect multiple Volra control planes for cross-server agent management.

Terminal

$ volra federation add https://server2.example.com --key vk_abc123
✓ Peer added: https://server2.example.com
  Agents: 5 remote agents discovered

$ volra federation list
URL                              Status    Agents
https://server2.example.com      healthy   5
https://server3.example.com      healthy   3

$ volra federation remove https://server2.example.com

Federated peers share agent registries and health status. All agents — local and remote — appear in the web console.

MCP Gateway

Aggregate tools from multiple agents via Model Context Protocol.

Terminal

$ volra gateway start
✓ Gateway started on :4440
  Tools: 12 (from 3 agents)
  Transport: Streamable HTTP

$ volra gateway tools
research-agent/web_search
research-agent/summarize
coder/generate_code
coder/review_code

$ volra gateway reload   # Rebuild catalog after changes

The gateway uses namespace routing: agent-name/tool-name. Tools from all registered agents are accessible via a single MCP endpoint.

Tip: Point your MCP client (Cursor, VS Code, Claude Code) at http://localhost:4440 to access all tools from all agents in one connection.

Marketplace

Discover and install community agent templates.

Terminal

$ volra marketplace search rag
Found 3 templates:
  rag             — RAG agent with ChromaDB + Redis
  pgvector-rag    — Hybrid search with pgvector
  langchain-rag   — LangChain RAG with embeddings

$ volra marketplace install advanced-rag
✓ Template installed → ./advanced-rag

Templates are sourced from the Volra marketplace GitHub index. Anyone can contribute templates via pull request.

Reference

Complete specification for CLI, Agentfile, API, error codes, and templates.

CLI Commands

Complete reference for all Volra CLI commands.

Note: All commands support the --json global flag for structured output.

volra doctor

Verifies Docker, Docker Compose, available ports, Python, and disk space. Run this first to ensure your system is ready.

Examples

Run all checks

$ volra doctor

✓ Docker installed (27.5.1)
✓ Docker running
✓ Docker Compose available (v2.32.4)
✓ Python found (3.12.0)
✓ Disk space OK (45 GB free)

All checks passed — ready to deploy!

Error codes: E101 E102 E103 E104 E105 E106

Flags

Flag	Type	Default	Description
-f, --force	bool	false	Overwrite existing Agentfile

Examples

Initialize current directory

$ volra init .

Detected framework: langgraph
Detected entry point: agent/main.py
Generated Agentfile

Initialize with force overwrite

$ volra init . --force

Error codes: E201 E202 E203

Flags

Flag	Type	Default	Description
--dry-run	bool	false	Generate files without deploying
--target	string	docker	Deployment target: docker or k8s

Examples

Deploy current project

$ volra deploy

✓ Agentfile validated
✓ Docker Compose generated
✓ Image built (12.3s)
✓ Services started
✓ Agent healthy (http://localhost:8000)
✓ Grafana ready (http://localhost:3001)

Dry run to inspect generated files

$ volra deploy --dry-run

Deploy to Kubernetes

$ volra deploy --target k8s

Error codes: E301 E302 E303 E304 E305 E307 E308

Examples

Check deployment status

$ volra status

Agent: my-agent (healthy)
  Container: my-agent-agent-1 (running, 2h uptime)
  Port: http://localhost:8000
  Health: ✓ /health (200 OK)

Services:
  prometheus: running (http://localhost:9090)
  grafana: running (http://localhost:3001)

Error codes: E401 E402

Flags

Flag	Type	Default	Description
-f, --follow	bool	false	Follow log output (stream)
-n, --lines	int	100	Number of lines to show

Examples

View recent agent logs

$ volra logs

Stream logs in real-time

$ volra logs -f

View Prometheus logs

$ volra logs prometheus

Show last 50 lines

$ volra logs -n 50

Examples

Launch interactive TUI

$ volra quickstart

Create from template directly

$ volra quickstart langgraph my-agent

Create a CrewAI project

$ volra quickstart crewai research-crew

Examples

Start dev mode

$ volra dev

✓ Development mode started
  Watching for changes...
  Agent: http://localhost:8000
  Grafana: http://localhost:3001

Error codes: E601 E602

Flags

Flag	Type	Default	Description
-v, --volumes	bool	false	Also remove volumes (data)

Examples

Stop services (keep data)

$ volra down

Stop and remove all data

$ volra down -v

Error codes: E601

Examples

Update to latest

$ volra update

Current: v0.9.0
Latest: v1.0.0
Downloading... done
✓ Updated to v1.0.0

volra eval [record|run] [path]

Record baselines from Prometheus metrics, then run evaluations to detect regressions. Uses PromQL queries defined in your Agentfile's eval section.

Examples

Record a baseline

$ volra eval record

✓ Baseline recorded → .volra/baselines/2026-03-09T10:00:00.json
  response_time_p95: 245ms
  success_rate: 99.2%
  tokens_per_request: 1,847

Run evaluation against baseline

$ volra eval run

Evaluating against baseline (2026-03-09T10:00:00)...
  response_time_p95: 267ms (+8.9%) ✓ within 20% threshold
  success_rate: 98.8% (-0.4%) ✓ within 5% threshold
  tokens_per_request: 2,104 (+13.9%) ⚠ exceeds 10% threshold

1 regression detected

Error codes: E701 E702 E703 E704 E705

Sub-commands

volra hub start

Start unified dashboard

Examples

Start the hub

$ volra hub start

✓ Hub started
  Dashboard: http://localhost:3002
  Agents: 3 registered

Error codes: E801 E802

Examples

Stop the hub

$ volra hub stop

Examples

Check hub status

$ volra hub status

Sub-commands

volra gateway start

Start MCP gateway server

Flags

Flag	Type	Default	Description
-p, --port	int	4440	Gateway port

Examples

Start gateway on default port

$ volra gateway start

✓ Gateway started on :4440
  Tools: 12 (from 3 agents)
  Transport: Streamable HTTP

Error codes: E901 E902 E903

Examples

List gateway tools

$ volra gateway tools

research-agent/web_search
research-agent/summarize
coder/generate_code
coder/review_code
assistant/answer

5 tools from 3 agents

Error codes: E904

Examples

Reload gateway catalog

$ volra gateway reload

Flags

Flag	Type	Default	Description
--port	int	4441	Server port

Examples

Start control plane

$ volra server

✓ Control plane started on :4441
  API: http://localhost:4441/api
  Console: http://localhost:4441
  Health: http://localhost:4441/health

Start on custom port

$ volra server --port 8080

Error codes: E1401 E1402 E1403 E1501

Sub-commands

volra marketplace search [query]

Search marketplace templates

Examples

Search for RAG templates

$ volra marketplace search rag

Error codes: E1201

volra marketplace list

List all marketplace templates

Examples

List all available templates

$ volra marketplace list

Error codes: E1201

Examples

Install a template

$ volra marketplace install advanced-rag

Error codes: E1202

Flags

Flag	Type	Default	Description
--action	string	""	Filter by action type (deploy, stop, etc.)
--agent	string	""	Filter by agent name
--since	string	""	Show entries since timestamp (RFC3339)

Examples

View all audit entries

$ volra audit

Filter by agent

$ volra audit --agent my-agent

Filter by action and time

$ volra audit --action deploy --since 2026-03-01T00:00:00Z

Examples

Generate compliance docs

$ volra compliance generate

✓ Generated compliance documentation
  → .volra/compliance/risk-classification.md
  → .volra/compliance/data-handling.md
  → .volra/compliance/transparency.md

Error codes: E1301

Sub-commands

volra auth create-key --name <name> --role <role>

Create a new API key

Flags

Flag	Type	Default	Description
--name	string	—	Key name (required)
--role	string	viewer	Key role: admin, operator, or viewer

Examples

Create an admin key

$ volra auth create-key --name "ci-deploy" --role admin

✓ API key created
  Name: ci-deploy
  Role: admin
  Key: vk_a1b2c3d4e5f6... (save this — shown only once)

Error codes: E1701

See also: auth list-keys auth revoke-key

volra auth list-keys

List all API keys

Examples

List keys

$ volra auth list-keys

ID    Name       Role      Created
1     ci-deploy  admin     2026-03-09
2     dashboard  viewer    2026-03-09

Examples

Revoke key by ID

$ volra auth revoke-key 2

Sub-commands

volra federation add <url>

Add a federation peer

Flags

Flag	Type	Default	Description
--key	string	—	API key for the remote server

Examples

Add a peer

$ volra federation add https://server2.example.com --key vk_abc123

✓ Peer added: https://server2.example.com
  Status: healthy
  Agents: 5 remote agents discovered

Error codes: E1801 E1802

volra federation remove <url>

Remove a federation peer

Examples

Remove a peer

$ volra federation remove https://server2.example.com

Examples

List peers

$ volra federation list

URL                              Status    Agents
https://server2.example.com      healthy   5
https://server3.example.com      healthy   3

Flags

Flag	Type	Default	Description
--local	bool	false	Show only local agents (skip federation)

Examples

List all agents (local + federated)

$ volra agents

SERVER              AGENT             FRAMEWORK    PORT   STATUS
local               research-agent    langgraph    8000   healthy
local               code-reviewer     crewai       8001   healthy
prod.example.com    support-bot       generic      8000   healthy

2 local, 1 federated

List local agents only

$ volra agents --local

JSON output for scripting

$ volra agents --json

Error codes: E1901 E1902 E2003

Examples

Start MCP server (used by editors)

$ volra mcp

Agentfile Spec

Complete reference for all Agentfile fields.

Interactive Builder

Agentfile Builder

name *

framework *

port *

host_port

health_path *

dockerfile *

package_manager

env (comma-separated)

observability

services

GPU Security hardened

Agentfile

Field Reference

Required Fields

version int required

Agentfile schema version. Currently only version 1 is supported.

Validation: Must be 1

version: 1

name string required

Agent project name. Used as Docker image name and service prefix.

Validation: 2-63 characters, DNS label format (lowercase alphanumeric + hyphens, must start/end with letter)

name: my-research-agent

framework enum required

Agent framework type. Determines auto-detection behavior and default templates.

Validation: generic, langgraph, or crewai

framework: langgraph

port int required

Internal container port where the agent listens.

Validation: 1-65535

port: 8000

health_path string required

HTTP endpoint for health checks. Volra polls this after deploy to verify the agent is running.

Validation: Must start with /

health_path: /health

dockerfile enum required

Dockerfile management mode. 'auto' generates a Dockerfile; 'custom' uses your existing one.

Validation: auto or custom

dockerfile: auto

Networking

host_port int optional

Host port mapping for the agent. If not set, the container port is used directly.

Validation: 1-65535

host_port: 9000

health_timeout int optional default: 60

Seconds to wait for the health check to pass after deployment.

Validation: 10-600

health_timeout: 120

Build & Runtime

package_manager enum optional default: pip

Python package manager used to install dependencies.

Validation: pip, poetry, uv, or pipenv

package_manager: uv

env string[] optional

Environment variable names to pass from .env file to the agent container.

Validation: No empty entries, no duplicates

env:
  - OPENAI_API_KEY
  - DATABASE_URL

volumes string[] optional

Volume mounts for persistent data. Paths are relative to the project directory.

Validation: Max 10 volumes, absolute paths, no /app/* (reserved), no duplicates

volumes:
  - /data/chroma
  - /data/cache

gpu bool optional default: false

Enable GPU passthrough to the agent container (NVIDIA runtime).

gpu: true

build object optional

Build-time configuration. Only valid with dockerfile: auto.

build:
  setup_commands:
    - apt-get update && apt-get install -y ffmpeg
  cache_dirs:
    - /root/.cache/pip

Observability

observability object optional

Observability configuration. Level 1 = HTTP probe only. Level 2 = LLM-level metrics via volra-observe Python package.

observability:
  level: 2
  metrics_port: 9101

Security

security object optional

Container security settings. Read-only filesystem, privilege escalation controls, and capability drops.

security:
  read_only: true
  no_new_privileges: true
  drop_capabilities:
    - ALL
  tmpfs:
    - path: /tmp
      size: 100m

Services

services map[string]Service optional

Additional infrastructure services (databases, caches, etc.). Max 5 services. Reserved names: agent, prometheus, grafana, blackbox.

services:
  redis:
    image: redis:7-alpine
    port: 6379
    host_port: 6380
  postgres:
    image: postgres:16-alpine
    port: 5432
    env:
      - POSTGRES_PASSWORD
    volumes:
      - /var/lib/postgresql/data

Evaluation

eval object optional

Evaluation configuration for regression detection. Define metrics with PromQL queries and threshold percentages.

eval:
  baseline_window: 1h
  metrics:
    - name: response_time_p95
      query: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
      threshold: 20
      unit: seconds
    - name: success_rate
      query: rate(http_requests_total{status="200"}[5m]) / rate(http_requests_total[5m]) * 100
      threshold: 5
      unit: percent

Alerting

alerts object optional

Alerting configuration. Define notification channels (Slack, email, webhook) and custom Prometheus alert rules.

alerts:
  channels:
    - type: slack
      webhook_url_env: SLACK_WEBHOOK_URL
    - type: email
      to: [email protected]
      smtp_env: SMTP_CONFIG
  rules:
    - name: HighErrorRate
      expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1
      for: 5m
      severity: critical

Full Example

Agentfile (complete)

version: 1
name: research-agent
framework: langgraph
port: 8000
health_path: /health
dockerfile: auto
package_manager: uv

env:
  - OPENAI_API_KEY
  - TAVILY_API_KEY

volumes:
  - /data/cache

services:
  redis:
    image: redis:7-alpine
    port: 6379

observability:
  level: 2
  metrics_port: 9101

security:
  read_only: true
  no_new_privileges: true
  drop_capabilities:
    - ALL
  tmpfs:
    - path: /tmp
      size: 100m

eval:
  baseline_window: 1h
  metrics:
    - name: response_time_p95
      query: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
      threshold: 20
      unit: seconds

alerts:
  channels:
    - type: slack
      webhook_url_env: SLACK_WEBHOOK_URL
  rules:
    - name: HighErrorRate
      expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1
      for: 5m
      severity: critical

a2a:
  mode: declarative
  skills:
    - id: research
      name: research
      endpoint: /ask
    - id: search
      name: semantic-search
      endpoint: /search
      request_field: query
      response_field: documents

REST API

Control plane REST API reference. Base URL: http://localhost:4441

Note: Authentication via Bearer token in the Authorization header. Create keys with volra auth create-key.

GET /health No auth

Server health check. Returns 200 if the control plane is running.

curl

curl http://localhost:4441/health

Response

{"status": "ok"}

GET /api/agents viewer+

List all registered agents with their current status, ports, and health information.

curl

curl -H "Authorization: Bearer vk_your_api_key" \
  http://localhost:4441/api/agents

Response

[
  {
    "name": "research-agent",
    "status": "healthy",
    "port": 8000,
    "framework": "langgraph",
    "uptime": "2h34m"
  },
  {
    "name": "coder-agent",
    "status": "healthy",
    "port": 8001,
    "framework": "crewai",
    "uptime": "1h12m"
  }
]

GET /api/agents/{name} viewer+

Get detailed information about a specific agent including configuration, metrics, and service status.

Parameters

name (path) — Agent name

curl

curl -H "Authorization: Bearer vk_your_api_key" \
  http://localhost:4441/api/agents/research-agent

Response

{
  "name": "research-agent",
  "status": "healthy",
  "port": 8000,
  "framework": "langgraph",
  "uptime": "2h34m",
  "services": {
    "prometheus": "running",
    "grafana": "running",
    "redis": "running"
  }
}

POST /api/agents/{name}/deploy operator+

Trigger deployment of an agent. Returns 202 Accepted and deploys asynchronously.

Parameters

name (path) — Agent name

curl

curl -X POST \
  -H "Authorization: Bearer vk_your_api_key" \
  http://localhost:4441/api/agents/research-agent/deploy

Response

{
  "status": "accepted",
  "message": "Deployment started for research-agent"
}

POST /api/agents/{name}/stop operator+

Stop a running agent and all its services.

Parameters

name (path) — Agent name

curl

curl -X POST \
  -H "Authorization: Bearer vk_your_api_key" \
  http://localhost:4441/api/agents/research-agent/stop

Response

{
  "status": "ok",
  "message": "Agent research-agent stopped"
}

Error Codes

All Volra error codes with causes and fixes.

Prerequisites

E101 Docker not installed

Cause: Docker CLI not found in PATH

Fix: Install Docker Desktop or Docker Engine from https://docs.docker.com/get-docker/

Commands: doctor

E102 Docker not running

Cause: Docker daemon is not active

Fix: Start Docker Desktop or run `sudo systemctl start docker`

Commands: doctor deploy

E103 Docker Compose not available

Cause: Docker Compose plugin not installed

Fix: Install Docker Compose: `docker compose version` should work. See https://docs.docker.com/compose/install/

Commands: doctor

E104 Port in use

Cause: A required port is already occupied by another process

Fix: Free the port or configure a different host_port in your Agentfile

Commands: doctor deploy

E105 Python not found

Cause: Python 3.x not found in PATH

Fix: Install Python 3.8+ from https://python.org

Commands: doctor

E106 Insufficient disk space

Cause: Less than 2 GB free disk space

Fix: Free up disk space. Docker images can be large — run `docker system prune` to clean up

Commands: doctor

Setup

E201 No Python project detected

Cause: No requirements.txt, pyproject.toml, or setup.py found

Fix: Ensure you're in a Python project directory with a dependency file

Commands: init

E202 No entry point found

Cause: Could not auto-detect main.py, app.py, or server.py

Fix: Create an entry point file or use `volra quickstart` to scaffold a project

Commands: init

E203 Agentfile already exists

Cause: An Agentfile already exists in this directory

Fix: Use `--force` flag to overwrite: `volra init . --force`

Commands: init

Deploy

E301 Docker not running

Cause: Docker daemon is not active when trying to deploy

Fix: Start Docker and try again. Run `volra doctor` to verify

Commands: deploy

E302 Build failed

Cause: Docker image build failed (dependency install, syntax error, etc.)

Fix: Check the build output for errors. Common causes: missing dependencies, invalid Dockerfile, network issues

Commands: deploy

E303 Health check failed

Cause: Agent didn't respond on health_path within health_timeout seconds

Fix: Verify health_path and port in Agentfile. Check logs with `volra logs`. Increase health_timeout if the agent needs more startup time

Commands: deploy status

E304 OOM killed

Cause: Container ran out of memory

Fix: Increase memory limit in services.agent.resources.mem_limit or reduce model size

Commands: deploy

E305 .env file not found

Cause: Agentfile references env vars but no .env file exists

Fix: Create a .env file with the required variables listed in the Agentfile env section

Commands: deploy

E307 GPU not available

Cause: gpu: true but NVIDIA runtime not detected

Fix: Install NVIDIA Container Toolkit: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html

Commands: deploy

E308 GPU check failed

Cause: Could not verify GPU availability

Fix: Run `docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi` to verify GPU setup

Commands: deploy

Status

E401 No deployment found

Cause: No running containers found for this project

Fix: Deploy first with `volra deploy`

Commands: status

E402 Docker not running

Cause: Docker daemon is not active

Fix: Start Docker and try again

Commands: status

Schema

E501 Invalid Agentfile

Cause: Agentfile has validation errors (missing required fields, invalid values)

Fix: Check the Agentfile spec. Common issues: missing name/port/framework, invalid DNS name, port out of range

Commands: deploy init

E502 Unsupported version

Cause: Agentfile version field is not 1

Fix: Set `version: 1` in your Agentfile

Commands: deploy

Lifecycle

E601 No deployment found

Cause: No running deployment to stop or attach to

Fix: Deploy first with `volra deploy`

Commands: down dev

E602 Docker Compose watch required

Cause: Docker Compose version doesn't support watch mode

Fix: Update Docker Compose to v2.22+ for `volra dev` support

Commands: dev

Eval

E701 No baseline recorded

Cause: Running eval without recording a baseline first

Fix: Record a baseline: `volra eval record`

Commands: eval

E702 Prometheus unreachable

Cause: Can't connect to the Prometheus instance

Fix: Ensure the agent is deployed and Prometheus is running. Check with `volra status`

Commands: eval

E703 Invalid eval config

Cause: Agentfile eval section has validation errors

Fix: Check eval metrics: each needs name, query, and threshold (> 0)

Commands: eval

E704 PromQL query failed

Cause: A metric query returned an error from Prometheus

Fix: Verify PromQL syntax in the eval.metrics[].query field

Commands: eval

E705 Regression detected

Cause: One or more metrics exceed their regression threshold

Fix: Review the regression report. Adjust thresholds or fix the performance issue

Commands: eval

Hub

E801 No agents registered

Cause: Hub requires at least one deployed agent

Fix: Deploy at least one agent first: `volra deploy`

Commands: hub

E802 Hub already running

Cause: A hub instance is already running

Fix: Stop it first with `volra hub stop` then start again

Commands: hub

Gateway

E901 No agents for gateway

Cause: No MCP-capable agents found

Fix: Deploy agents with MCP tool definitions first

Commands: gateway

E902 Spawn failed

Cause: Failed to start a backend subprocess for an agent

Fix: Check agent logs and verify the agent binary/script is accessible

Commands: gateway

E903 Gateway init failed

Cause: Gateway server failed to start

Fix: Check if the port is available. Try a different port: `volra gateway start --port 4442`

Commands: gateway

E904 List tools failed

Cause: Could not enumerate tools from one or more agents

Fix: Verify agents are running and exposing MCP tools correctly

Commands: gateway

E905 Agent discovery timeout

Cause: Timed out waiting for agent to report its tools

Fix: Check agent health. The agent may be slow to start — try again

Commands: gateway

Marketplace

E1201 Marketplace fetch failed

Cause: Could not download the marketplace index from GitHub

Fix: Check your internet connection. The index is at github.com/romerox3/volra-marketplace

Commands: marketplace

E1202 Template not found

Cause: The requested template doesn't exist in the marketplace

Fix: Use `volra marketplace search` to find available templates

Commands: marketplace

Compliance

E1301 No Agentfile for compliance

Cause: No Agentfile found to generate compliance docs from

Fix: Run from a directory with an Agentfile, or initialize one: `volra init .`

Commands: compliance

Control Plane

E1401 Control plane start failed

Cause: Server failed to bind to the specified port

Fix: Check if port 4441 is in use. Try: `volra server --port 4442`

Commands: server

E1402 Control plane DB failed

Cause: SQLite database could not be opened or created

Fix: Check file permissions in .volra/ directory. Ensure disk space is available

Commands: server

E1403 Metrics proxy failed

Cause: Could not proxy metrics from Prometheus instances

Fix: Verify Prometheus is running for deployed agents

Commands: server

Console

E1501 Console assets missing

Cause: Embedded console HTML/JS/CSS assets not found

Fix: This is a build issue. Reinstall Volra: `volra update`

Commands: server

Kubernetes

E1601 K8s manifest generation failed

Cause: Could not generate Kubernetes YAML from Agentfile

Fix: Check Agentfile for invalid fields. Run `volra deploy --dry-run --target k8s` to see errors

Commands: deploy

E1602 kubectl not found

Cause: kubectl CLI not found in PATH

Fix: Install kubectl: https://kubernetes.io/docs/tasks/tools/

Commands: deploy

E1603 kubectl apply failed

Cause: kubectl apply returned an error

Fix: Check the error output. Common causes: cluster unreachable, RBAC issues, invalid manifests

Commands: deploy

RBAC

E1701 API key creation failed

Cause: Could not create API key (database error or invalid parameters)

Fix: Check that the control plane DB is accessible. Verify --name and --role flags

Commands: auth

E1702 Authentication failed

Cause: Invalid or missing API key

Fix: Provide a valid API key via Authorization header: `Bearer vk_your_key`

Commands: auth server

E1703 Authorization failed

Cause: API key doesn't have sufficient permissions for this action

Fix: Use a key with the required role. Admin > Operator > Viewer. Create a new key with `volra auth create-key --role admin`

Commands: auth

Federation

E1801 Federation peer unreachable

Cause: Could not connect to the remote control plane

Fix: Verify the URL is correct and the remote server is running

Commands: federation

E1802 Federation auth failed

Cause: API key rejected by the remote server

Fix: Verify the --key flag value. The key must be valid on the remote server

Commands: federation

A2A

E1901 A2A card fetch failed

Cause: Could not fetch the agent card from the remote agent's /.well-known/agent-card.json endpoint

Fix: Verify the agent URL is correct and the agent is running. Check network connectivity

Commands: agents federation

E1902 A2A card invalid

Cause: The fetched agent card is not valid JSON or doesn't conform to A2A v0.3 spec

Fix: Check the remote agent's card generation. The card must have name, url, and skills fields

Commands: agents federation

E1903 A2A remote call failed

Cause: Failed to send a Tasks/send request to a remote agent via A2A JSON-RPC

Fix: Verify the remote agent is running and accepts A2A requests at /a2a endpoint

Commands: gateway

E1904 A2A task failed

Cause: The remote agent returned a failed task status

Fix: Check the remote agent logs for the error. The task error message is included in the response

Commands: gateway

Mesh

E2001 Mesh tool not found

Cause: The requested tool was not found in any local or federated agent catalog

Fix: Use `volra gateway tools` to list available tools. Check namespacing: server/agent/tool for remote, agent/tool for local

Commands: gateway

E2002 Mesh namespace invalid

Cause: The tool namespace format is invalid (expected agent/tool or server/agent/tool)

Fix: Use correct namespace format: agent/tool for local tools, server/agent/tool for remote tools

Commands: gateway

E2003 All agents unreachable

Cause: None of the federated agents could be reached for capability discovery

Fix: Check federation peer health with `volra federation list`. Verify network connectivity to remote servers

Commands: federation agents

E2004 Federation down

Cause: The control plane's federation capabilities endpoint is unreachable

Fix: Ensure `volra server` is running. The gateway needs the control plane for federated tool discovery

Commands: server gateway

Proxy

E2101 Proxy: agent unreachable

Cause: The volra-proxy sidecar cannot connect to the agent's HTTP endpoint

Fix: Verify the agent is running and VOLRA_AGENT_URL is correct. The proxy must be able to reach the agent on the Docker network

Commands: deploy

E2102 Proxy: skill not found

Cause: A Tasks/send request referenced a skill ID not defined in the Agentfile a2a.skills section

Fix: Add the skill to your Agentfile a2a.skills section with mode: declarative, or use mode: default for zero-config

Commands: deploy

E2103 Proxy: invalid agent response

Cause: The agent returned a response that couldn't be parsed (unexpected format or missing expected field)

Fix: Verify the agent endpoint returns the expected JSON format. Check request_field and response_field in your skill config

Commands: deploy

Templates Catalog

24 built-in templates across 4 categories.

basic generic

Minimal FastAPI agent with health + ask endpoints

Getting Started

custom-agent generic

Blank canvas with TODO stubs for your own logic

Getting Started

rag generic

RAG agent with ChromaDB + Redis cache

Use Cases

conversational generic

Conversational agent with LLM, Redis + PostgreSQL

Use Cases

api-agent generic

Function-calling agent without any framework

Use Cases

mcp-server generic

MCP-compatible tool server

Use Cases

pgvector-rag generic

Hybrid search (vector + keyword) with pgvector

Use Cases

openai-assistant generic

OpenAI Assistants API with threads and code interpreter

Use Cases

langgraph langgraph

LangGraph ReAct agent with tool-calling loop

Frameworks

crewai crewai

CrewAI multi-agent research crew

Frameworks

openai-agents generic

OpenAI Agents SDK with tools and handoffs

Frameworks

smolagents generic

HuggingFace code agent with tool use

Frameworks

langchain-chatbot langgraph

LangChain chatbot with conversation memory

Frameworks

langchain-agent langgraph

LangChain AgentExecutor with ReAct tools

Frameworks

langchain-rag langgraph

LangChain RAG with ChromaDB and OpenAI embeddings

Frameworks

openai-swarm generic

Multi-agent handoffs via function calling

Frameworks

crewai-team crewai

3-agent dev team (PM, Dev, QA) with CrewAI

Frameworks

crewai-researcher crewai

Single research agent with web scraping tools

Frameworks

autogen-duo generic

Two-agent coder + reviewer with AutoGen

Frameworks

autogen-group generic

3+ agent group chat with approval flow

Frameworks

discord-bot generic

AI-powered Discord bot with slash commands

Platforms

slack-bot generic

AI-powered Slack bot with event handling

Platforms

web-chat generic

Full-stack chat UI with WebSocket

Platforms

fastapi-bot generic

SSE streaming chatbot with session memory

Platforms

Tip: Use any template with: volra quickstart <template-name> <directory>

Architecture

How things work under the hood and why we made certain decisions.

How Deploy Works

Step-by-step breakdown of the deploy pipeline.

Parse Agentfile

YAML parsed into Go struct. All fields validated (DNS name, port range, framework enum, volume paths, etc.).

Generate Artifacts

Docker Compose YAML generated with: agent service, Prometheus, Grafana, Blackbox Exporter. If dockerfile: auto, a Dockerfile is generated. Prometheus config wired to scrape agent metrics.

Build Image

docker compose build runs. For auto Dockerfiles: Python base image, dependency install (pip/uv/poetry), code copy, CMD. For custom: your Dockerfile is used as-is.

Start Services

docker compose up -d starts all containers. Services start in dependency order.

Health Check

Volra polls health_path every 2 seconds until it returns HTTP 200, or until health_timeout (default 60s) expires. On success: deployment complete. On timeout: E303 error.

Generated File Structure

After volra deploy

my-agent/
├── Agentfile              # Your config (source of truth)
├── .env                   # API keys (not committed)
├── docker-compose.yml     # Generated — do not edit
├── Dockerfile             # Generated (if auto)
├── prometheus.yml         # Generated
├── grafana/
│   └── provisioning/      # Dashboards + datasources
└── .volra/
    ├── baselines/          # Eval snapshots
    ├── audit.jsonl          # Audit trail
    └── volra.db             # Control plane DB

Design Decisions

Key architectural decisions and their rationale.

ADR-1

Docker Compose Watch for Dev Mode

Uses Docker Compose watch instead of fsnotify. Simpler, no Go dependency, works across platforms. Requires Compose v2.22+.

ADR-5

Eval in Agentfile (not Evalfile)

Evaluation config lives in the Agentfile's eval section. One file to rule them all — avoids config sprawl.

ADR-6

Baselines as JSON files

Stored in .volra/baselines/ as timestamped JSON. No database needed, easy to diff, git-friendly.

ADR-11

Streamable HTTP for MCP Gateway

Uses Streamable HTTP transport (not SSE). Better for request-response patterns, simpler error handling.

ADR-12

Stdio Backends for Gateway

Each gateway tool call spawns a subprocess. Simple, isolated, no connection pool management. Trade-off: higher latency per call.

ADR-14

Namespace Routing for Tools

Tools are namespaced as agent-name/tool-name. Avoids collisions when multiple agents expose same-named tools.

ADR-15

Alertmanager Integration

Generates Alertmanager config from Agentfile alerts section. Default rules included for agent down and high error rate.

ADR-18

SQLite for Control Plane

Uses modernc.org/sqlite (pure Go, no CGO). Zero external dependencies, embedded, production-grade. Trade-off: single-node only.

ADR-19

net/http for API Server

Standard library HTTP server, no framework. Fewer dependencies, Go-idiomatic, sufficient for the API surface.

ADR-20

htmx + Alpine.js for Console

Embedded HTML with htmx for dynamic updates and Alpine.js for interactions. No Node.js build step, no JavaScript framework.

ADR-21

kubectl apply for K8s

Uses kubectl CLI via exec instead of client-go. Simpler, respects user's kubeconfig, no Go K8s dependency (saves ~30MB binary size).