convez.ai
MCP ServerDevOps & InfraestruturaAvançado
beachead-dev

Beachead — Orquestrador de Sandbox para Agentes IA

beachead-dev/beachead

Desktop para orquestrar agentes IA em Docker sandbox isolado

Ver no GitHub
BomPluginScore · de 0 a 100

Aplicação desktop para gerenciar agentes de IA executando dentro de microVMs Docker isoladas. Oferece interface unificada para criar personas, gerenciar políticas de rede, associar memória de longo prazo e coordenar múltiplas sessões de agentes em ambiente sandboxado seguro.

Instalação

$npx convez-ai beachead-dev/beachead

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
87%
Último commit
há 3 meses
Versão
v0.17.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Executar múltiplos agentes IA com segurança em ambientes isolados
  • Gerenciar personas com memória persistente e contexto de longo prazo
  • Coordenar políticas de rede e acesso para agentes sandboxados
  • Integrar MCP Servers customizados com agentes específicos

Veredito

Beachead é uma solução robusta para quem precisa executar múltiplos agentes IA com isolamento forte. Requer infraestrutura complexa (Docker Engine, sbx, keyring) e é destinado a usuários avançados que priorizam segurança e controle.

README

A tradução para o português deste README ainda está na fila.

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:

DependencyPurposeInstall Guide
Docker EngineContainer runtime for sandboxes and memory MCP containersdocs.docker.com/engine/install
Docker Sandboxes (sbx)CLI for managing sandbox microVMsgithub.com/docker/sbx-releases
GitRequired 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

TermDescription
PersonaA saved configuration combining an agent, workspace, and settings
AgentAn AI tool (Claude Code, Codex, etc.) that runs inside a sandbox
SessionAn active terminal connection to a running sandbox
SandboxA Docker Sandbox microVM with hypervisor-level isolation
KitA YAML config package applied to sandboxes at creation time
MCPModel Context Protocol — enables agents to use external tools
MemoryPer-persona long-term context stored in a local MCP container
MCP ContainerA Docker container hosting a memory MCP server (managed via bollard)
TemplateA saved snapshot of a configured sandbox for reuse
PolicyA 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

Ver o original no GitHub

Bom para

Relacionados