🔒 AgentBox

Self-hosted AI agent runtime in a secure VM with encrypted secrets

AgentBox is a security-first AI agent framework designed for isolated VM deployment on macOS and Linux. Run AI agents with complete host isolation, encrypted secrets storage, and enterprise-grade security controls.

Note: AgentBox was inspired by and built upon the foundation of OpenClaw, an open-source personal AI agent framework. We are grateful to the OpenClaw community for pioneering accessible self-hosted AI agents. AgentBox extends these concepts with enhanced security, encrypted secrets management, and VM isolation for enterprise and privacy-focused deployments.

🎯 Why AgentBox?

Feature	AgentBox	Standard AI Tools	Cloud AI Services
VM Isolation	✅ Built-in	⚠️ Manual	❌ N/A
Encrypted Secrets	✅ age encryption	⚠️ Plain .env	⚠️ Provider KMS
Zero Host Access	✅ Default	❌ Full access	❌ Cloud access
Audit Logging	✅ Immutable logs	⚠️ Limited	⚠️ Limited
Network Isolation	✅ Firewall rules	⚠️ Manual	❌ Internet required
Snapshot/Rollback	✅ VM snapshots	❌ N/A	❌ N/A
Air-gap Capable	✅ Optional	❌ Internet required	❌ Cloud only
Self-Hosted	✅ Complete control	⚠️ Varies	❌ SaaS only
Telemetry Dashboard	✅ Real-time observability	❌ N/A	⚠️ Limited

📊 Telemetry & Observability

AgentBox includes a built-in real-time observability dashboard for monitoring your AI agent's performance, costs, and usage:

✅ Real-time cost tracking - Monitor API spending across all sessions and models
✅ Token usage analytics - Track input/output tokens with cache optimization insights
✅ Tool usage patterns - Identify bottlenecks and frequently used tools
✅ Timeline visualization - See agent activity over time (hourly, daily, monthly)
✅ Session-level breakdowns - Debug expensive runs and optimize workflows

Quick Start Telemetry

# Start AgentBox with telemetry dashboard
docker-compose up -d

# Access telemetry dashboard
open http://localhost:8501

The dashboard automatically discovers and monitors OpenClaw session logs. Perfect for:

• Cost optimization - Track spending and identify expensive operations
• Performance tuning - Analyze token usage and cache hit rates
• Debugging - Review session history and tool call patterns
• Capacity planning - Understand usage trends and forecast needs

See telemetry/README.md for detailed setup and configuration.

🚀 Quick Start

Prerequisites

• Docker: Docker Desktop or Docker Engine
• macOS: UTM or VirtualBox (for full VM)
• Linux: QEMU/KVM or VirtualBox (for full VM)

Option 1: Docker (Recommended)

Build the Image

# Clone the repo
git clone https://github.com/travis-burmaster/agentbox.git
cd agentbox

# Build the Docker image (takes 3-5 minutes)
# OpenClaw is installed from npm — no local source build required
docker build -t agentbox:latest .

Start the Container

# Start with Docker Compose (recommended)
docker-compose up -d

# Or with docker run
docker run -d --name agentbox \
  -v agentbox-config:/agentbox/.openclaw \
  -v agentbox-data:/agentbox/data \
  -v agentbox-logs:/agentbox/logs \
  -p 127.0.0.1:3000:3000 \
  agentbox:latest

Run Interactive Onboarding

To configure OpenClaw with API keys, models, and channels:

# Method 1: Using helper script (easiest)
./onboard.sh

# Method 2: Manual (connect to shell first, then run onboarding)
docker exec -it agentbox /bin/bash
# Inside container:
openclaw onboard --install-daemon
# Use arrow keys to navigate, Enter to confirm
# Press Ctrl+D or type 'exit' when done

Note: The --install-daemon flag is optional. It attempts to install systemd service (not available in Docker, but onboarding will complete successfully anyway).

Verify the Build

# Check OpenClaw version
docker exec agentbox openclaw --version
# Output: 2026.2.15

# View available commands
docker exec agentbox openclaw --help

# Run diagnostics
docker exec agentbox openclaw doctor

# Check gateway status
docker exec agentbox openclaw status

Using OpenClaw CLI Commands

Once the container is running, you can execute OpenClaw commands:

# Check system status
docker exec agentbox openclaw status

# List available models
docker exec agentbox openclaw models list

# View skills
docker exec agentbox openclaw skills list

# Check security settings
docker exec agentbox openclaw security audit

