convez.ai
AgenteDevOps & InfraestruturaAvançado
krzysztofgawrys

Agents Anywhere

krzysztofgawrys/anywhere_agents

Federação multi-máquina autohospedada para agentes de IA coding

Ver no GitHub
InicialPluginScore · de 0 a 100

Federaçã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_agents

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
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

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.

SolutionWhere the hub runsWhere workers runCode transits a third party?Multi-machine federation
CloudCLI CloudVendor SaaSYour box, through their tunnelYesNo
CloudCLI (self-host)Your boxSame box onlyNoNo
Happy CoderVendor "Happy Server" (E2E enc)Your CLI, through their tunnelYes (E2E, but still their infra)No
GitHub Copilot /remote ongithub.comGitHub-hosted or your runnerYesNo
Claude Managed AgentsCloudflareCloudflare microVMsYesNo
NetClodeVendor managedVendor microVMsYesNo
claude-code-webui / similarYour boxSame box onlyNoNo
Agents Anywhere (this repo)Your boxN machines you own, anywhereNoYes

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:

  1. Zero Trust -> Access -> Service Auth -> Service Tokens. Create one (e.g. worker-remote-copilot). Copy Client ID + Secret (secret shown once).

  2. Zero Trust -> Access -> Applications -> Add an application -> Self-hosted. Application domain hub.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).

  3. 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

AspectOutbound (LAN/Tailscale)Outbound (CF Tunnel per worker)Inbound (reverse)
Worker needs ingress?Yes (via VPN/mesh)NoNo
Vendor in data path of worker?No (or Tailscale coordination only)Yes (CF)No
Per-worker public hostname?NoYesNo
Setup per workerTailscale upcloudflared + DNSEnv vars
LatencyDirect mesh+50-100ms hopDirect TCP
Code changes requiredNoneNoneNone (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 - Anthropic claude-agent-sdk
    • worker-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 on EXCEL_PORT, default 3847). 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 to frontend-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 *.example templates. 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) for worker-claude, worker -> GitHub Copilot API for worker-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_AUD and an email allowlist). Fail-closed in CLAUDE_WEB_ENV=prod if 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 in X-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 *.example templates 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_locked with the current holder's device label and can either back off or take over (sends lock_revoked to the previous owner, who is flipped to read-only).
  • Permission broker: tool calls surface as permission_request blocks for explicit Allow / Deny unless auto_approve is set per project or armed per prompt. User's ~/.claude/settings.json permissions.allow patterns 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 via CopilotClient.list_models(), Claude from a hub-side default that you can override). /model default clears 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 cwd doesn'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_file WS 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_approve flag (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_request block above the composer

Locks

  • Lock is per session_id, not per project. Held by the WS connection that most recently called new_session / resume_session.
  • Second client resuming the same session gets session_locked with the current holder's device label. Modal offers "Take over" (force: true).
  • Takeover sends lock_revoked to 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_notify to hub/api/internal/push (authenticated with X-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): useVisibilityNotify fallback 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 any and maskable)
  • 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, structlog for 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.sh points core.hooksPath at .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.toml extends 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 *.example templates 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-verify bypasses 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-windows ships no compose file - it runs natively via start.ps1 (copy worker-windows/start.ps1.example).
  • workers.json (gitignored; from workers.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"
    }
    
    type is 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?}, interrupt
  • list_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 returns CopilotClient.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, error
  • projects payload carries {projects, workers} where each worker has {id, label, type, connected, models: [{id, name}]} so the sidebar can render the worker filter and /model autocomplete without extra round-trips
  • sessions, session_history (with has_more / oldest_uuid)
  • session_started (with cwd, session_id, resumed, auto_approve, is_busy)
  • session_locked, lock_revoked
  • permission_request, project_updated, project_created
  • directory, file_content, file_written, fs_directory
  • terminal_ready, terminal_output {data}, terminal_closed
  • user_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 to list_models; hub-internal)

Hub remaps project IDs: hub_id = worker_index * 1_000_000 + worker_project_id


Environment variables

VariablePurpose
UID / GIDContainer user mapping (match host user)
PORTHost bind for hub (default 127.0.0.1:8001)
CLAUDE_WEB_ENVprod = fail-closed auth, dev = bypass when CF unset
CF_ACCESS_TEAM_DOMAINe.g. myteam.cloudflareaccess.com
CF_ACCESS_AUDApplication Audience tag from CF dashboard
CF_ACCESS_ALLOWED_EMAILSComma-separated email allowlist
WORKER_SECRETShared secret for hub <-> worker auth
WORKERS_CONFIGPath to workers.json (default /config/workers.json)
CLAUDE_WEB_DB_PATHSQLite path (default ~/.claude-web/db.sqlite)
HUB_URLHub URL for worker out-of-band push (e.g. http://hub:8001)
TUNNEL_TOKENCloudflare 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.

Ver o original no GitHub

Bom para

Relacionados