Architecture

AgentVisor™ uses a host-guest architecture that provides strong security boundaries while maintaining compatibility with standard HTTP libraries.

Overview

Components

Guest Sandbox

The guest sandbox is an isolated environment where agent code runs.

Security Properties:

• No direct network access outside the hostlink channel (--network=none on gVisor/Docker-Linux; nftables-restricted egress to the hostlink address on Docker macOS/Windows — see Sandbox Modes)
• All syscalls intercepted by gVisor (in gVisor mode) or filtered via seccomp (Docker mode)
• Filesystem isolation
• Resource limits (memory, CPU, processes)
• Credentials never enter the sandbox (symbolic token substitution via credential brokering)
• Per-agent UID isolation prevents cross-tenant access (gVisor and Docker modes)

Contents:

• Agent code and its runtime dependencies
• Guest runtime (Go binary)
• Mounted Unix socket for host communication

Guest Runtime

A small process inside the sandbox that:

1. Runs an HTTP proxy and forces HTTP_PROXY / HTTPS_PROXY into the agent's environment so all agent HTTP traffic is intercepted
2. Forwards intercepted requests to the host runtime over the hostlink session (UDS or TCP+mTLS, depending on sandbox mode)
3. Hosts a per-agent control socket the SDK consumes (the SDK exposes Python APIs like agentvisor.store, agentvisor.checkpoint, agentvisor.langgraph.AgentVisorCheckpointer; agent code never deals with the channel directly)
4. Stamps every agent-originated request with authoritative identity (thread_id, principal, run_id) before forwarding to the host — agents cannot spoof identity through this path

Host Runtime

The trusted component running outside the sandbox:

1. Control plane: receives the guest's policy/checkpoint/store/etc. requests over the hostlink session, and drives the guest's lifecycle in the reverse direction
2. HTTP Proxy: makes authorized external requests on the agent's behalf
3. PolicyEngine: evaluates access policies
4. Temporal Worker: manages durable workflows
5. Lifecycle Manager: starts/stops guest sandboxes
6. Credential Resolver: substitutes symbolic tokens with real credentials at the outbound boundary
7. API Transports: multi-protocol access for external clients (REST, MCP, A2A)
8. MCP and A2A Gateways: outbound connections to external MCP servers and A2A agents on behalf of agents
9. Trace Collector Client: optional outbound stream of gVisor seccheck syscall events (enriched with thread/principal/agent context) to an external security-monitoring collector

Communication Protocol