# Run diagnostics
docker exec agentbox openclaw doctor

Interactive Shell Access

For interactive commands (onboarding, configuration, etc.), connect to the container's bash shell:

# Connect to container shell
docker exec -it agentbox /bin/bash

# Inside container, you can run interactive commands:
openclaw onboard --install-daemon    # Full onboarding wizard
openclaw configure                   # Configuration wizard
openclaw tui                         # Text-based UI for monitoring and control

# Exit shell when done
exit

Tip: Use the ./onboard.sh helper script for easier onboarding!

Text-Based UI (TUI)

OpenClaw includes a terminal-based user interface for real-time monitoring and control:

# Connect to container and launch TUI
docker exec -it agentbox /bin/bash
openclaw tui

# Or in one command:
docker exec -it agentbox openclaw tui

TUI Features:

• 📊 Real-time session monitoring
• 💬 Live message streams
• 🔧 Interactive agent control
• 📈 System metrics and status
• ⌨️ Keyboard shortcuts for navigation

Controls:

• q or Ctrl+C - Exit TUI
• Arrow keys - Navigate
• Tab - Switch panels
• Enter - Select/activate

Note: The TUI requires a terminal with proper TTY support. If you get display issues, ensure you're using docker exec -it (with -it flags).

Option 2: Vagrant (Full VM - Coming Soon)

# Clone and start VM
git clone https://github.com/travis-burmaster/agentbox.git
cd agentbox
vagrant up

# SSH into the VM
vagrant ssh

# Inside VM: Initialize OpenClaw
openclaw init

Option 3: Manual VM Setup

See VM_SETUP.md for UTM, QEMU/KVM, and VirtualBox instructions.

---

📊 Current Status

✅ What Works

• Docker Build: Full OpenClaw compilation and installation
• CLI Commands: All openclaw CLI commands function correctly
• Diagnostics: openclaw doctor, openclaw status, openclaw --help
• Model Management: List and configure AI models
• Skills: View and manage agent skills
• Security Tools: Security auditing and configuration

🚧 In Progress

• Gateway Service: Requires configuration for daemon mode

  • CLI commands work fully ✅
  • Gateway daemon requires systemd (working on Docker-compatible solution)
  • Workaround: Use openclaw configure to set up, then run specific commands

• Encrypted Secrets: Template ready, needs integration testing

• Network Isolation: Firewall rules defined, needs runtime configuration

• Vagrant VM: Configuration files in progress

🎯 Quick Start Workflow

After building and starting the container:

1. Connect to Container Shell:

   docker exec -it agentbox /bin/bash

2. Run Onboarding (inside container):

   openclaw onboard --install-daemon

   • Use arrow keys to navigate prompts
   • Enter your Anthropic API key when prompted
   • Configure models, tools, and channels
   • Press Ctrl+D or type exit when complete

3. Test AI Chat (after exiting container):

   docker exec agentbox openclaw agent chat "Hello! Introduce yourself."

4. Check Status:

   docker exec agentbox openclaw status

Alternative: Use the helper script for automated onboarding:

./onboard.sh

---

🔐 Encrypted Secrets Management

AgentBox uses age encryption to protect all secrets at rest.

First-Time Setup

# Generate encryption key (do this ONCE, backup safely!)
age-keygen -o secrets/agent.key

# Your public key (safe to commit):
age1abc123...xyz789

# Add secrets
cat > secrets/secrets.env <<EOF
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
TELEGRAM_BOT_TOKEN=123456:ABC...
EOF

# Encrypt secrets
age -r age1abc123...xyz789 -o secrets/secrets.env.age secrets/secrets.env
rm secrets/secrets.env  # Delete plaintext!

Using Encrypted Secrets

# Decrypt on-the-fly (never writes plaintext to disk)
age -d -i secrets/agent.key secrets/secrets.env.age | source /dev/stdin

# Or use the helper script
./scripts/load-secrets.sh

Secrets File Structure

secrets/
├── agent.key              # Private key (NEVER commit! Add to .gitignore)
├── agent.key.pub          # Public key (safe to commit)
├── secrets.env.age        # Encrypted secrets (safe to commit)
└── README.md             # Instructions

✅ Safe to commit: *.age, *.pub
❌ NEVER commit: agent.key, *.env (plaintext)

🛡️ Security Features

1. VM Isolation

• Agent runs in completely isolated VM
• No direct host filesystem access
• Restricted network egress (allowlist-only)
• Dedicated virtual network interface

2. Encrypted Secrets

