Production Deployment

This guide provides a production readiness checklist for deploying AgentVisor™. Use it to ensure you've addressed all critical areas before going live.

Production Readiness Checklist

Before deploying to production, verify each area:

Area	Status	Guide
Security hardening	☐	Security Checklist
Temporal configured	☐	Temporal Guide
Scaling configured	☐	Scaling and Resilience
Authentication enabled	☐	OIDC Setup
Policies defined	☐	Policy Configuration
Monitoring set up	☐	Monitoring
Backup plan in place	☐	Backup and Recovery

Security Checklist

Before deploying to production:

• Configure sandbox mode (gVisor recommended for Linux; Docker is production-grade on any platform)
• Configure restrictive policies (deny-by-default)
• Enable OIDC authentication
• Set up TLS for the API
• Configure resource limits
• Enable audit logging
• Block cloud metadata endpoints
• Review network policies

Sandbox Configuration

Both Docker and gVisor sandbox modes are production-grade. gVisor is recommended for Linux production deployments because it adds syscall-level interception via a userspace kernel. Docker provides equivalent container-level isolation and works across Linux, macOS, and Windows.

gVisor (Recommended for Linux)

Images built with agentvisor build use gVisor by default—no extra configuration needed:

# docker-compose.yml
services:
  agentvisor:
    image: my-agent:v1
    security_opt:
      - seccomp=unconfined  # Required for rootless gVisor (default mode)
      - apparmor=unconfined  # Required on Ubuntu 24.04+, GKE, AKS

Docker (Cross-Platform)

To use Docker sandbox mode explicitly (e.g. on non-Linux hosts or when gVisor is unavailable):

services:
  agentvisor:
    image: my-agent:v1
    environment:
      - AGENTVISOR_GUEST_SANDBOX=docker

For more on sandbox modes and isolation, see Sandbox Modes.

Resource Limits

Set appropriate limits to prevent runaway processes:

# Memory (512MB)
export AGENTVISOR_GUEST_MEMORY_LIMIT=536870912

# CPU (1 core)
export AGENTVISOR_GUEST_CPU_LIMIT=1.0

# Processes (1024)
export AGENTVISOR_GUEST_PIDS_LIMIT=1024

Timeouts

Configure timeouts for predictable behavior:

# Guest startup timeout
export AGENTVISOR_GUEST_STARTUP_TIMEOUT=30s

# Guest shutdown timeout
export AGENTVISOR_GUEST_SHUTDOWN_TIMEOUT=10s

# HTTP proxy timeout
export AGENTVISOR_PROXY_REQUEST_TIMEOUT=30s

Authentication

Enable OIDC authentication for the API:

export AGENTVISOR_API_AUTH_ENABLED=true
export AGENTVISOR_API_AUTH_OIDC_ISSUER=https://auth.example.com
export AGENTVISOR_API_AUTH_OIDC_AUDIENCE=agentvisor

Enable TLS:

export AGENTVISOR_API_TLS_ENABLED=true
export AGENTVISOR_API_TLS_CERT_FILE=/etc/ssl/certs/server.crt
export AGENTVISOR_API_TLS_KEY_FILE=/etc/ssl/private/server.key

For detailed OIDC setup including provider-specific configurations, see OIDC Setup.

Policy Configuration

Start with deny-all and explicitly allow only what's needed:

spec:
  resources:
    # Only what's needed
    - name: openai-chat
      selector: ["mrn:agentvisor:http:api\\.openai\\.com/v1/chat.*"]
      group: "mrn:iam:resource-group:allowed"

    # Block everything else
    - name: default
      selector: ["mrn:agentvisor:http:.*"]
      group: "mrn:iam:resource-group:denied"

Block Cloud Metadata

Always block cloud provider metadata services to prevent credential theft:

resources:
  - name: aws-metadata
    selector: ["mrn:agentvisor:http:169\\.254\\.169\\.254.*"]
    group: "mrn:iam:resource-group:denied"

  - name: gcp-metadata
    selector: ["mrn:agentvisor:http:metadata\\.google\\.internal.*"]
    group: "mrn:iam:resource-group:denied"

  - name: azure-metadata
    selector: ["mrn:agentvisor:http:169\\.254\\.169\\.254.*"]
    group: "mrn:iam:resource-group:denied"

For comprehensive policy configuration, see Policy Guide.

Temporal Configuration

Configure Temporal for production use. This is critical for durability and reliability.

Key areas to configure:

