Proxmox LXC AI Agent Sandbox
A turnkey, isolated execution environment and developer client for running autonomous AI coding agents inside Proxmox LXC containers on a dedicated Raspberry Pi server.
Project Brief
- Role
- Solo systems engineer and tool builder
- Scope
- A complete developer client suite and isolated Proxmox LXC sandboxing environment on a dedicated Raspberry Pi 4 node for running autonomous AI coding agents safely
- Timeline
- Designed and implemented in 2026
- Result
- A secure, turnkey sandboxing platform with instant rollback, live port tunneling, bi-directional sync, and a stylized 6-tab TUI
Evidence Included
Hardware-isolated sandbox boundary
Autonomous coding agents execute inside an unprivileged LXC container on a physical Raspberry Pi 4 Proxmox VE server, preventing untrusted scripts from touching the primary workstation.
Zero credentials stored at rest
Provider API keys are passed directly into ephemeral SSH process memory at command launch and never written to container configuration or persistent disk storage.
Time Machine rollbacks verified
Workspace checkpoints enable instant single-command restoration to clean project states when testing speculative agent changes.
Complete client distribution
Turnkey package featuring a stylized curses TUI with theme switching, Zsh/Bash autocompletions, global desktop hotkey, and multi-container cloning.
6 Visual Tabs
TUI Dashboard
5 Auto-Tunneled
Forwarded Ports
Zero Keys on Disk
Secret Hygiene
Instant Restore
Rollback Speed
Proxmox LXC (ARM64)
Isolation
1-Command Install
Deployment
Interactive System Architecture
Proxmox LXC AI Agent Sandbox Architecture
Developer Client
User machine where source code lives and commands are initiated.
CLI Runner & Sync Engine
sandbox & sandboxer executable
6-Tab Visual TUI
Python Curses control dashboard with 5 themes
In-Memory Secret Harvester
Zero API keys on disk; passes envs over SSH
Desktop Integration
Global hotkey <Super><Alt>S + Ghostty launch
Tunnel & Sync Bus
Bi-directional sync and port forwarding layer over keyed SSH.
Smart rsync Sync
Ignores .git, node_modules, .venv, caches
5 Port Reverse Tunnels
3000, 5173, 8000, 8080, 8888 → localhost
Ed25519 Key Auth
Strict keyless pairing wizard with host checks
Diff & Review Guard
Colorized terminal diffs before pulling
Isolated LXC Container
Unprivileged Linux container housing tools and agent execution.
AI Coding Agent Roster
Pi Coding Agent, OpenCode AI, Docker CE
Herdr Session Multiplexer
Persistent workspace surviving disconnects
Time Machine Snapshots
Pre/post task checkpoints + instant rollback
Multi-Sandbox Cloning
Fast LXC cloning for parallel agent branches
Core Security & Architectural Guarantees
Uncontrolled agent file edits, runaway loops, or destructive scripts run strictly inside the LXC container.
Local environment variables are passed directly into ephemeral SSH process memory without saving keys to disk.
Workspace state is check-pointed before task execution, enabling instant restoration without messing up git history.
A personal infrastructure and developer tooling project built to safely run autonomous AI coding agents (Pi Coding Agent, OpenCode AI, and containerized dev stacks) with strong hardware isolation. Instead of granting autonomous coding agents raw execution privileges on a primary development machine, the sandbox runs them inside an unprivileged LXC container hosted on a dedicated ARM64 Raspberry Pi 4 Proxmox VE node. A custom CLI runner and bi-directional sync engine pairs with a stylized 6-tab terminal dashboard (sandbox-tui), providing instant workspace snapshot rollbacks (Time Machine), ephemeral in-memory secret forwarding over SSH, automatic multi-port tunneling, active web service discovery, and one-command multi-sandbox container cloning.
Highlights
- Hardware-isolated agent sandbox running AI coding agents (Pi Coding Agent, OpenCode AI, Herdr Workspace, Docker CE) inside a dedicated Proxmox LXC container on a Raspberry Pi 4 — protecting workstation filesystems from uncontrolled agent writes or dangerous commands
- Zero credentials at rest — LLM API keys (Anthropic, OpenAI, Gemini, DeepSeek, OpenRouter, Groq, xAI, Mistral) are harvested locally and injected into remote SSH session memory on the fly, leaving container disk storage and config files completely free of static API secrets
- Optimized bi-directional sync engine (rsync over SSH) with smart exclusions (.git, node_modules, .venv, .env.local, binaries, build caches) to quickly mirror working directories to ~/workspace in the container
- Time Machine snapshot and rollback pipeline — automatically captures workspace checkpoints before and after agent tasks, supporting instant one-command rollbacks (sandbox rollback) if an agent produces broken refactors or corrupted dependencies
- Visual pre-pull diff review — inspect remote agent code modifications in the terminal (sandbox diff .) before pulling changes down, with an interactive confirmation tool (sandbox pull -i .) preventing accidental local overwrites
- Automatic multi-port SSH tunneling (ports 3000, 5173, 8000, 8080, 8888) with active TCP port scanning in the container (sandbox ports) and direct browser launching (sandbox open <port>)
- Persistent agent session multiplexing — wraps agent executions in Herdr terminal workspaces so long-running agent tasks survive network disconnects and support multi-pane inspection
- Stylized 6-Tab curses terminal UI (sandbox-tui) featuring Launch Agents, Time Machine snapshots, Sync & Diffs, Live Hardware Telemetry (real-time CPU/RAM/Disk gauges), Power/Lifecycle controls, and Multi-Sandbox container cloning
- Interactive TUI theme customizer supporting 5 switchable color palettes (Cyberpunk, Emerald, Amethyst, Amber, Monokai) with persistent preferences
- Disposable scratchpad provisioning (sandbox scratch <template>) for clean, isolated prototyping across Node.js, Python, Rust, and Web environments
- Desktop integration & ergonomics — global hotkey (<Super><Alt>S) summoning the Sandbox Control Center via Ghostty terminal, XDG desktop launchers, Zsh/Bash autocompletions, and an automated Ed25519 SSH pairing wizard
Architecture & Infrastructure
Proxmox LXC Hardware Isolation Boundary
Proxmox VE on an ARM64 Raspberry Pi 4 hosts isolated Linux Container (LXC) instances. Autonomous agent executions, file system writes, and shell tools execute strictly within the container boundary, air-gapping the developer's primary machine against accidental damage or uncontrolled agent scripts.
Ephemeral In-Memory Secret Injection
Rather than persisting API credentials in container environment files or shell profiles, the client CLI gathers local provider keys and injects them as ephemeral environment exports directly into the SSH process memory per command invocation — leaving zero credentials on disk.
Workspace Time Machine & Disaster Recovery
Lightweight snapshot tooling captures pre-execution workspace checkpoints. If an autonomous agent corrupts dependencies or produces hallucinated modifications, a single rollback command restores the exact workspace state. Full container image backups (vzdump) provide complete disaster recovery.
Smart Bi-Directional Synchronization & Diff Inspection
An optimized rsync pipeline excludes version-control metadata, virtual environments, binaries, and local secrets. A remote diff inspector allows developers to review changed files in the terminal before syncing code back down to the local development environment.
Automated Port Tunneling & Active Service Discovery
SSH port forwards (3000, 5173, 8000, 8080, 8888) bridge web servers running inside the sandbox to localhost. A live port scanner detects active listening sockets inside the container and pairs with a one-key browser launcher to streamline UI testing.
Stylized 6-Tab Curses Terminal Dashboard
A custom curses TUI (sandbox-tui) delivers a comprehensive visual control center: agent launchers, instant snapshot rollbacks, visual diff review, real-time hardware telemetry gauges (CPU, memory, disk), power lifecycle controls, and multi-sandbox container cloning.