Internal communication moves over a private control channel that connects three components. Users do not interact with this channel directly — language SDKs (Python's agentvisor.* packages and equivalents) abstract it.

Agent process ↔ Guest runtime. A per-agent socket inside the sandbox. The SDK consumes this for everything an agent needs to coordinate with AgentVisor — saving/loading checkpoints, key-value store access, per-thread state, MCP/A2A gateway calls, log forwarding, telemetry. Agent code never opens the socket directly; it calls SDK functions.

Guest runtime ↔ Host runtime. Every action that crosses the sandbox boundary is forwarded over the hostlink session — HTTP proxy traffic (including streaming and WebSocket upgrades), checkpoint/state operations, store/MCP/A2A calls, log and span forwarding, and policy pre-checks for raw network connect attempts. The guest runtime always re-stamps the request with authoritative identity (thread, principal, run) before forwarding; agents cannot spoof identity over this path.

Host runtime ↔ Guest runtime. The same hostlink session is used in the reverse direction for invoking agents, cancelling runs, snapshotting and restoring durable state, signal delivery, environment configuration, lifecycle (shutdown / health check), and bridging interactive terminal sessions for agentvisor exec.

A separate outbound trace stream is also available for security monitoring: when configured, the host runtime acts as a client to an external trace-collector service, forwarding gVisor seccheck syscall events enriched with thread/principal/agent context. The collector itself is implemented by an external system (e.g., a SIEM or security-monitoring platform), not by AgentVisor.

Hostlink Session

Host and guest communicate via a single multiplexed connection — the hostlink session — that carries both directions of host↔guest traffic. The wire-level transport depends on the sandbox mode and host OS:

Mode	Host OS	Transport	Security
none, gvisor	any	Unix domain socket (UDS)	OS-level isolation — no TLS needed
docker	Linux	Unix domain socket (UDS)	OS-level isolation — no TLS needed
docker	macOS / Windows	TCP + mTLS via host.docker.internal	Ephemeral CA generates short-lived client/server certs

This single connection is bind-mounted (UDS) or addressed via host.docker.internal (TCP), providing the only communication path between guest and host. The agent process never reaches the hostlink directly — its requests pass through the guest runtime, which stamps identity on every forwarded message.

Exec Mode

agentvisor exec is an alternative execution model that bypasses Temporal workflows and the HTTP API entirely. Instead of invoking an agent in response to an HTTP run request, the host bridges its own stdin/stdout into the sandbox so the user has an interactive terminal session inside it. All policy enforcement (HTTP proxy, MCP, A2A, store) remains active — only the orchestration layer is removed. This makes exec suitable for interactive tools like Claude Code, shells, or Cursor that expect a persistent TTY rather than a request/response API.

Trust Boundaries

The key insight: agent code cannot escape the sandbox. It has no route out except the hostlink session (UDS or TCP+mTLS, depending on sandbox mode), where every request is policy-checked.

API Transport Architecture

AgentVisor supports multiple API transports through a pluggable provider system. All transports share a single HTTP server, TLS configuration, and authentication middleware.

Supported Transports

Transport	Endpoint(s)	Protocol	Description
OpenAPI/REST	/*	HTTP/REST	LangGraph Agent Protocol v0.2.0
MCP	POST /mcp, GET /mcp	JSON-RPC 2.0 over HTTP, with SSE notifications	Model Context Protocol for tool access
A2A	POST /a2a, GET /.well-known/agent-card.json	JSON-RPC 2.0	Google Agent-to-Agent Protocol (with standard agent-card discovery path)

Single Server Design

All transports are served from a single HTTP server on the configured listen address (default :8090). This provides:

• Simplified deployment: Single port to expose
• Consistent TLS termination: One certificate configuration
• Shared authentication: Common middleware for all protocols
• Transport isolation: Each protocol registers its own routes

Transport Provider Pattern

Transports use a pluggable provider model — each transport (OpenAPI, MCP, A2A) registers its own routes on the shared HTTP mux and can be independently enabled or disabled via configuration:

api:
  listen_addr: ":8090"
  openapi:
    enabled: true   # OpenAPI/REST (default: enabled)
  mcp:
    enabled: false  # MCP transport (default: disabled)
  a2a:
    enabled: false  # A2A transport (default: disabled)

Authorization

All transports share authentication middleware, but each transport authorizes individual operations against per-resource MRNs rather than a single transport-wide pattern. The most relevant patterns:

Transport	Resource	MRN
OpenAPI/REST	Thread	mrn:agentvisor:thread:<thread_id>
OpenAPI/REST	Run	mrn:agentvisor:run:<thread_id>/<run_id>
OpenAPI/REST	Thread state	mrn:agentvisor:state:<thread_id>
OpenAPI/REST	Agent	mrn:agentvisor:agent:<agent_name>
OpenAPI/REST	Store item	mrn:agentvisor:store:<namespace>/<key>
MCP	MCP server (listing)	mrn:agentvisor:mcp:<server_name>
MCP	MCP tool	mrn:agentvisor:mcp:<server_name>/<tool_name>
MCP	MCP resource	mrn:agentvisor:mcp:<server_name>/resource/<uri>
A2A	A2A agent	mrn:agentvisor:a2a:<agent_name>
A2A	A2A task	mrn:agentvisor:a2a:<agent_name>/task/<task_id>

See Policy Enforcement for how these MRNs are used in policy decisions.

Security Considerations

Threat Mitigations

Threat	Mitigation
Malicious agent code	gVisor syscall isolation
Network bypass	No direct network access outside the hostlink channel
Policy bypass	All requests through host proxy
Data exfiltration	Policy controls on endpoints
Credential theft	Symbolic tokens, host-side substitution, TLS termination (credential brokering)
Privilege escalation	gVisor + non-root container
Cross-tenant access	Per-agent UIDs with umask 0077 (gVisor and Docker modes)
Resource exhaustion	cgroups resource limits

Defense in Depth

1. Sandbox isolation: Container boundary prevents direct host access; gVisor mode adds syscall-level interception
2. No network: Only Unix socket (or hostlink) communication
3. Policy enforcement: Every request evaluated
4. Audit logging: All actions recorded
5. Resource limits: Memory/CPU/process limits
6. Credential brokering: Real credentials never leave the host
7. Per-agent UIDs: Each agent runs as unique UID