agentvisor run

Run an agent once with the specified input and exit.

Synopsis

agentvisor run <path> [options]

Description

The run command executes an agent once with the provided input, prints the output, and exits. Useful for testing and scripting.

License required

agentvisor run 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
--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)	-
--input	{}	JSON input to pass to the agent	-
--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	-
--principal-file	-	Path to principal.json with identity claims	-
--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 Run (Docker Mode - Default)

agentvisor run ./my-agent \
    --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

With Messages

agentvisor run ./my-agent \
    --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

Running Without Sandbox Isolation

agentvisor run ./my-agent \
    --sandbox=none \
    --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

Debug Mode (Interactive Debugging)

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

# Debug with default provider (debugpy) and port (5678)
agentvisor run ./my-agent \
    --sandbox=none \
    --debug \
    --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

# Debug with custom port
agentvisor run ./my-agent \
    --sandbox=none \
    --debug \
    --debug-port=5679 \
    --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

# Use PyCharm native debugger (pydevd)
agentvisor run ./my-agent \
    --sandbox=none \
    --debug \
    --debug-provider=pydevd \
    --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

# Custom port with pydevd
agentvisor run ./my-agent \
    --sandbox=none \
    --debug \
    --debug-provider=pydevd \
    --debug-port=5679 \
    --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

The agent waits for debugger attachment before executing. See Local Development Setup for VS Code and PyCharm debugging configuration.

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 run ./my-agent \
    --sandbox=gvisor \
    --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

# Linux only - privileged mode (opt-in, requires --rootless=false)
agentvisor run ./my-agent \
    --sandbox=gvisor \
    --rootless=false \
    --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

With Environment Variables (.env file)

# Auto-discover .env in agent directory
agentvisor run ./my-agent \
    --sandbox=none \
    --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

# Specify explicit .env file path
agentvisor run ./my-agent \
    --sandbox=none \
    --env-files=/path/to/secrets.env \
    --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

# Multiple .env files (later files override earlier)
agentvisor run ./my-agent \
    --sandbox=none \
    --env-files=base.env,secrets.env \
    --input '{"messages": [{"role": "user", "content": "Hello!"}]}'

The .env file uses standard format:

# my-agent/.env
OPENAI_API_KEY=sk-...
DATABASE_URL=postgres://user:pass@host:5432/db
LOG_LEVEL=debug

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. Use --bundle-mcp-tools to pre-extract the rootfs before the run (avoids an image pull at invocation time), and mcp.prepull in mav-agent-config.yaml to pre-install packages. See the agentvisor serve docs for the full explanation — the behavior is identical.

Output

The command prints human-readable progress lines to stdout as it starts the runtime and executes the agent, ending with the run status and the agent's output (pretty-printed JSON, not a single structured document):

Waiting for host runtime...
Host runtime ready
Executing agent...

Run completed successfully
Status: completed
Output: {
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    },
    {
      "role": "assistant",
      "content": "Hello! How can I help you?"
    }
  ]
}

If the agent run does not complete (status error, interrupted, or cancelled), the command prints Run finished with status: <status> instead and exits non-zero.

Exit Codes

Code	Description
0	Command completed successfully, including the agent run reaching completed status
1	Any failure: CLI/configuration error, startup failure, or the agent run not reaching completed status

Environment Variables

All options can be set via environment variables:

export AGENTVISOR_TEMPORAL_TARGET=localhost:7233
agentvisor run ./my-agent --sandbox=none --input '{...}'

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 run ./my-agent --input '{...}'

For development only, bypass authorization:

AGENTVISOR_AUTHZ_TYPE=allowall agentvisor run ./my-agent --input '{...}'

danger

Never use AGENTVISOR_AUTHZ_TYPE=allowall in production.

See Also

• agentvisor serve - Long-running server mode
• Configuration Reference - All configuration options