• All secrets encrypted with age (ChaCha20-Poly1305)
• Private keys stored in VM only
• Secrets decrypted in-memory (never written to disk)
• Automatic key rotation scripts included

3. Network Security

• Default-deny firewall (UFW/iptables)
• Allowlist for API endpoints (Anthropic, OpenAI, etc.)
• Optional Tor/VPN routing
• DNS-over-HTTPS (DoH) enabled

4. Audit Logging

• All agent actions logged to immutable append-only log
• Logs exported to host via read-only mount
• Syslog integration for centralized monitoring
• Tamper-evident log signatures

5. Hardening

• SELinux/AppArmor profiles included
• Automatic security updates (unattended-upgrades)
• Minimal attack surface (no GUI, minimal packages)
• Secure boot support

📦 What's Included

agentbox/
├── Dockerfile              # ✅ Docker container config
├── docker-entrypoint.sh    # ✅ Container startup script with secrets loading
├── docker-compose.yml      # ✅ Compose config (agentbox + telemetry)
├── supervisord.conf        # ✅ Process supervisor (runs gateway in container)
├── config/
│   └── openclaw.json      # ✅ Default OpenClaw config
├── scripts/
│   ├── load-secrets.sh    # Helper: decrypt and load age-encrypted secrets
│   └── rotate-keys.sh     # Helper: rotate age encryption keys
├── secrets/
│   └── (template)         # Encrypted secrets management templates
├── telemetry/             # ✅ Streamlit observability dashboard
├── security/
│   └── (coming soon)      # Firewall rules, SELinux, AppArmor profiles
├── vm-configs/            # (coming soon)
│   ├── utm/              # macOS UTM configs
│   ├── qemu/             # Linux QEMU/KVM configs
│   └── virtualbox/       # Cross-platform VirtualBox
└── docs/
    ├── SECURITY.md        # Security architecture documentation
    └── (expanding)        # More guides coming

What Actually Runs

The Docker image includes:

• Ubuntu 22.04 base system
• Node.js 22.x runtime
• OpenClaw 2026.2.15 fully compiled and installed
• System tools: curl, wget, git, build-essential
• Security tools: age encryption, ufw firewall, fail2ban, auditd
• Python 3 with pip for extensions

Image Size

• Compressed: ~800 MB
• Uncompressed: ~2.5 GB
• Build time: 3-5 minutes (with caching)

🔧 Configuration

Agent Configuration

# agentbox.yaml
agent:
  name: "AgentBox"
  model: "anthropic/claude-sonnet-4-5"
  
secrets:
  encryption: "age"
  key_path: "/agentbox/secrets/agent.key"
  secrets_path: "/agentbox/secrets/secrets.env.age"

network:
  mode: "restricted"  # restricted | allowlist | open
  allowed_domains:
    - "api.anthropic.com"
    - "api.openai.com"
    - "api.telegram.org"
  
security:
  firewall: true
  selinux: true
  audit_logging: true
  auto_updates: true

vm:
  memory: "4GB"
  cpus: 2
  disk: "20GB"
  snapshot_on_shutdown: true

🎓 Use Cases

1. Personal AI Assistant (Privacy-Focused)

• All data stays on your hardware
• Encrypted secrets for API keys
• No telemetry or cloud dependencies

2. Development/Testing

• Isolated environment for agent experiments
• Snapshot before risky operations
• Rollback on failure

3. Enterprise Deployment

• Compliance-friendly (HIPAA, PCI, SOC 2)
• Air-gap capable for sensitive environments
• Audit logs for security reviews

4. Research

• Controlled environment for AI safety research
• Reproducible experiments (VM snapshots)
• Network isolation for adversarial testing

📋 Roadmap

v0.1.0 - Foundation (Current)

• Docker Build System

  • OpenClaw compilation from source
  • Node.js 22.x integration
  • Multi-stage build optimization
  • Working CLI commands

• Core Components

  • OpenClaw 2026.2.15 fully functional
  • age encryption tools installed
  • Security tools (ufw, fail2ban, auditd)
  • Python 3 runtime

• Secrets Management (Template Ready)

  • age encryption support
  • Automated secrets loading in entrypoint
  • Key rotation scripts
  • Backup automation

• Gateway Service

  • CLI commands working
  • Docker-compatible daemon mode (no systemd dependency)
  • Configuration wizard
  • Persistent storage configuration

v0.2.0 - VM Deployment

• Vagrant Integration

  • Vagrantfile for automated VM provisioning
  • Multi-provider support (VirtualBox, VMware, Parallels)
  • Shared folder configuration