• Temporal Cloud or self-hosted cluster connection
• Namespace and task queue strategy
• Search attributes setup
• Payload encryption (recommended)
• History management

See Temporal Configuration for complete setup instructions.

Scaling and High Availability

For production deployments, configure:

• Multiple replicas (minimum 3 recommended)
• Availability zone spread
• PodDisruptionBudget
• Auto-scaling (HPA)

See Scaling and Resilience for deployment manifests and configuration.

Guest OCI Container Deployment

AgentVisor supports building guest images as standalone OCI containers, enabling flexible deployment patterns where the guest image is built separately and pulled at runtime.

Building Standalone Guest Images

Build a guest image without bundling it into a combined host+guest image:

# Build and push a standalone guest image
agentvisor build guest ./my-agent -t myregistry.io/myagent:v1 --push

# Multi-arch build
agentvisor build guest ./my-agent -t myregistry.io/myagent:v1 --platform amd64,arm64 --push

OCI Labels

Guest images include metadata labels for runtime configuration:

Label	Example	Description
io.agentvisor.type	guest	Identifies as AgentVisor guest image
io.agentvisor.version	v0.1.0	AgentVisor version used to build
io.agentvisor.framework.provider	langgraph	Framework provider name
io.agentvisor.image.variant	python	Image variant
io.agentvisor.exec-mode	true	Whether this is an interactive agent

Docker Compose Deployment

Deploy the host runtime with a pre-built guest image:

# docker-compose.yml
services:
  agentvisor:
    image: ghcr.io/manetu/agentvisor/agentvisor-host:v1.0
    security_opt:
      - seccomp=unconfined  # Required for rootless gVisor (default mode)
      - apparmor=unconfined  # Required on Ubuntu 24.04+, GKE, AKS
    environment:
      AGENTVISOR_GUEST_IMAGE: myregistry.io/myagent:v1
      AGENTVISOR_GUEST_SANDBOX: gvisor
      AGENTVISOR_AUTHZ_TYPE: embedded
      AGENTVISOR_AUTHZ_EMBEDDED_POLICY_DOMAIN_FILES: /etc/agentvisor/policies/domain.yml
    volumes:
      - ./policies:/etc/agentvisor/policies
    ports:
      - "8090:8090"

Kubernetes Deployment

Deploy with imagePullSecrets for private registries:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: agentvisor
spec:
  template:
    spec:
      # For private guest image registries
      imagePullSecrets:
        - name: guest-registry-secret
      containers:
        - name: agentvisor
          image: ghcr.io/manetu/agentvisor/agentvisor-host:v1.0
          securityContext:
            seccompProfile:
              type: Unconfined  # Required for rootless gVisor (default mode)
            appArmorProfile:
              type: Unconfined  # Required on Ubuntu 24.04+, GKE, AKS
          env:
            - name: AGENTVISOR_GUEST_IMAGE
              value: myregistry.io/myagent:v1
            - name: AGENTVISOR_GUEST_SANDBOX
              value: gvisor
            # Registry auth via env vars (alternative to imagePullSecrets)
            - name: AGENTVISOR_GUEST_REGISTRY_AUTH_USERNAME_ENV
              value: REGISTRY_USERNAME
            - name: AGENTVISOR_GUEST_REGISTRY_AUTH_PASSWORD_ENV
              value: REGISTRY_PASSWORD
            - name: REGISTRY_USERNAME
              valueFrom:
                secretKeyRef:
                  name: guest-registry-credentials
                  key: username
            - name: REGISTRY_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: guest-registry-credentials
                  key: password

Registry Authentication

The host runtime supports multiple authentication methods for pulling guest images:

Method 1: Default Docker Keychain No configuration needed. Uses ~/.docker/config.json and credential helpers automatically.

Method 2: Explicit Credentials via Environment Variables

# Set the env var names that contain credentials
export AGENTVISOR_GUEST_REGISTRY_AUTH_USERNAME_ENV=MY_REG_USER
export AGENTVISOR_GUEST_REGISTRY_AUTH_PASSWORD_ENV=MY_REG_PASS

# Set the actual credentials
export MY_REG_USER=myusername
export MY_REG_PASS=mytoken

Method 3: Custom Docker Config Path

export AGENTVISOR_GUEST_REGISTRY_AUTH_DOCKER_CONFIG=/path/to/.docker/config.json

Using Guest Images with CLI Commands

The serve, run, and exec commands accept OCI image references directly:

