agentvisor serve

Start a long-running server that exposes the HTTP API for the agent.

Synopsis

agentvisor serve <path> [options]

Description

The serve command starts the AgentVisor runtime with:

HTTP API on port 8090 (configurable)
Temporal worker for durable execution
Guest sandbox management
Policy enforcement

Use this for local development and testing.

License required

agentvisor serve requires a valid Manetu license key. On a TTY the CLI prompts interactively on first run; set AGENTVISOR_LICENSE_KEY for automated or headless environments. See the Licensing guide and https://manetu.com/agentvisor to obtain a key.

Arguments

Argument	Description
`<path>`	Path to agent directory

Options

Option	Default	Description	Env Var
`--access-log-pretty-print`	`false`	Enable indented multi-line JSON for access logs	-
`--api-addr`	-	HTTP API listen address	`AGENTVISOR_API_LISTEN_ADDR`
`--bundle-mcp-tools`	`false`	Bundle MCP tools rootfs into a temporary directory for local-launch (gvisor/docker only)	-
`--cpu`	-	CPU limit for guest sandbox (e.g., 0.5, 1.0, 2.0)	-
`--debug`	`false`	Enable Python remote debugging via debugpy (unsandboxed mode only, --sandbox=none)	`AGENTVISOR_GUEST_DEBUG_ENABLED`
`--debug-opt`	-	Provider-specific options (can be repeated)	`AGENTVISOR_GUEST_DEBUG_PROVIDER_OPTIONS`
`--debug-port`	`5678`	Debug server port (default: 5678, standard debugpy port)	`AGENTVISOR_GUEST_DEBUG_PORT`
`--debug-provider`	`debugpy`	Debug provider: debugpy (default), pydevd	`AGENTVISOR_GUEST_DEBUG_PROVIDER`
`--env-files`	-	Comma-separated paths to .env files; later files override earlier (auto-discovers .env in source-dir if not specified)	`AGENTVISOR_GUEST_ENVIRONMENT_FILES`
`--guest-image`	-	Guest base image (default: ghcr.io/manetu/agentvisor/agentvisor-guest:<version>-<type>)	-
`--image`	-	Pre-built guest OCI image reference (alternative to source directory)	-
`--interpreter`	-	Override detected interpreter (e.g., python3.12)	-
`--mcp-tools-image`	-	MCP tools OCI image for bundling (default: ghcr.io/manetu/agentvisor/agentvisor-mcp-tools:<version>)	-
`--memory`	-	Memory limit for guest sandbox (e.g., 512Mi, 1Gi)	-
`--policy`	-	Path to policy domain YAML file(s), comma-separated	-
`--registry-ca-data`	-	Base64-encoded PEM CA certificate to trust when pulling guest/mcp-tools images (alternative to --registry-ca-file)	-
`--registry-ca-file`	-	Path to a PEM CA certificate to trust when pulling guest/mcp-tools images from a private registry	-
`--registry-insecure`	`false`	Skip TLS certificate verification for registry pulls; requires AGENTVISOR_TLS_ALLOW_INSECURE=true	-
`--rootless`	`true`	gVisor rootless mode; disable with --rootless=false for privileged mode	`AGENTVISOR_GUEST_ROOTLESS`
`--sandbox`	-	Sandbox mode: docker, none, gvisor (default: docker)	`AGENTVISOR_GUEST_SANDBOX`
`--temporal-api-key`	-	Temporal Cloud API key	`AGENTVISOR_TEMPORAL_AUTH_API_KEY`
`--temporal-auth-type`	-	Temporal auth type: api_key, mtls	`AGENTVISOR_TEMPORAL_AUTH_TYPE`
`--temporal-mtls-ca`	-	Path to custom CA certificate	`AGENTVISOR_TEMPORAL_AUTH_MTLS_CA_FILE`
`--temporal-mtls-ca-data`	-	Base64-encoded custom CA certificate	`AGENTVISOR_TEMPORAL_AUTH_MTLS_CA_DATA`
`--temporal-mtls-cert`	-	Path to mTLS client certificate	`AGENTVISOR_TEMPORAL_AUTH_MTLS_CERT_FILE`
`--temporal-mtls-cert-data`	-	Base64-encoded mTLS client certificate	`AGENTVISOR_TEMPORAL_AUTH_MTLS_CERT_DATA`
`--temporal-mtls-key`	-	Path to mTLS client private key	`AGENTVISOR_TEMPORAL_AUTH_MTLS_KEY_FILE`
`--temporal-mtls-key-data`	-	Base64-encoded mTLS client private key	`AGENTVISOR_TEMPORAL_AUTH_MTLS_KEY_DATA`
`--temporal-mtls-server-name`	-	TLS server name override	`AGENTVISOR_TEMPORAL_AUTH_MTLS_SERVER_NAME`
`--temporal-namespace`	-	Temporal namespace	`AGENTVISOR_TEMPORAL_NAMESPACE`
`--temporal-target`	-	Temporal server address	`AGENTVISOR_TEMPORAL_TARGET`
`--temporal-task-queue`	-	Temporal task queue	`AGENTVISOR_TEMPORAL_TASK_QUEUE`

Examples

Basic Server (Docker Mode - Default)

agentvisor serve ./my-agent

Running Without Sandbox Isolation

agentvisor serve ./my-agent --sandbox=none

Debug Mode (Interactive Debugging)

Enable remote debugging for IDE attachment (VS Code, PyCharm):

# Debug with default provider (debugpy) and port (5678)
agentvisor serve ./my-agent --sandbox=none --debug

# Debug with custom port
agentvisor serve ./my-agent --sandbox=none --debug --debug-port=5679