• Manual VM Configs

  • UTM (macOS) configuration files
  • QEMU/KVM (Linux) setup scripts
  • VirtualBox OVA exports

• Network Isolation

  • UFW firewall rules
  • API endpoint allowlists
  • DNS-over-HTTPS configuration
  • Optional Tor/VPN routing

v0.3.0 - Enhanced Security

• Mandatory Access Control

  • SELinux policies
  • AppArmor profiles
  • Seccomp filters

• Audit & Monitoring

  • Immutable append-only logging
  • Syslog integration
  • Tamper-evident log signatures
  • Security event alerting

• Advanced Secrets

  • Hardware security module (HSM) support
  • PKCS#11 integration
  • Automatic key rotation
  • Multi-key encryption (threshold)

v0.4.0 - Compliance & Enterprise

• Compliance Frameworks

  • FIPS 140-2 mode
  • STIG hardening
  • Compliance reporting (HIPAA, PCI, SOC 2)
  • CIS Benchmark alignment

• Enterprise Features

  • Multi-tenancy support
  • Centralized logging (SIEM integration)
  • Role-based access control (RBAC)
  • Zero-knowledge backup

Future Considerations

• Kubernetes deployment (Helm charts)
• ARM64 support (Apple Silicon, Raspberry Pi)
• WebAssembly sandbox for untrusted code
• Hardware root of trust (TPM, Secure Enclave)

🤝 Contributing

Security contributions are welcome! Please see CONTRIBUTING.md.

Security vulnerabilities: Report privately via GitHub Security Advisories.

📜 License

AgentBox is released under the MIT License.

🙏 Acknowledgments

AgentBox was inspired by and builds upon OpenClaw, an open-source framework for self-hosted AI agents. We extend our gratitude to the OpenClaw team and community for their pioneering work in making AI agents accessible and self-hostable.

Other Credits:

• age - Modern encryption tool by Filippo Valsorda
• Vagrant - HashiCorp's VM automation tool
• Docker - Container platform

🔍 Troubleshooting

Docker Build Issues

Problem: Build fails with module resolution errors

Solution: Try a clean build (clears cached layers):

docker build --no-cache -t agentbox:latest .

OpenClaw is installed directly from npm during the build — no local source compilation required. If you see npm network errors, check your internet connection and try again.

Problem: Build takes too long or runs out of memory

Solution: Increase Docker resources:

• Docker Desktop: Settings → Resources → Memory (increase to 8GB+)
• Linux: Check docker info for available resources

Runtime Issues

Problem: openclaw command not found in container

Solution: The container uses the binary name openclaw (not agentbox):

# Correct:
docker run --rm agentbox:latest openclaw --version

# Incorrect:
docker run --rm agentbox:latest agentbox --version

Problem: Gateway fails to start with systemd error

Solution: This is expected. Gateway daemon mode requires configuration. Use CLI commands directly:

# Instead of running the gateway daemon:
docker run --rm agentbox:latest openclaw status
docker run --rm agentbox:latest openclaw models list
docker run --rm agentbox:latest openclaw skills list

Problem: Container exits immediately

Solution: The default CMD tries to start the gateway service. Override it:

# Run a specific command:
docker run --rm agentbox:latest openclaw doctor

# Open a shell:
docker run -it --rm agentbox:latest /bin/bash

Common Commands Reference

# Version check
docker run --rm agentbox:latest openclaw --version

# System diagnostics
docker run --rm agentbox:latest openclaw doctor

# Configuration wizard (interactive)
docker run -it agentbox:latest openclaw configure

# List available models
docker run --rm agentbox:latest openclaw models list

# List installed skills
docker run --rm agentbox:latest openclaw skills list

# Security audit
docker run --rm agentbox:latest openclaw security audit

# Help for any command
docker run --rm agentbox:latest openclaw <command> --help

---

📞 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• OpenClaw Docs: https://docs.openclaw.ai

---

⚠️ Important Notices

Alpha Software: AgentBox is in early development. The Docker CLI interface is fully functional, but gateway daemon mode requires additional configuration. Use in production at your own risk. Always test in a safe environment first.

Security Notice: Encryption is only as strong as your key management. Keep your agent.key safe, backed up, and never commit it to version control.

OpenClaw Integration: This project uses OpenClaw as its core framework. The command-line tool is openclaw, not agentbox. AgentBox adds security, VM isolation, and encrypted secrets management on top of OpenClaw's foundation.