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 for activation instructions and where to obtain a key.

Arguments

Argument	Description
`[path]`	Path to agent directory. Optional if `--image` is given (a pre-built guest OCI image reference used instead of a source 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 the full HTTP API on the configured --api-addr (default :8090) — threads, runs, state, agents, store, tracing, and system endpoints (health, readiness, metrics, OpenAPI spec, Swagger UI). See the HTTP API Reference for the complete, authoritative endpoint list.

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

All options can be set via environment variables (see the Env Var column in Options above):

export AGENTVISOR_TEMPORAL_TARGET=localhost:7233
agentvisor serve ./my-agent --sandbox=none

See the Configuration Reference for the full list of configuration keys, environment variables, and defaults — including Temporal, API, sandbox, policy, and logging settings not exposed as CLI flags.

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

See Troubleshooting Guide: Temporal Connectivity for namespace and Temporal Cloud auth issues.

Policy Denied

See Troubleshooting Guide: Policy Evaluation Errors for debugging steps and the development-only allowall bypass (never use 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​