# Use PyCharm native debugger (pydevd)
agentvisor serve ./my-agent --sandbox=none --debug --debug-provider=pydevd

# Custom port with pydevd
agentvisor serve ./my-agent --sandbox=none --debug --debug-provider=pydevd --debug-port=5679

Each agent invocation waits for debugger attachment. See Local Development Setup for VS Code and PyCharm debugging configuration.

Single Debug Session

Only one agent can bind to the debug port at a time. In serve mode with concurrent requests, only the first agent will successfully start debugging. For debugging specific scenarios, consider using agentvisor run instead.

Debug Mode Requirements

Requires --sandbox=none (debug mode is not supported with container sandboxes)
For debugpy (default): pip install debugpy
For pydevd: pip install pydevd-pycharm

gVisor Mode (Strongest Isolation)

# Linux only - rootless mode (default, no --privileged needed)
agentvisor serve ./my-agent --sandbox=gvisor

# Linux only - privileged mode (opt-in, requires --rootless=false)
agentvisor serve ./my-agent --sandbox=gvisor --rootless=false

Custom API Port

agentvisor serve ./my-agent --api-addr :9000

Multiple Policy Files

--policy takes a single comma-separated value; repeating the flag makes the last occurrence win, not merge:

agentvisor serve ./my-agent \
    --policy ./policies/base.yml,./policies/custom.yml

With Environment Variables (.env file)

# Auto-discover .env in agent directory
agentvisor serve ./my-agent --sandbox=none

# Specify explicit .env file path
agentvisor serve ./my-agent \
    --sandbox=none \
    --env-files=/path/to/secrets.env

# Multiple .env files (later files override earlier)
agentvisor serve ./my-agent \
    --sandbox=none \
    --env-files=base.env,secrets.env

Sandboxing stdio MCP Servers

When your agent uses stdio MCP servers and --sandbox is gvisor or docker, AgentVisor sandboxes each stdio server inside its own mcp-tools container (providing node/npx and python/uvx). The sandbox image is resolved at startup.

--bundle-mcp-tools (recommended for offline/CI environments): extracts the mcp-tools rootfs into a temporary directory before the runtime starts, so no image pull is needed at agent invocation time:

agentvisor serve ./my-mcp-agent --bundle-mcp-tools

mcp.prepull in mav-agent-config.yaml: declares packages to pre-install into the rootfs before startup. This is honored automatically — no extra flag is needed:

# mav-agent-config.yaml
mcp:
  prepull:
    - manager: npm
      package: "@modelcontextprotocol/server-filesystem"

See MCP Gateway: Pre-installing Packages (prepull) and the Configuration Reference: Stdio Sandbox Image for details.

HTTP API

When running, the server exposes:

Endpoint	Description
`GET /agents`	List available agents
`POST /threads`	Create thread
`GET /threads/{id}`	Get thread
`DELETE /threads/{id}`	Delete thread
`POST /threads/{id}/runs`	Create run
`GET /threads/{id}/runs`	List runs
`GET /threads/{id}/state`	Get state
`POST /threads/{id}/state`	Update state
`GET /health`	Health check
`GET /swagger-ui/`	Interactive API docs
`GET /openapi.json`	OpenAPI spec

Stopping

Press Ctrl+C to stop the server. The server:

Stops accepting new requests
Completes in-flight runs
Shuts down guest sandbox
Closes Temporal connection

Environment Variables

# Temporal connection
export AGENTVISOR_TEMPORAL_TARGET=localhost:7233
export AGENTVISOR_TEMPORAL_NAMESPACE=default

# API configuration
export AGENTVISOR_API_LISTEN_ADDR=:8090

# Sandbox configuration
export AGENTVISOR_GUEST_MEMORY_LIMIT=536870912
export AGENTVISOR_GUEST_CPU_LIMIT=1.0
export AGENTVISOR_GUEST_ROOTLESS=true  # Enable gVisor rootless mode

# Policy configuration
export AGENTVISOR_AUTHZ_TYPE=embedded
export AGENTVISOR_AUTHZ_EMBEDDED_POLICY_DOMAIN_FILES=./policies/domain.yml

# Logging
export AGENTVISOR_LOG_LEVEL=info
export AGENTVISOR_LOG_FORMAT=plain

Troubleshooting

ModuleNotFoundError: No module named 'agentvisor'

This error occurs when running with --sandbox=none without the SDK installed. See SDK Installation.

Temporal Connection Failed

Start the required services (from the scaffolded project's compose.yml):

docker compose up -d

Policy Denied

Check policy allows required operations. Debug with:

AGENTVISOR_LOG_LEVEL=debug agentvisor serve ./my-agent

For development only, bypass authorization:

AGENTVISOR_AUTHZ_TYPE=allowall agentvisor serve ./my-agent

danger

Never use AGENTVISOR_AUTHZ_TYPE=allowall in production.

Docker Image Not Found

Pull or build the guest image:

# Pull the Python variant (for LangGraph agents)
docker pull ghcr.io/manetu/agentvisor/agentvisor-guest:latest-python

# Or the minimal variant (for exec mode)
docker pull ghcr.io/manetu/agentvisor/agentvisor-guest:latest-minimal

Synopsis​

Description​

Arguments​

Options​

Examples​

Basic Server (Docker Mode - Default)​

Running Without Sandbox Isolation​

Debug Mode (Interactive Debugging)​

gVisor Mode (Strongest Isolation)​

Custom API Port​

Multiple Policy Files​

With Environment Variables (.env file)​

Sandboxing stdio MCP Servers​

HTTP API​

Stopping​

Environment Variables​

Troubleshooting​

ModuleNotFoundError: No module named 'agentvisor'​

Temporal Connection Failed​

Policy Denied​

Docker Image Not Found​

See Also​