Beachead — AI Sandbox Orchestrator

Beachead is a desktop application that manages AI agents running inside Docker Sandbox microVMs. It provides a unified interface for creating personas, launching sandboxed agent sessions, managing network policies, and attaching long-term memory to each persona.

Prerequisites

Before using Beachead, install the following:

Dependency	Purpose	Install Guide
Docker Engine	Container runtime for sandboxes and memory MCP containers	docs.docker.com/engine/install
Docker Sandboxes (sbx)	CLI for managing sandbox microVMs	github.com/docker/sbx-releases
Git	Required for Repo Sync features (remote synchronization)	git-scm.com/downloads

Note: Docker Engine must be running for both sandbox sessions and per-persona memory features. Memory MCP containers are managed automatically via the Docker API (bollard crate).

Note: Git is optional but required for Repo Sync functionality. If git is not found on your PATH, Repo Sync features will be disabled (graceful degradation).

Platform-Specific Notes

Linux — Keyring Support

Repo Sync stores git credentials in the OS keyring. On Linux, this requires libsecret (used by GNOME Keyring / KDE Wallet):

Ubuntu/Debian:

sudo apt install libsecret-1-dev gnome-keyring

Fedora/RHEL:

sudo dnf install libsecret-devel gnome-keyring

Arch Linux:

sudo pacman -S libsecret gnome-keyring

If the keyring service is not available, credential storage for Repo Sync will fail. The rest of Beachead will continue to work normally.

Installing sbx

macOS:

brew install docker/tap/sbx

Windows:

winget install Docker.sbx

Linux (Ubuntu/Debian): Download the latest binary from sbx-releases and place it on your PATH:

sudo mv sbx /usr/local/bin/sbx
sudo chmod +x /usr/local/bin/sbx

Sign in to Docker

After installing sbx, authenticate with Docker:

sbx login

This opens a browser for Docker OAuth. Choose the "Balanced" network policy when prompted.

Quick Start

1. Launch Beachead

Open the Beachead application. On first launch it will verify that sbx and docker are available.

If either dependency is missing, the app will display setup instructions in the System Settings page.

2. Create a Persona

1. Navigate to Personas in the sidebar.
2. Click Create Persona.
3. Fill in:
   • Name — a unique identifier (e.g., "my-project-claude")
   • Agent Type — select from built-in agents (Claude Code, Codex, Copilot, etc.)
   • Workspace — path to a local project folder
4. Optionally enable Memory for long-term context retention.
5. Optionally add MCP Servers for custom tool integrations.
6. Click Save.

3. Configure Agent Credentials

Credential setup depends on the agent type:

API key agents (Gemini, OpenCode, etc.) — set the key before starting a session:

1. Navigate to Agents in the sidebar.
2. Click the Credentials tab.
3. Set the required API key for each service.

Interactive auth agents (Claude Code, Copilot, Cursor, etc.) — these are marked with a Sandbox Auth badge and handle authentication themselves. Start a session and follow the prompt in the terminal on first run.

OAuth agents (Codex) — authenticate via the terminal before starting a session:

sbx secret set -g openai --oauth

Credentials are stored securely in your OS keychain via sbx secret — they never touch the application database.

4. Start a Session

1. Navigate to Sessions in the sidebar.
2. Click New Session and select your persona.
3. A terminal tab opens with the agent running inside an isolated sandbox.
4. Interact with the agent directly in the terminal.

The sandbox mounts your workspace at the same path, so the agent can read and modify your project files.

5. Manage Network Policies

1. Navigate to Policies in the sidebar.
2. View and modify global network access rules.
3. Check the Traffic Log to see what network requests sandboxes are making.

6. Per-Persona Memory

Each persona can have long-term memory enabled, backed by a local MCP server running in a Docker container.

1. When creating or editing a persona, toggle Memory on.
2. The orchestrator automatically manages a dedicated memory container for that persona.
3. Memory persists across sessions — the agent retains context from previous conversations.
4. Memory data is stored in Docker volumes on your local machine.

Requirements: Docker Engine must be running for memory features. The memory MCP container starts automatically when Beachead launches.

7. Export and Import Configuration

You can export your full Beachead configuration for backup or transfer to another machine.

1. Navigate to Settings in the sidebar.
2. Click Export and set a password to encrypt the file.
3. To restore, click Import, select the file, and enter the password.

Exports include all personas, agent definitions, sessions, and MCP server configurations. Credentials are excluded — they are tied to the OS keychain and must be reconfigured on the destination machine.

Key Concepts

Term	Description
Persona	A saved configuration combining an agent, workspace, and settings
Agent	An AI tool (Claude Code, Codex, etc.) that runs inside a sandbox
Session	An active terminal connection to a running sandbox
Sandbox	A Docker Sandbox microVM with hypervisor-level isolation
Kit	A YAML config package applied to sandboxes at creation time
MCP	Model Context Protocol — enables agents to use external tools
Memory	Per-persona long-term context stored in a local MCP container
MCP Container	A Docker container hosting a memory MCP server (managed via bollard)
Template	A saved snapshot of a configured sandbox for reuse
Policy	A global network access rule applied to all sandboxes

Troubleshooting

sbx CLI not found

Ensure sbx is on your system PATH:

sbx version

If not found, reinstall following the instructions above.

Docker authentication failed

Sign in to Docker:

sbx login

Sandbox creation errors

Check that Docker is running:

docker info

Run diagnostics:

sbx diagnose

Credential issues

List configured secrets:

sbx secret ls

Set a missing credential:

sbx secret set -g <service> -t <api-key>

Architecture

Beachead runs as a Tauri 2.0 desktop app with:

• Rust backend (Axum HTTP/WebSocket server) — manages all sandbox operations
• React frontend — provides the UI with xterm.js terminals
• SQLite database — persists configuration locally (no secrets)

All sandbox operations go through the official sbx CLI. No undocumented APIs are used.

Acknowledgments

Development was aided by AI coding assistants.

License

MIT