Bilrost¶

Part of the qlawbox stack  ·  vindler  ·  qortex  ·  PyPI

Defense-in-depth sandbox for agent runtime containment.

---

The Problem¶

Running AI agents directly on your host machine is risky:

• File access -- agents can read sensitive files, credentials, SSH keys, and configs.
• Unrestricted network -- nothing prevents an agent from phoning home to arbitrary endpoints.
• No process isolation -- agent processes share your session, environment, and shell history.
• Secret leakage -- API keys end up in environment variables, logs, and .bash_history.

You need a boundary between "what the agent can touch" and "everything else on your machine."

The Solution¶

Bilrost runs your agents inside a hardened Linux VM (Ubuntu 24.04 on Lima) with strict network policies, layered filesystem isolation, and secure secrets handling. Everything provisions from a single command on macOS.

Changes only reach your host through a validated sync gate that runs gitleaks scanning, path allowlists, and size checks before anything is copied back.

Feature Highlights¶

Feature	What it does
Python CLI	bilrost up, bilrost status, bilrost ssh — profile-based management
Dual-Container Isolation	Per-tool network routing: air-gapped by default, bridge only for tools that need it
Filesystem Isolation	OverlayFS makes host mounts read-only; all writes land in an overlay layer
Network Containment	UFW firewall allows only HTTPS, DNS, and Tailscale; everything else is denied and logged
MCP Server	LLM agents manage the sandbox via FastMCP (bilrost-mcp)
Secrets Management	Multiple injection methods, file permissions at 0600, never exposed in logs
Config/Data Isolation	Config files copied (patchable), agent data symlinked to persistent mounts
Gated Sync	gitleaks scan + path allowlist before any changes reach the host
GitHub CLI	gh installed in VM and sandbox containers with GH_TOKEN passthrough
Obsidian Vault	Vault bind-mounted with overlay protection; iCloud rsync sync
Qortex Interop	Docker-deployed knowledge graph with HTTP REST transport, seed exchange, and buildlog interop
Telegram Integration	Bot integration with pairing-based access control
Cadence Pipeline	Ambient AI: vault watch → insight extraction → Telegram delivery
Tailscale Routing	Route to your private network via the host

Quick Start¶

# Install from PyPI
pip install bilrost
# or: pipx install bilrost / uv tool install bilrost

# Create a profile interactively
bilrost init

# Provision the VM
bilrost up

# Check status
bilrost status

# SSH into the VM
bilrost ssh

Or from source:

git clone https://github.com/Peleke/openclaw-sandbox.git
cd openclaw-sandbox
uv pip install -e cli/

Or use bootstrap.sh directly:

./bootstrap.sh --openclaw ~/Projects/openclaw --secrets ~/.openclaw-secrets.env

Requirements¶

• macOS (Apple Silicon or Intel)
• Homebrew
• ~10GB disk space

Documentation¶

Section	What's inside
Getting Started	Prerequisites, installation, and your first session
Usage	Bootstrap flags, filesystem modes, sync gate, and VM management
Configuration	Secrets, Docker sandbox, network policy, Telegram, GitHub CLI, Obsidian, Cadence, and buildlog
Architecture	System design, defense-in-depth layers, secrets pipeline, and overlay filesystem
Security	Threat model and STRIDE analysis
Development	Test suites, contributing guide, and release process
Troubleshooting	Common issues, diagnostic commands, and recovery steps

Defense-in-Depth¶

Two layers of isolation work together:

Layer 1 (overlay):   gateway process  --> VM + read-only host mounts + OverlayFS
Layer 2 (docker):    tool execution   --> Isolated container (air-gapped)
                     network tools    --> Network container (bridge, per-tool routing)

Host mounts are read-only by default. All writes land in an OverlayFS upper layer inside the VM. Individual tool executions are further sandboxed inside Docker containers with dual-container network isolation: most tools run air-gapped, while only web_fetch, web_search, and gh commands get bridge networking.

Security at a Glance¶

1. Filesystem isolation -- host mounts read-only, writes contained in OverlayFS
2. Docker sandbox -- tool executions in containers with bridge networking
3. Gated sync -- gitleaks scan + path allowlist before changes reach host
4. Secrets never logged -- all Ansible tasks use no_log: true
5. File permissions -- /etc/openclaw/secrets.env is 0600
6. No process exposure -- EnvironmentFile= instead of Environment=
7. Network isolation -- explicit allowlist, all else denied and logged
8. Audit trail -- inotifywait watcher logs all overlay writes

The qlawbox stack¶

Bilrost is the isolation layer. The full stack:

Component	Role	Docs
vindler	Agent runtime (OpenClaw fork)	Docs
bilrost	Hardened VM isolation (this project)	PyPI
qortex	Knowledge graph with adaptive learning	PyPI

License¶

MIT License. See LICENSE.