# Auto-detected as OCI image (contains registry prefix)
agentvisor serve myregistry.io/myagent:v1

# Explicit --image flag
agentvisor serve --image myregistry.io/myagent:v1

# Works with run and exec too
agentvisor run --image myregistry.io/myagent:v1
agentvisor exec --image myregistry.io/myagent:v1

Build with Pre-Built Guest Image

Build a combined host+guest image using a pre-built guest:

# Use --from-guest-image to skip guest build
agentvisor build --from-guest-image myregistry.io/myagent:v1 -t myapp:v1

Kubernetes Deployment

Network Policies

Restrict network access to only what's needed:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: agentvisor-egress
spec:
  podSelector:
    matchLabels:
      app: agentvisor
  policyTypes:
  - Egress
  egress:
  # Temporal
  - to:
    - namespaceSelector:
        matchLabels:
          name: temporal
    ports:
    - port: 7233
  # LLM APIs (via allowed IPs)
  - to:
    - ipBlock:
        cidr: 0.0.0.0/0
        except:
        - 10.0.0.0/8
        - 172.16.0.0/12
        - 192.168.0.0/16
        - 169.254.0.0/16
    ports:
    - port: 443

Secrets Management

Store sensitive values in Kubernetes Secrets:

apiVersion: v1
kind: Secret
metadata:
  name: agentvisor-secrets
type: Opaque
stringData:
  api-key: "your-api-key"
  oidc-client-secret: "your-secret"
---
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: agent
    envFrom:
    - secretRef:
        name: agentvisor-secrets

For complete deployment manifests including replicas, HPA, and PDB, see Scaling and Resilience.

Monitoring

Health Checks

Configure liveness and readiness probes:

containers:
- name: agent
  livenessProbe:
    httpGet:
      path: /health
      port: 8090
    initialDelaySeconds: 30
    periodSeconds: 10
  readinessProbe:
    httpGet:
      path: /health
      port: 8090
    initialDelaySeconds: 5
    periodSeconds: 5

Metrics

Enable Prometheus metrics. The /metrics endpoint is served on the same shared HTTP API listener as /health and /ready (AGENTVISOR_API_LISTEN_ADDR, default :8090) — there is no separate metrics bind address:

export AGENTVISOR_TELEMETRY_METRICS_ENABLED=true

Scrape configuration:

scrape_configs:
- job_name: agentvisor
  static_configs:
  - targets: ['agentvisor:8090']

Logging

Configure structured logging for production:

export AGENTVISOR_LOG_FORMAT=json
export AGENTVISOR_LOG_LEVEL=info

For metrics to monitor and alerting recommendations, see Scaling and Resilience: Monitoring for Scale.

Backup and Recovery

Temporal State

Temporal stores all workflow state. Back up:

• Temporal database (PostgreSQL/MySQL/Cassandra)
• Elasticsearch (for visibility features)

For Temporal Cloud, backups are managed automatically.

Configuration

Version control all configuration:

• Policy domain files
• Kubernetes manifests
• Environment variable templates (without secrets)

Encryption Keys

If using payload encryption:

• Store codec passwords in a secrets manager
• Document key rotation procedures
• Warning: Lost encryption keys = lost data

See Temporal Configuration: Payload Encryption for encryption setup.

Incident Response

Disable a Problematic Agent

Cancel all threads for a specific agent:

# Cancel all threads for an agent
for thread in $(curl -s http://localhost:8090/threads/search \
  -d '{"metadata": {"agent": "problematic-agent"}}' | jq -r '.[].thread_id'); do
  curl -X DELETE "http://localhost:8090/threads/$thread"
done

Emergency Policy Update

Apply a restrictive policy immediately:

# Apply restrictive policy
kubectl create configmap emergency-policy --from-file=domain.yml=emergency.yml
kubectl rollout restart deployment/agentvisor

Audit Investigation

Query audit logs for policy decisions:

# Search recent logs for policy decisions
kubectl logs -l app=agentvisor --since=1h | grep "policy_decision"

Next Steps

Once your production deployment is configured:

1. Run a load test to validate scaling configuration
2. Set up alerts for key metrics (see Scaling and Resilience)
3. Document runbooks for common incident scenarios
4. Schedule regular policy reviews to audit access controls

See Also

• Temporal Configuration — Complete Temporal setup
• Scaling and Resilience — HA and auto-scaling
• OIDC Setup — Authentication setup
• Policy Guide — Authorization policies
• Kubernetes Deployment — Deployment reference