agentor CLAUDE.md

Agent Orchestrator (Agentor)

Docker orchestrator that spawns isolated AI coding agent workers, each in its own container with terminal access via a web dashboard. All agent CLIs (Claude, Codex, Gemini) are pre-installed in a single unified worker image. Includes a modular app system (Chromium, SOCKS5 proxy, VS Code Tunnel, SSH server), a unified Traefik reverse proxy for both TCP port mappings and HTTP/HTTPS/TCP domain routing, a VS Code editor (code-server), live per-worker resource monitoring (CPU/RAM/disk/network via the Docker API), worker export/import (portable .tar bundles incl. an optional docker export of the filesystem), and an automatic update mechanism for production deployments.

Architecture

Worker (curl)            <--HTTP/JSON--> Orchestrator (/api/worker-self/*, identified by Docker source IP)
Browser (Vue 3/Nuxt UI) <--HTTP/JSON--> Orchestrator (Nuxt 3/Nitro) <--dockerode exec--> Worker (tmux/agent)
Browser (xterm.js)       <--WebSocket--> Nitro (crossws)             <--docker stream--> Worker (tmux)
Browser (noVNC iframe)   <--HTTP/WS----> Nitro (proxy)               <--HTTP/WS-------> Worker (websockify <--> x11vnc <--> Xvfb)
Browser (code-server)    <--HTTP/WS----> Nitro (proxy)               <--HTTP/WS-------> Worker (code-server on port 8443)
Local VS Code            <--tunnel-----> Microsoft Relay              <--tunnel--------> Worker (vscode app → code tunnel)
Local ssh client         <--TCP--------> Traefik (ext :22xxx)         <--TCP-----------> Worker (ssh app → sshd :22)
Orchestrator             <--docker exec-> apps/*/manage.sh (start/stop/list app instances in worker)
Orchestrator (TraefikManager) <--dockerode--> Traefik container (unified reverse proxy: port mappings + domain routing, TLS)

Three managed containers:

• Orchestrator: Nuxt 3 app (SPA mode) with Nitro server, serving dashboard + managing workers and the Traefik container via Docker socket
• Traefik: Unified reverse proxy container handling both TCP port mappings (one dedicated entrypoint per mapping) and HTTP/HTTPS/TCP domain routing with Let's Encrypt or self-signed TLS. Managed by the orchestrator — created when any port/domain mapping or dashboard subdomain is configured, removed when empty. Port mappings work without BASE_DOMAINS; domain mappings require it. The reconcile is misconfig-safe: a mapping whose host port can't be bound (occupied, or the reserved 80/443 while domain routing is active) is rejected with 409 and rolled back out of the store, and a failed (re)create rolls Traefik back to its last-good config — so a bad mapping never wedges Traefik or locks the operator out of the dashboard (see @docs/networking.md → Reconcile Robustness).
• Workers: Single unified Docker image (agentor-worker, Ubuntu 24.04) with all agent CLIs pre-installed, running in tmux, plus an integrated display stack (Xvfb + fluxbox + x11vnc + noVNC on port 6080), code-server (VS Code on port 8443), Chromium, and apps — Chromium with CDP, SOCKS5 proxy, VS Code Tunnel (native VS Code client via Microsoft relay), and OpenSSH server (port 22). Each worker is a single container with all agents available. Three persistent volumes per worker: workspace (/workspace), agent config data (/home/agent/.agent-data — symlinked to ~/.claude, ~/.gemini, ~/.codex, ~/.agents, ~/.claude.json), and optionally DinD (/var/lib/docker). Worker identity is a stable UUID id (server-minted UUID v4 — the WorkerStore key and the agentor.id label, stable across rebuild/unarchive); the Docker container id (containerId) changes on every rebuild and is resolved from id on demand. The derived containerName = agentor-worker-<id> is the Docker container name, the prefix for per-worker volume names, and the DNS name Traefik routes to. No custom Hostname is set, so the in-container shell prompt shows the docker short container id, not the UUID. The image reference is imageName (+ imageId). A separate editable displayName is the user-facing label shown in the dashboard (free-form, not required to be unique). All worker settings are editable post-creation via PATCH /api/containers/:id from the Worker Settings modal (the Settings pencil / card title): displayName is applied to the running worker immediately (no rebuild needed), while environmentId, repos, mounts, and initScript are baked into the container at create time, so editing them updates the stored config and flags the worker pendingRebuild until the next rebuild (which re-resolves from the stored config and clears the flag). Environment-specific settings (CPU/memory, network, Docker, capabilities, instructions, setup script, env vars) are edited in the Environments modal, not the worker modal. The persisted WorkerRecord (workers.json) is minimal: it stores only what cannot be discovered from Docker at runtime — the worker's own settings (displayName, status, repos, mounts, initScript, pendingRebuild), foreign keys (userId, environmentId), and base fields (id/createdAt/updatedAt/archivedAt). Everything describing the live Docker container — containerId, containerName (agentor-worker-<id>), imageName, imageId, and the running/stopped state — is not persisted; it is resolved at runtime in ContainerManager.sync() by matching the agentor.id label (and, for archived workers with no container, derived from the id). The one image-related exception is importedImage: a worker restored from an export that captured the source filesystem persists the per-worker agentor-import-<id> image reference (a config choice, not a discoverable label) so the captured rootfs survives rebuild/unarchive; it is removed on permanent delete. The runtime ContainerInfo returned by the API is the record merged with that discovered Docker data, so it still carries those fields. The environment config and the git identity (name/email) are likewise resolved live at build time from the EnvironmentStore / the owning user, never copied onto the worker. There is no per-worker resource-limit override; limits come from the environment. Resource metrics are per-worker only (no host/system metrics — those are OS/runtime-dependent), served by an in-memory ResourceMonitor singleton entirely via the Docker API: cpu/mem/net from container.stats, disk from the writable layer (SizeRw) + a du of the worker's volumes (GET /api/worker-metrics, POST /api/worker-metrics/refresh, GET /api/containers/:id/metrics). No host bind mounts needed. Worker export/import (GET /api/containers/:id/export, POST /api/containers/import) bundles the worker's config + environment + mappings + workspace/agent volumes (+ optional docker export rootfs) into a portable .tar and restores it as a fresh worker. See @docs/production.md.