Agents Anywhere
krzysztofgawrys/anywhere_agents
Federação multi-máquina autohospedada para agentes de IA coding
Ver no GitHubFederação autohospedada para agentes de IA coding (Claude Code, Copilot, Codex). Execute workers em múltiplas máquinas que você controla — laptop, servidor caseiro, VPC — e acesse todos por uma única UI web/mobile. Seu código nunca sai da sua infraestrutura.
Instalação
npx convez-ai krzysztofgawrys/anywhere_agents1 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
Casos de uso
- Executar múltiplos agentes de código em máquinas diferentes com controle centralizado
- Manter código-fonte confinado à sua VPC enquanto trabalha remotamente
- Construir homelab com múltiplos workers de IA coordenados
- Proteger dados sensíveis evitando terceiros no caminho dos dados
Veredito

Solução robusta para quem precisa federação multi-máquina de agentes de código sem intermediários. Destaca-se pela arquitetura distribuída autohospedada, mas exige expertise em infra e orquestração. Primeira opção OSS para manter código confinado em VPC enquanto o acessa remotamente.
README
A tradução para o português deste README ainda está na fila.
Agents Anywhere
Self-hosted federation for AI coding agents. Run Claude Code on your laptop, GitHub Copilot CLI on your home server, another worker inside a locked-down VPC, and reach all of them from a single web/mobile UI you control. No vendor in the data path. Your code never leaves your infrastructure.
Installable as a PWA on Android / iOS. Exposed to the public internet (optionally) via Cloudflare Tunnel + Cloudflare Access JWT auth, or kept entirely on a private network reached only over VPN/intranet (no public ingress). True air-gap is not possible because the underlying agent SDKs call out to their hosted LLM APIs - any deployment that needs zero outbound traffic would also need a local model backend, which is out of scope here.
Why this exists
There are already plenty of web wrappers around claude and copilot CLIs.
What none of them do is let you point one UI at workers running on multiple
machines that you own, with no third party in the middle.
| Solution | Where the hub runs | Where workers run | Code transits a third party? | Multi-machine federation |
|---|---|---|---|---|
| CloudCLI Cloud | Vendor SaaS | Your box, through their tunnel | Yes | No |
| CloudCLI (self-host) | Your box | Same box only | No | No |
| Happy Coder | Vendor "Happy Server" (E2E enc) | Your CLI, through their tunnel | Yes (E2E, but still their infra) | No |
GitHub Copilot /remote on | github.com | GitHub-hosted or your runner | Yes | No |
| Claude Managed Agents | Cloudflare | Cloudflare microVMs | Yes | No |
| NetClode | Vendor managed | Vendor microVMs | Yes | No |
| claude-code-webui / similar | Your box | Same box only | No | No |
| Agents Anywhere (this repo) | Your box | N machines you own, anywhere | No | Yes |
If "my source code must not leave VPC-A, but I still want to drive an agent on my phone from a cafe" is a problem you actually have, this is the only OSS project I am aware of that solves it end-to-end.
Deployment topologies
The same binary supports four very different setups. Pick the one that matches what you have.
1. Laptop only (dev)
Browser ────▶ Hub ────▶ worker-claude (all on one laptop, docker compose)
────▶ worker-copilot
Single docker compose up. No tunnel, no Cloudflare, no auth (dev mode).
Use this to evaluate the project in 5 minutes.
2. Laptop + home server (homelab)
Phone ─▶ CF Tunnel ─▶ Hub (laptop)
├──▶ worker-claude (laptop)
└──▶ worker-claude (home server, 192.168.1.25:8002)
Workers registered in workers.json with their LAN addresses. Hub re-reads
the file on every WS connect, so adding a worker is one line + nothing to
restart. From your phone you switch between machines in the sidebar.
3. Hub on VPS + workers in VPC (small team)
Phone ─▶ CF Access ─▶ Hub (VPS or small EC2)
├──▶ worker-claude (EC2 in VPC, behind SG)
└──▶ worker-copilot (EC2 in VPC, behind SG)
Hub is the only public surface and is gated by Cloudflare Access (JWT
verified on WS handshake, key rotation handled automatically). Workers
listen on private subnets, only the hub can reach them, only their
shared WORKER_SECRET lets the hub in. Code never leaves the VPC.
4. Cross-account / regulated (enterprise, no public ingress)
Workstation ─▶ Hub (VPC-A, behind internal ALB + corporate SSO)
├──▶ worker-claude (VPC-B, dedicated to client A)
├──▶ worker-claude (VPC-C, dedicated to client B)
└──▶ worker-claude (on-prem GPU box, intranet only)
Sessions are segregated by worker. Each worker only sees the project roots mounted into its container. The Anthropic / GitHub API endpoints are the only outbound destinations, and you can lock egress to those specific hostnames with a security group or HTTP egress proxy. Nothing in the deployment needs to accept connections from the public internet - browser access goes through corporate VPN/SSO terminating at the hub, and workers are reachable only from the hub's VPC (or via reverse mode for boxes that can't accept ingress at all). Not air-gap (the agents need their LLM APIs) but the smallest network surface area short of swapping in a local model backend.
Network setup (how the hub reaches workers)
Out of the box, the hub talks to workers via WebSocket. Two directions are
supported. Pick one per worker - workers.json mode field switches
between them.
Option A: outbound mode (default) - hub dials worker
Worker runs a WS server (port 8002 for claude, 8003 for copilot). Hub
reaches it at the URL you put in workers.json. Requires the worker port
to be reachable from the hub: same machine, same LAN, VPN, Tailscale, or
VPC peering.
Easiest enabler: Tailscale (free for personal use, up to 6 users with
unlimited devices). Each box gets a stable 100.x.x.x address; put that
in workers.json and forget about NAT and firewalls.
{
"id": "vpc-worker", "type": "claude", "label": "VPC",
"mode": "outbound",
"url": "ws://100.64.1.5:8002/ws", "secret": "..."
}
Headscale (self-hosted Tailscale coordination server) works the same way if you don't want a vendor anywhere in the loop.
Option B: inbound (reverse) mode - worker dials hub
Worker has no inbound port. It dials a long-lived control WS to the hub
at /worker-register, identifies itself by WORKER_ID, and reacts to
open_data_channel commands by dialing a fresh data WS per browser
session. Use this when the worker sits in a closed VPC, behind a NAT, or
in a corporate network where only egress 443 is allowed.
Worker side env vars:
WORKER_MODE=inbound
HUB_PUBLIC_URL=https://hub.example.com # publicly reachable hub URL (CF Tunnel)
WORKER_ID=remote-copilot # must match workers.json on hub
WORKER_LABEL=Remote # cosmetic
WORKER_SECRET=... # same as hub's WORKER_SECRET
(HUB_URL, used by the worker for out-of-band HTTP push to
hub/api/internal/push, is a separate variable that should stay as the
internal docker / VPN address. HUB_PUBLIC_URL is only used for the
reverse-mode control + data WS handshake which must traverse CF Access.)
Hub side workers.json entry (no url needed):
{
"id": "remote-copilot", "type": "copilot", "label": "Remote",
"mode": "inbound", "secret": "..."
}
Auth: shared secret + (optional) Cloudflare Access service tokens.
Cloudflare Access service tokens for inbound mode
If the hub sits behind Cloudflare Access, browser sessions go through SSO (email allowlist) - but workers can't do SSO. CF Access supports service tokens for exactly this M2M case.
Setup in CF Dashboard:
-
Zero Trust->Access->Service Auth->Service Tokens. Create one (e.g.worker-remote-copilot). Copy Client ID + Secret (secret shown once). -
Zero Trust->Access->Applications->Add an application->Self-hosted. Application domainhub.example.com, path/worker-register. Policy: Allow + Service Token = the one above. Repeat for path/worker-data(or use a single app with path glob). -
Pass to worker:
CF_ACCESS_CLIENT_ID=<client id> CF_ACCESS_CLIENT_SECRET=<client secret>
Now the worker passes both CF Access (service token check at the edge)
and the hub's WORKER_SECRET check (in-app handshake). Two independent
layers; compromise of one is not enough.
Option C: outbound mode + per-worker Cloudflare Tunnel
Hybrid for users who want each worker reachable from anywhere without
running a VPN. Worker box runs its own cloudflared (outbound only),
hub dials wss://worker-x.example.com/ws. Same auth layering as Option
B works here (service token sent by hub when dialing the worker URL).
Trade-off: Cloudflare is in the data path of every worker. Latency hop of ~50-100ms per direction; for streaming and tool calls this is fine, for the xterm.js terminal you may notice typing lag.
Comparison
| Aspect | Outbound (LAN/Tailscale) | Outbound (CF Tunnel per worker) | Inbound (reverse) |
|---|---|---|---|
| Worker needs ingress? | Yes (via VPN/mesh) | No | No |
| Vendor in data path of worker? | No (or Tailscale coordination only) | Yes (CF) | No |
| Per-worker public hostname? | No | Yes | No |
| Setup per worker | Tailscale up | cloudflared + DNS | Env vars |
| Latency | Direct mesh | +50-100ms hop | Direct TCP |
| Code changes required | None | None | None (already shipped) |
Architecture
Hub + multi-agent workers running in Docker.
- Hub (
hub/): FastAPI. Frontend static serve, Cloudflare Access auth, WebSocket router between browser and N workers, push notifications, per-worker model registry. - Workers (
worker-claude/,worker-copilot/,worker-codex/,worker-windows/): FastAPI. One per agent SDK family. Each handles project scanning, terminal, file browser, session management, and routes prompts into its SDK's session loop.worker-claude- Anthropicclaude-agent-sdkworker-copilot-github-copilot-sdk(GitHub Copilot CLI)worker-codex-openai-codex-sdk(OpenAI Codex CLI)worker-windows- Claude SDK on Windows, plus an Excel automation module (Office.js task-pane add-in + an MCP server onEXCEL_PORT, default3847). Runs natively (start.ps1), not in Docker. Supports both server and inbound (reverse) modes like the other workers.
- Shared (
shared/worker_shared/): SDK-agnostic modules (db, files, terminal, locks, projects service, session registry) consumed by every worker via a uv path source. Adding a new agent SDK = one new worker directory reusing these modules. - Frontend (
frontend/): React + Vite + Tailwind, builds tofrontend-dist/which is volume-mounted into hub (no hub rebuild on frontend changes). - Tunnel (optional): cloudflared, included in
compose.yml. - Auth (optional): Cloudflare Access JWT verified on WS handshake. Dev bypass if unconfigured.
Browser ─WS─▶ Hub ─WS─▶ worker-claude (Claude SDK)
─WS─▶ worker-copilot (Copilot SDK)
─WS─▶ worker-... (any future SDK)
Workers are configured in workers.json (id, type, label, url, secret).
Hub re-reads workers.json on every frontend WS connect (no hub restart
needed to add a worker) and keeps retrying any worker that isn't reachable
yet via a per-WS retry loop (default 30s). When a worker (re)appears, hub
pushes a fresh projects payload to the frontend automatically.
Each project carries a worker_id + worker_type; routing is by project
ID so prompts go to the worker that owns the conversation. Active session
is the worker of the most recent new_session / resume_session.
Quick start
# Clone, configure
git clone <this repo>
cd anywhere_agents
# Enable the secret-scanning git hooks (pre-commit + pre-push). One-time.
./scripts/install-hooks.sh
cp .env.example .env # fill in UID, GID, WORKER_SECRET
# Configure workers (id, type, label, url, secret)
cp workers.json.example workers.json # or edit by hand
# Build + start (hub, local worker-claude, optional cloudflared)
docker compose up -d --build
# Open http://localhost:8001 (or your tunnel hostname)
Config that can hold secrets is gitignored; the repo ships only
*.exampletemplates. Copy the one you need and fill it in locally - never commit the real file. The pre-push hook scans for secrets and blocks a push if it finds any (see Git hooks).
Adding a remote worker from another machine:
# On the remote machine: copy the gitignored template, fill in secrets,
# then bring up a standalone worker (pulls from GHCR).
cp workers/worker-claude-compose.yml.example workers/worker-claude-compose.yml
docker compose -f workers/worker-claude-compose.yml up -d
# On the hub machine: append a new entry to workers.json
# { "id": "big-box", "type": "claude", "label": "Big Box",
# "url": "ws://10.0.0.42:8002/ws", "secret": "..." }
# No hub restart needed - hub re-reads on next browser WS connect.
Frontend dev:
cd frontend && npm install && npm run build
# Hub serves from frontend-dist/ volume mount - no rebuild needed
# Hub Python changes do require a rebuild:
docker compose up -d --build hub
Compliance / security posture
- Data path: browser - hub - worker. Nothing in between except the optional Cloudflare Tunnel (you control the tunnel; CF is the proxy, not the agent host).
- Where the source code is read: only on the worker container, from a bind-mounted host directory. Worker -> hub WS carries diffs and tool output but no checkouts.
- Outbound calls: worker -> Anthropic API (
api.anthropic.com:443) forworker-claude, worker -> GitHub Copilot API forworker-copilot. Lockable behind a security group / egress proxy if needed. Hub has no outbound dependencies once running. - Auth between browser and hub: Cloudflare Access JWT (HS256 from CF's
rotating JWKS, validated against
CF_ACCESS_AUDand an email allowlist). Fail-closed inCLAUDE_WEB_ENV=prodif the CF env vars are missing. - Auth between hub and worker: shared secret (
WORKER_SECRET) over the WS handshake. Worker -> hub push callbacks (HTTP POST/api/internal/push) carry the same secret inX-Worker-Secret. - Secrets at rest:
~/.claude-web/push_subs.json(web push subscriptions, atomic write), SQLite DB (project index, no source code). No secrets logged. - Secret hygiene in git: real config holding secrets is gitignored; only
*.exampletemplates are committed, and pre-commit/pre-push hooks scan for secrets (see Git hooks). - Per-session locks: a session is bound to the WS connection that
resumed it. A second device gets
session_lockedwith the current holder's device label and can either back off or take over (sendslock_revokedto the previous owner, who is flipped to read-only). - Permission broker: tool calls surface as
permission_requestblocks for explicit Allow / Deny unlessauto_approveis set per project or armed per prompt. User's~/.claude/settings.jsonpermissions.allowpatterns still apply upstream.
Features
Chat & streaming
- Real-time WS streaming (text deltas, thinking blocks, tool calls)
- Markdown + syntax highlight (ReactMarkdown + rehype-highlight)
- LCS diff viewer for Edit / Write tool calls (green/red lines, truncation at 200 lines)
- Activity bar (Thinking / Running tool / Sending) above the composer
- Tool blocks collapsed by default
- Smart auto-scroll (only when user is near the bottom)
- Session history search with match counter and prev/next navigation
Composer
- Slash command autocomplete (Up/Down/Tab/Enter/Escape):
/clear,/compact,/new/plan,/act- frontend-only plan mode (prepends a read-only instruction to the prompt)/model <id>- mid-session model switch. Model list is fetched per worker (Copilot viaCopilotClient.list_models(), Claude from a hub-side default that you can override)./model defaultclears the per-session override.
- Image upload: file picker, clipboard paste, drag-and-drop (PNG/JPEG/GIF/WEBP), with thumbnail preview strip
- Voice input via Web Speech API
- Per-prompt auto-approve checkbox
- Stream tokens toggle (persisted to localStorage)
- Mobile-aware: Enter sends on desktop, overflow menu on touch
Projects & sessions
- Sidebar with collapsible project list, lazy-loaded sessions
- Project scanner walks
~/.claude/projects/(or~/.copilot/session-state/) on worker startup, registers in SQLite - Projects sorted by last session modification time
- Project search/filter (name or path, case-insensitive)
- Worker filter dropdown (shown when more than one worker is connected)
- Active session highlighted yellow; a session that streams in the background (different chat) is flagged blue on its session row, project, and worker filter, clearing when you open it. Background-session stream events never bleed into the chat you are currently viewing.
- New project browser - modal FS navigator with breadcrumbs, "New folder"
- Projects whose
cwddoesn't exist on the worker shown greyed-out - Active project/session persisted to localStorage (survives reload / push tap)
- Paginated session history (
before_uuid/has_more)
AskUserQuestion (multi-question)
- Worker sends full list of questions from a single AskUserQuestion call
- One input per question with option buttons that pre-fill the field
- Minimize/expand toggle, internal scroll, dismiss button to unblock the agent with empty answers
File browser
- Sandboxed directory listing (file/folder icons, sizes, symlink-aware)
- File viewer: text files with syntax highlight, image preview, binary detection, "too large" notice
- File editing: textarea, Save/Cancel, Ctrl/Cmd+S shortcut
write_fileWS message persists back to disk
Terminal
- xterm.js + FitAddon, JetBrains Mono / Fira Code / Cascadia Code stack
- PTY fork on worker side, asyncio reader
- Dynamic resize via ResizeObserver
- Hide without kill - PTY stays alive when terminal is closed
- Mobile accessory key bar (touch only): Esc, Tab, a sticky Ctrl that
composes with the next key, and arrow keys - floats just above the on-screen
keyboard (tracked via
visualViewport) instead of hiding behind it - Optional in-app keyboard (toggle): suppresses the OS keyboard and renders a built-in QWERTY + symbols layout that feeds the PTY directly
Permissions
- Per-project
auto_approveflag (sidebar dot + header pill, toggleable mid-session) - Per-prompt one-shot override via composer checkbox (armed before query,
disarmed after
result) - Otherwise every tool call surfaces a
permission_requestblock above the composer
Locks
- Lock is per
session_id, not per project. Held by the WS connection that most recently callednew_session/resume_session. - Second client resuming the same session gets
session_lockedwith the current holder's device label. Modal offers "Take over" (force: true). - Takeover sends
lock_revokedto the previous owner; chat store flips to read-only. - Locks auto-release on WS disconnect / timeout.
Notifications (dedup'd)
- Web Push (server-side): worker POSTs
push_notifytohub/api/internal/push(authenticated withX-Worker-Secret). This out-of-band path survives client WS disconnects (PWA swiped away on Android, etc.). Subscriptions persisted to~/.claude-web/push_subs.json(atomic write); dead endpoints (403/404/410) pruned automatically. - Local (client-side):
useVisibilityNotifyfallback when push is not subscribed. Two-tone Web Audio chime (880Hz / 1100Hz).
Both use tag: "claude-result" so they don't stack. Local notify is
skipped when push is active. Service worker suppresses push banner when
any client window has visibilityState === 'visible', and any lingering
tray notifications are cleared when the app becomes visible again (opened
by any means, not just by tapping the notification).
PWA
- Web App Manifest with icons (192px + 512px, separate
anyandmaskable) - Service worker (install/activate/fetch/notification click handlers)
- Screen Wake Lock during active streaming (re-acquired on visibility change)
- Cloudflare Access bypass rules for public PWA assets
(
/manifest.json,/icon-*.png,/sw.js) so Chrome can generate a proper WebAPK
Conventions
- Python: async everywhere, full type hints,
mypy --strict,structlogfor logging - TypeScript: strict mode, functional components + hooks, Tailwind utility-first
- WS protocol: every message is
{ type, payload }JSON - Commits: conventional commits (
feat:,fix:,refactor:) - Dependency posture: no socket.io, no Redux, no react-query - keep the surface minimal
Git hooks / secret scanning
Secret hygiene is enforced at the git layer so a secret cannot be committed or pushed regardless of who (a human or an agent) runs git.
./scripts/install-hooks.shpointscore.hooksPathat.githooks/.- pre-commit scans staged changes; pre-push scans each pushed commit
range. Both run
gitleaks(regex rules + Shannon-entropy heuristics, when installed) AND a bundled regex/entropy fallback (secret-fallback.py), and block if either flags something - so protection still works where gitleaks is not installed (fresh clones, other worker containers). .gitleaks.tomlextends the default ruleset with an allowlist for template placeholders (${VAR},<...>,changeme).- Real config holding secrets (
*.env,start.ps1, worker*-compose.yml,workers.json) is gitignored; only sanitized*.exampletemplates are committed. Copy the*.example, fill it in locally, never commit the real file. - Install gitleaks for the strongest coverage (https://github.com/gitleaks/gitleaks); the hooks degrade gracefully without it.
--no-verifybypasses the hooks. Do not use it to push past a finding - fix the value or update the allowlist.
Module layout
hub/src/
├── main.py FastAPI app, static serving, WS endpoint, auth, internal push API
├── auth/cf_access.py CF Access JWT verification + key rotation (1h cert cache)
├── push/manager.py Web Push (VAPID) - persistent subs, dead endpoint pruning
├── workers/
│ ├── registry.py Read workers.json - WorkerInfo list
│ ├── connection.py WorkerConnection - WS client to a single worker
│ └── project_index.py ProjectIndex - hub_id <-> (worker_id, worker_pid) mapping
└── ws/handler.py Multi-worker WS proxy + message routing
shared/worker_shared/ (path-installed in every worker via uv sources)
├── db.py aiosqlite singleton + schema (projects table)
├── files/browser.py Sandboxed file browser (symlink-aware) + write_file
├── terminal/session.py PTY terminal session (pty fork + asyncio reader)
├── locks/manager.py per-session lock registry (takeover supported)
├── projects/service.py project CRUD (list, get, set_auto_approve)
└── sdk/registry.py Session parking registry (keeps sessions alive after
WS disconnect) - typed against a structural Protocol
worker-claude/src/ (Anthropic Claude SDK runtime)
├── main.py FastAPI app, WS endpoint with shared secret auth
├── projects/scanner.py walk ~/.claude/projects/, register in DB
├── sessions/reader.py parse .jsonl, list sessions, paginated history
├── sdk/
│ ├── session.py ClaudeSDKClient wrapper (streaming, model switch, push)
│ ├── manager.py SessionManager - owns active session per WS
│ ├── permissions.py PermissionBroker - gated tool-use approvals
│ └── registry.py Session parking after WS disconnect
└── ws/handler.py WS routing + heartbeat
worker-copilot/src/ (GitHub Copilot SDK runtime - mirrors worker-claude)
├── main.py FastAPI app, lifespan starts/stops CopilotClient
├── projects/scanner.py walk ~/.copilot/session-state/, group by workspace_path
├── sessions/reader.py parse events.jsonl (Copilot raw camelCase), build
│ ChatMessage[] with tool blocks attached by toolCallId
├── sdk/
│ ├── client.py Singleton CopilotClient (bundled CLI subprocess)
│ ├── session.py CopilotSession wrapper - event mapping
│ │ (AssistantMessageDelta -> text_delta, ToolExecutionStart
│ │ -> tool_call, SessionIdle -> result, etc.)
│ ├── manager.py SessionManager - owns active session per WS
│ └── permissions.py PermissionBroker - bridges to SDK's
│ on_permission_request callback
└── ws/handler.py WS routing + heartbeat + list_models endpoint
worker-windows/src/ (Claude SDK on Windows + Excel automation)
├── main.py FastAPI app, server + inbound modes, /internal/upload
├── modules/excel/ Office.js task-pane add-in + MCP server (EXCEL_PORT)
│ bridging Claude tool calls to live Excel
├── sdk/ session/manager/permissions (mirrors worker-claude)
├── projects/, sessions/, terminal/, ws/ same shape as the other workers
└── start.ps1 native launcher (uv sync + uvicorn on 8002)
frontend/src/
├── App.tsx Main app shell, WS message dispatch, search
├── stores/
│ ├── chat.ts Zustand - messages, streaming state, plan mode, model
│ ├── projects.ts Zustand - project list, sessions, active selection
│ └── files.ts Zustand - file browser state, directory cache
├── hooks/
│ ├── useWebSocket.ts Auto-reconnect WS with heartbeat
│ ├── usePushNotifications.ts VAPID push subscription management
│ ├── useVisibilityNotify.ts Client-side notification fallback
│ ├── useWakeLock.ts Screen wake lock during streaming
│ └── useSpeechInput.ts Web Speech API voice dictation
├── components/
│ ├── Sidebar.tsx Projects, sessions, search, worker filter, logout;
│ │ active-session (yellow) + background-activity (blue) cues
│ ├── Composer.tsx Input, slash commands, images, voice, auto-approve
│ ├── Message.tsx Markdown + syntax highlight + search highlight
│ ├── ToolBlock.tsx Collapsible tool call display + DiffView
│ ├── DiffView.tsx LCS line diff (add/del/ctx, green/red)
│ ├── FileBrowser.tsx Directory listing + file viewer/editor
│ ├── Terminal.tsx xterm.js PTY terminal + mobile accessory key bar
│ ├── TerminalKeyboard.tsx In-app soft keyboard (hybrid mode)
│ ├── StreamingStatus.tsx Activity bar (thinking/tool/waiting)
│ ├── TypingIndicator.tsx Animated typing dots
│ ├── UserInputPrompt.tsx Multi-question panel with minimize
│ ├── NewProjectBrowser.tsx Modal FS browser for new projects
│ ├── PermissionPrompt.tsx Inline Allow/Deny above composer
│ ├── LockTakeoverModal.tsx "Take over" prompt on session_locked
│ ├── UploadOverlay.tsx Drag-and-drop upload progress overlay
│ ├── AuthBootstrapBanner.tsx Worker-needs-credentials banner
│ └── AuthBootstrapModal.tsx Paste API key / device-code bootstrap flow
├── commands.ts Slash command definitions + matchCommands()
└── public/
└── sw.js Service worker (push, fetch, notification click)
.githooks/ Secret-scanning git hooks (see Git hooks section)
├── pre-commit Scan staged changes
├── pre-push Scan each pushed commit range
├── scan-secrets.sh gitleaks + bundled fallback driver
└── secret-fallback.py regex/entropy scanner used when gitleaks is absent
scripts/install-hooks.sh Enable the hooks (sets core.hooksPath)
Docker
docker/
├── hub.Dockerfile Multi-stage: node (frontend) - uv (deps) - python:3.13-slim
├── worker-claude.Dockerfile Multi-stage: uv (deps) - python:3.13-slim + Node.js + Claude CLI
├── worker-copilot.Dockerfile Multi-stage: uv (deps) - python:3.13-slim
│ (github-copilot-sdk wheel bundles the Copilot CLI
│ binary so no separate Node install)
├── worker-codex.Dockerfile Multi-stage: uv (deps) - python:3.13-slim + OpenAI Codex CLI
└── entrypoint.sh Injects user into /etc/passwd (fixes "I have no name!")
compose.yml- hub + local worker-claude + cloudflared (worker-copilot and worker-codex commented out as examples)workers/worker-claude-compose.yml.example- standalone worker-claude for a remote machine (GHCR image)workers/worker-copilot-compose.yml.example- standalone worker-copilot for a remote machine (GHCR image)workers/worker-codex-compose.yml.example- standalone worker-codex for a remote machine (GHCR image)- These (and
workers.json) are gitignored once filled in; copy the*.example, add your secrets, and run the real file.worker-windowsships no compose file - it runs natively viastart.ps1(copyworker-windows/start.ps1.example).
- These (and
workers.json(gitignored; fromworkers.json.example) - worker registry; one entry per worker:{ "id": "big-worker", "type": "claude", "label": "Big Worker", "url": "ws://192.168.1.25:8002/ws", "secret": "changeme" }typeis free-form (claude,copilot, ...). Frontend renders it as a per-project badge and uses it to pick the right model list for/model.
Volume mounts use the same absolute paths as the host so that Claude /
Copilot session history (~/.claude/projects/*.jsonl,
~/.copilot/session-state/) resolves correctly inside containers.
Frontend build output (frontend-dist/) is volume-mounted into hub at
/app/src/static-mount. Hub prefers this over the baked-in copy, so
npm run build updates the UI without rebuilding the hub image.
WebSocket protocol
Client - Hub - Worker:
ping,prompt {text, images?, auto_approve?, stream?},interruptlist_projects,list_sessions {project_id},session_history {project_id, session_id, limit?, before_uuid?}new_session {project_id, model?},resume_session {project_id, session_id, force?, model?}set_auto_approve {project_id, auto_approve}set_model {model},set_plan_mode {plan_mode}list_models(hub queries each worker on connect; worker-copilot returnsCopilotClient.list_models(), worker-claude falls back to a hub-side default - see hub_DEFAULT_MODELS_BY_TYPE)approve_tool {tool_use_id},deny_tool {tool_use_id, reason?}user_input_response {tool_use_id, answers: string[]}(one per question; legacy{tool_use_id, answer}still accepted)list_directory {project_id, path?},read_file {project_id, path},write_file {project_id, path, content}browse_fs {path?, worker_id?},create_directory {path, worker_id?},create_project {path, worker_id?}terminal_open {project_id, cols?, rows?},terminal_input {data},terminal_resize {cols, rows},terminal_close
Worker - Hub - Client:
pong,text_delta,thinking,tool_call,tool_result,result,system,errorprojectspayload carries{projects, workers}where each worker has{id, label, type, connected, models: [{id, name}]}so the sidebar can render the worker filter and/modelautocomplete without extra round-tripssessions,session_history(withhas_more/oldest_uuid)session_started(withcwd,session_id,resumed,auto_approve,is_busy)session_locked,lock_revokedpermission_request,project_updated,project_createddirectory,file_content,file_written,fs_directoryterminal_ready,terminal_output {data},terminal_closeduser_input_request {tool_use_id, questions: [{question, options}]}push_notify {title, body}(intercepted by hub - Web Push, or out-of-band via HTTP)model_changed {model}(system subtype, shown as info banner in chat)task_event(Monitor/TaskCreate tick events parsed from XML in UserMessage)models(worker-copilot's reply tolist_models; hub-internal)
Hub remaps project IDs:
hub_id = worker_index * 1_000_000 + worker_project_id
Environment variables
| Variable | Purpose |
|---|---|
UID / GID | Container user mapping (match host user) |
PORT | Host bind for hub (default 127.0.0.1:8001) |
CLAUDE_WEB_ENV | prod = fail-closed auth, dev = bypass when CF unset |
CF_ACCESS_TEAM_DOMAIN | e.g. myteam.cloudflareaccess.com |
CF_ACCESS_AUD | Application Audience tag from CF dashboard |
CF_ACCESS_ALLOWED_EMAILS | Comma-separated email allowlist |
WORKER_SECRET | Shared secret for hub <-> worker auth |
WORKERS_CONFIG | Path to workers.json (default /config/workers.json) |
CLAUDE_WEB_DB_PATH | SQLite path (default ~/.claude-web/db.sqlite) |
HUB_URL | Hub URL for worker out-of-band push (e.g. http://hub:8001) |
TUNNEL_TOKEN | Cloudflare Tunnel token (if running cloudflared service) |
Without the CF_ACCESS_* vars, auth is bypassed (dev mode).
Host SSH access (from inside the worker container)
The worker container has SSH access back to the host. Useful for anything
that can't be done from inside the sandbox: docker compose rebuilds,
poking running containers, inspecting host network state, hitting
services bound to host-only ports, etc.
Testing
cd worker-claude && uv run pytest
cd worker-copilot && uv run pytest
cd hub && uv run pytest
License
Apache License 2.0. See NOTICE for attribution.
Permissive: use, modify, redistribute, and embed in commercial products freely. Patent grant included. The only obligation is keeping the copyright + license notice when you redistribute the source.