{"id":50363645,"url":"https://github.com/beachead-dev/beachead","last_synced_at":"2026-05-30T03:00:38.565Z","repository":{"id":361075372,"uuid":"1249503678","full_name":"beachead-dev/beachead","owner":"beachead-dev","description":"Desktop app for managing AI agents in isolated Docker Sandbox microVMs","archived":false,"fork":false,"pushed_at":"2026-05-29T04:28:40.000Z","size":8546,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T06:16:06.928Z","etag":null,"topics":["ai-agents","docker","docker-sandbox","llm","mcp","rust","security","tauri"],"latest_commit_sha":null,"homepage":"https://www.beachead.net","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beachead-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-25T19:15:31.000Z","updated_at":"2026-05-29T04:28:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/beachead-dev/beachead","commit_stats":null,"previous_names":["beachead-dev/beachead"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/beachead-dev/beachead","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beachead-dev%2Fbeachead","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beachead-dev%2Fbeachead/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beachead-dev%2Fbeachead/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beachead-dev%2Fbeachead/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beachead-dev","download_url":"https://codeload.github.com/beachead-dev/beachead/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beachead-dev%2Fbeachead/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33678271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","docker","docker-sandbox","llm","mcp","rust","security","tauri"],"created_at":"2026-05-30T03:00:21.851Z","updated_at":"2026-05-30T03:00:38.559Z","avatar_url":"https://github.com/beachead-dev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Beachead — Secure AI Orchestrator\n\nBeachead is a local-only 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.\n\n## Prerequisites\n\nBefore using Beachead, install the following:\n\n| Dependency | Purpose | Install Guide |\n|-----------|---------|---------------|\n| **Docker Engine** | Container runtime for sandboxes and memory MCP containers | [docs.docker.com/engine/install](https://docs.docker.com/engine/install/) |\n| **Docker Sandboxes (sbx)** | CLI for managing sandbox microVMs | [github.com/docker/sbx-releases](https://github.com/docker/sbx-releases/releases) |\n| **Git** | Required for Repo Sync features (remote synchronization) | [git-scm.com/downloads](https://git-scm.com/downloads) |\n\n\u003e **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).\n\n\u003e **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).\n\n### Platform-Specific Notes\n\n#### Linux — Keyring Support\n\nRepo Sync stores git credentials in the OS keyring. On Linux, this requires `libsecret` (used by GNOME Keyring / KDE Wallet):\n\n**Ubuntu/Debian:**\n```bash\nsudo apt install libsecret-1-dev gnome-keyring\n```\n\n**Fedora/RHEL:**\n```bash\nsudo dnf install libsecret-devel gnome-keyring\n```\n\n**Arch Linux:**\n```bash\nsudo pacman -S libsecret gnome-keyring\n```\n\nIf the keyring service is not available, credential storage for Repo Sync will fail. The rest of Beachead will continue to work normally.\n\n### Installing sbx\n\n**macOS:**\n```bash\nbrew install docker/tap/sbx\n```\n\n**Windows:**\n```powershell\nwinget install Docker.sbx\n```\n\n**Linux (Ubuntu/Debian):**\nDownload the latest binary from [sbx-releases](https://github.com/docker/sbx-releases/releases) and place it on your PATH:\n```bash\nsudo mv sbx /usr/local/bin/sbx\nsudo chmod +x /usr/local/bin/sbx\n```\n\n### Sign in to Docker\n\nAfter installing sbx, authenticate with Docker:\n```bash\nsbx login\n```\nThis opens a browser for Docker OAuth. Choose the \"Balanced\" network policy when prompted.\n\n## Quick Start\n\n### 1. Launch Beachead\n\nOpen the Beachead application. On first launch it will verify that `sbx` and `docker` are available.\n\nIf either dependency is missing, the app will display setup instructions in the System Settings page.\n\n### 2. Create a Persona\n\n1. Navigate to **Personas** in the sidebar.\n2. Click **Create Persona**.\n3. Fill in:\n   - **Name** — a unique identifier (e.g., \"my-project-claude\")\n   - **Agent Type** — select from built-in agents (Claude Code, Codex, Copilot, etc.)\n   - **Workspace** — path to a local project folder\n4. Optionally enable **Memory** for long-term context retention.\n5. Optionally add **MCP Servers** for custom tool integrations.\n6. Click **Save**.\n\n### 3. Configure Agent Credentials\n\nCredential setup depends on the agent type:\n\n**API key agents** (Gemini, OpenCode, etc.) — set the key before starting a session:\n1. Navigate to **Agents** in the sidebar.\n2. Click the **Credentials** tab.\n3. Set the required API key for each service.\n\n**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.\n\n**OAuth agents** (Codex) — authenticate via the terminal before starting a session:\n```bash\nsbx secret set -g openai --oauth\n```\n\nCredentials are stored securely in your OS keychain via `sbx secret` — they never touch the application database.\n\n### 4. Start a Session\n\n1. Navigate to **Sessions** in the sidebar.\n2. Click **New Session** and select your persona.\n3. A terminal tab opens with the agent running inside an isolated sandbox.\n4. Interact with the agent directly in the terminal.\n\nThe sandbox mounts your workspace at the same path, so the agent can read and modify your project files.\n\n### 5. Manage Network Policies\n\n1. Navigate to **Policies** in the sidebar.\n2. View and modify global network access rules.\n3. Check the **Traffic Log** to see what network requests sandboxes are making.\n\n### 6. Per-Persona Memory\n\nEach persona can have long-term memory enabled, backed by a local MCP server running in a Docker container.\n\n1. When creating or editing a persona, toggle **Memory** on.\n2. The orchestrator automatically manages a dedicated memory container for that persona.\n3. Memory persists across sessions — the agent retains context from previous conversations.\n4. Memory data is stored in Docker volumes on your local machine.\n\n**Requirements:** Docker Engine must be running for memory features. The memory MCP container starts automatically when Beachead launches.\n\n### 7. Export and Import Configuration\n\nYou can export your full Beachead configuration for backup or transfer to another machine.\n\n1. Navigate to **Settings** in the sidebar.\n2. Click **Export** and set a password to encrypt the file.\n3. To restore, click **Import**, select the file, and enter the password.\n\nExports 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.\n\n## Key Concepts\n\n| Term | Description |\n|------|-------------|\n| **Persona** | A saved configuration combining an agent, workspace, and settings |\n| **Agent** | An AI tool (Claude Code, Codex, etc.) that runs inside a sandbox |\n| **Session** | An active terminal connection to a running sandbox |\n| **Sandbox** | A Docker Sandbox microVM with hypervisor-level isolation |\n| **Kit** | A YAML config package applied to sandboxes at creation time |\n| **MCP** | Model Context Protocol — enables agents to use external tools |\n| **Memory** | Per-persona long-term context stored in a local MCP container |\n| **MCP Container** | A Docker container hosting a memory MCP server (managed via bollard) |\n| **Template** | A saved snapshot of a configured sandbox for reuse |\n| **Policy** | A global network access rule applied to all sandboxes |\n\n## Troubleshooting\n\n### sbx CLI not found\n\nEnsure `sbx` is on your system PATH:\n```bash\nsbx version\n```\nIf not found, reinstall following the instructions above.\n\n### Docker authentication failed\n\nSign in to Docker:\n```bash\nsbx login\n```\n\n### Sandbox creation errors\n\nCheck that Docker is running:\n```bash\ndocker info\n```\n\nRun diagnostics:\n```bash\nsbx diagnose\n```\n\n### Credential issues\n\nList configured secrets:\n```bash\nsbx secret ls\n```\n\nSet a missing credential:\n```bash\nsbx secret set -g \u003cservice\u003e -t \u003capi-key\u003e\n```\n\n## Architecture\n\nBeachead runs as a Tauri 2.0 desktop app with:\n- **Rust backend** (Axum HTTP/WebSocket server) — manages all sandbox operations\n- **React frontend** — provides the UI with xterm.js terminals\n- **SQLite database** — persists configuration locally (no secrets)\n\nAll sandbox operations go through the official `sbx` CLI. No undocumented APIs are used.\n\n## Acknowledgments\n\nDevelopment was aided by AI coding assistants.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeachead-dev%2Fbeachead","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeachead-dev%2Fbeachead","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeachead-dev%2Fbeachead/lists"}