OpenStaff

OpenStaff is an open-source foundation for an always-on staff of AI teammates. Humans and named bots share iMessage-style rooms, bots get separately scheduled turns, and consequential tools can pause for approval without losing the conversation.

Quick start

Requirements: Node 22.22.3 or newer in the Node 22 line, and Corepack. The Composio SDK declares this minimum patch version.

pnpm i
cp .env.example .env

Set one model key (XAI_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENCODE_API_KEY, or AI_GATEWAY_API_KEY) in .env, then run:

pnpm dev

Open http://localhost:3000. The web app proxies API and WebSocket traffic to the server on port 8787.

If no provider key is configured, the app still boots and persists turns. A direct bot turn fails gracefully with a system message explaining which provider key is missing.

The default computer driver is local. It can execute commands with the server user's permissions: use Docker for command isolation. The shell's path jail protects file tools, not arbitrary shell programs. Do not expose this single-workspace development app to untrusted users.

Landing page

The static OpenStaff marketing site lives in apps/landing. Run it locally with pnpm dev:landing. pnpm --filter landing build outputs the production site to apps/landing/dist.

Browser setup

From the repository root, install Chromium into the mutable data directory:

export PLAYWRIGHT_BROWSERS_PATH="$PWD/data/playwright"
pnpm --filter server exec playwright install chromium
pnpm dev

Keep that environment variable set when running the server or save its absolute value in .env. Linux may also require Playwright's install --with-deps chromium command. If Chromium cannot launch, browser tools return an actionable error and the turn continues.

Each turn owns a page in one persistent browser context. Approval pauses retain the page until the turn resumes; completed/cancelled turns close it. Snapshots provide ARIA refs for click/type, and browser clicks and typing require approval under writes. With Local, E2B, Daytona, Freestyle, or Vercel Sandbox, the browser stays in the server process and its profile lives at DATA_DIR/browser-profile. Docker uses the headed browser in its desktop container over CDP. Screenshots for every provider remain in DATA_DIR/screens.

On the Docker provider, bots can also see and operate the full shared desktop with native-resolution screenshots, pixel clicks and drags, typing, key chords, scrolling, and window switching. These computer tools share the browser's human-takeover lease and display mutex. Bots prefer structured browser snapshots when available because they are cheaper and more reliable, using desktop vision for native apps, canvases, dialogs, and browser fallbacks.

Choose a Computer

Every bot shares one always-on Computer. Settings → Computer selects Local, Docker, E2B, Daytona, Freestyle, or Vercel Sandbox, shows its capabilities, and stores vendor credentials encrypted at the workspace scope. COMPUTER_DRIVER is an operator override that locks Settings. Local uses the server filesystem and is appropriate only for trusted deployments; Docker and remote providers isolate commands from the server host. See Computer providers.

E2B is also a full Computer: a hosted Firecracker microVM with a persistent 1280×800 desktop, live takeover stream, native computer-use input, and a headed Chromium controlled over CDP. Set E2B_DESKTOP_TEMPLATE to choose a desktop template, or set E2B_DESKTOP=0 for the legacy shell-only mode. E2B keeps filesystem and memory indefinitely while paused; Hobby permits 1 hour and Pro 24 hours of continuous runtime before a pause and resume resets the clock. Default desktop compute is approximately $0.17 per running hour. Returning or expiring takeover rotates the whole stream, so viewer sessions reconnect as well as the old controller URL becoming invalid.

The Docker Computer persists both /workspace in superworkers-data and /home/worker in superworkers-home. Home contains the Chromium profile, cookies, logins, dotfiles, shell history, and user-level tools. Container restarts and image upgrades preserve both volumes; system packages, the writable root filesystem, and running processes do not persist. Put idempotent user-level installation scripts in /home/worker/setup.d. Reset home state with docker volume rm superworkers-home only after stopping the stack and confirming that saved browser sessions and home files may be deleted.

The desktop needs at least 2 vCPU, 4 GiB memory, and 1 GiB shared memory. At every start the container probes whether Chromium's own sandbox works under the supplied seccomp profile with all capabilities dropped. When it does, Chromium runs sandboxed; when it does not (Docker Desktop on arm64 fails the zygote's sys_chroot check, for example) Chromium starts with --no-sandbox and logs a warning, so the stack still boots. The container boundary (non-root, cap_drop: ALL, seccomp, no-new-privileges) applies either way. Set COMPUTER_CHROME_NO_SANDBOX=0 to require the sandbox and fail loudly instead, or 1 to skip the probe and always disable it.

Production

The canonical self-host path is a single Linux VM with Docker Compose, a durable volume, and Caddy HTTPS. Run pnpm run doctor after configuring .env, back up before upgrades, and use the explicit Docker overlay only when selecting Docker as the Computer provider. See self-hosting, backup and restore, and releases.

This is the beginning of the README. Read the rest at the original. Read the full README ↗