{"id":50271248,"url":"https://github.com/openclaw/crabfleet","last_synced_at":"2026-05-27T18:00:46.613Z","repository":{"id":358394515,"uuid":"1241076174","full_name":"openclaw/crabfleet","owner":"openclaw","description":"Mission control for agent runs.","archived":false,"fork":false,"pushed_at":"2026-05-24T03:10:14.000Z","size":487,"stargazers_count":16,"open_issues_count":0,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-24T03:25:57.267Z","etag":null,"topics":["agent","fleet","management"],"latest_commit_sha":null,"homepage":"http://docs.crabfleet.ai","language":"TypeScript","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/openclaw.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"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},"funding":{"github":["moltbot"]}},"created_at":"2026-05-16T23:41:20.000Z","updated_at":"2026-05-24T03:10:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/openclaw/crabfleet","commit_stats":null,"previous_names":["openclaw/crabyard","openclaw/crabfleet"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/openclaw/crabfleet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fcrabfleet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fcrabfleet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fcrabfleet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fcrabfleet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openclaw","download_url":"https://codeload.github.com/openclaw/crabfleet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openclaw%2Fcrabfleet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33577636,"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-27T02:00:06.184Z","response_time":53,"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":["agent","fleet","management"],"created_at":"2026-05-27T18:00:26.532Z","updated_at":"2026-05-27T18:00:46.565Z","avatar_url":"https://github.com/openclaw.png","language":"TypeScript","funding_links":["https://github.com/sponsors/moltbot"],"categories":[],"sub_categories":[],"readme":"# Crabfleet\n\n**Mission control for Agent runs.**\n\nCrabfleet gives OpenClaw maintainers a fleet dashboard where every Codex crabbox is visible by operator, repo, terminal, and WebVNC state.\n\n## What It Does\n\n- **Fleet-first workflow.** Create repo-ready Crabboxes from the app, SSH, or the Go CLI and see org Codex instances grouped by person.\n- **Board-based workflow.** Create cards from prompts, GitHub issues, or PRs. Track them through Todo, Running, Human Review, and Done lanes.\n- **Issue/PR lookup.** Type `#123` in search to preview matching GitHub issues or PRs across enabled OpenClaw repos and create a card from the match.\n- **Codex run control.** Start durable run attempts, track heartbeats, watch the Ghostty WASM session grid, and take over only when the selected runtime advertises that capability.\n- **Interactive Crabboxes.** Start a standalone Codex CLI workspace for manual cloud work and attach it in the same fullscreen Ghostty grid or WebVNC.\n- **Worker-owned sandbox credentials.** Built-in Cloudflare Sandbox sessions get placeholder env credentials; Worker-controlled outbound routing injects model and GitHub credentials only for approved upstream requests.\n- **Diff previews.** Card tiles show changed files and totals; the run drawer shows a compact Codiff-style patch view.\n- **Multi-runtime policy.** Auto-select between the Container and Crabbox adapter surfaces based on card overrides, repo workflow defaults, and task requirements.\n- **Allowlist controls.** Restrict access to OpenClaw org members and specific repos through admin-managed allowlists.\n- **Session logs.** D1-backed card/run event history with a 30-day product retention setting.\n- **Repo workflow config.** Owners can evaluate `CRABBOX.md` per repo and use it for runtime and merge defaults.\n\n## Architecture\n\n- **Cloudflare Workers** for the app, API, auth, GitHub lookup, and docs routes.\n- **D1 + Kysely** for typed persistence: users, sessions, allowlists, repos, cards, events, run attempts, interactive sessions, diffs, and repo workflow evaluations.\n- **Ghostty WebAssembly** for the fullscreen attach grid and run log replay.\n- **Cloudflare Sandbox containers** for standalone interactive Codex CLI workspaces with live PTY attach.\n- **Runtime adapter descriptors** for Container and Crabbox selection, capability display, interactive provision handoff, and guarded takeover.\n- **Provision endpoint** at `/api/provision/interactive` that can use the built-in Sandbox backend or delegate to a generic runtime adapter or ClawFleet.\n- **R2 session archives** for crabbox event NDJSON, transcripts, and summaries.\n- **GitHub API** for OAuth, org/team membership, and issue/PR previews across enabled repos.\n\nAutonomous card execution, Crabbox VNC transport, Durable Object fanout, and merge automation are adapter targets, not faked in the current Worker.\n\n## Quick Start\n\n### 1. Sign In\n\nUse GitHub OAuth for normal browser access, or link an SSH key from the terminal:\n\n```bash\nssh link@crabd.sh\n```\n\n`CRABBOX_BOOTSTRAP_TOKEN` is only a break-glass recovery path for owners.\n\n### 2. Configure Access\n\nAdd users/teams to the allowlist and enable repos:\n\n- Navigate to Admin panel\n- Add GitHub users (`@login`) or teams (`@org/team`)\n- Assign roles: owner, maintainer, or viewer\n- Add allowed repos (`owner/repo`)\n\n### 3. Create Cards\n\n- **From prompt:** New card → enter prompt, select repo; title is optional\n- **From issue:** Search GitHub issues → create card\n- **From PR:** Search GitHub PRs → create card for review/fix\n\n### 4. Watch Runs\n\n- Running cards show D1 event logs and heartbeat state\n- Click \"Attach\" to open the fullscreen Ghostty WASM session grid\n- Click \"Take over\" only when the active run advertises takeover support\n- Click \"Watch\" for read-only stream\n\n### 5. Start Crabboxes\n\n- Click \"New crabbox\" to request a standalone Codex CLI workspace\n- Default runtime is Cloudflare Sandbox; choose Crabbox only when a VNC/desktop adapter is configured\n- Without `CRABBOX_INTERACTIVE_PROVISION_URL`, sessions are stored as `pending_adapter` and still visible in the grid\n- Install or build the Go CLI, then run `crabfleet new --repo openclaw/crabfleet \"fix the failing check\"`\n\n## Features\n\n### Board Management\n\n- Kanban-style lanes: Todo, Running, Human Review, Done\n- Card filtering: all, mine, live\n- Search cards by title, repo, or ID\n- Real-time updates via WebSockets\n\n### Card Policies\n\n- **Runtime:** `auto`, `container`, `crabbox`\n- **Merge policy:** repo default, `open_pr`, `merge_when_green`, `fix_until_green_and_merge`\n- **Source types:** Prompt, Issue, PR\n\nRepo defaults can come from a `CRABBOX.md` file:\n\n```yaml\n---\nruntime:\n  default: auto\nmerge:\n  default_policy: open_pr\n---\n```\n\n`stall_ms`, `cap`, `prompt_prefix`, and the Markdown body are parsed/stored for future policy work, but only runtime and merge defaults are effective today.\n\n### Admin Controls\n\n- User and team allowlists with role-based access\n- Repo allowlists\n- Manual `CRABBOX.md` evaluation with status/error visibility\n- Concurrent run caps (default: 20)\n- Log retention (14, 30, 60 days)\n- Direct merge permissions (guarded, maintainers, disabled)\n\n### Auth\n\n- GitHub OAuth for org members\n- Bootstrap token for admin setup and recovery\n- Short-lived sessions with automatic refresh\n- Role-based access control (owner, maintainer, viewer)\n\n## Deployment\n\n### Prerequisites\n\n- Cloudflare account\n- `crabfleet.ai` route in Cloudflare (`crabfleet.ai` redirects here)\n- GitHub OAuth app (optional but recommended)\n- Bootstrap token secret\n\n### Deploy\n\nPushes to `main` run `.github/workflows/deploy-worker.yml`, which checks, tests, builds,\napplies remote D1 migrations, and deploys the Worker. Configure the repository secret\n`CLOUDFLARE_API_TOKEN` with permissions for Workers deploys and D1 migrations.\n`crabfleet.ai` and `crabd.sh` DNS/route convergence is handled by\n`scripts/ensure-cloudflare-domains.mjs`; set `CLOUDFLARE_DNS_API_TOKEN` when CI should\nmanage those records. Without that DNS-scoped token, CI skips domain convergence and\ndeploys to the already configured route.\n\nManual deploy is still available:\n\n```bash\n# Build assets\npnpm build\n\n# Apply migrations\nwrangler d1 migrations apply DB --remote\n\n# Deploy to Cloudflare\nwrangler deploy\n```\n\n### Environment Variables\n\nConfigure these in Cloudflare Workers dashboard. `CRABBOX_*` names are the runtime/crabbox adapter contract; `CRABFLEET_*` names are for the public CLI and SSH gateway. The `SESSION_LOGS` R2 binding points at the `crabfleet-session-logs` bucket and stores crabbox event archives.\n\nThe Crabbox namespace cutover intentionally has no old-name compatibility. Existing browser sessions expire, linked SSH keys must be relinked with `ssh link@crabd.sh`, and in-flight interactive workspaces should be recreated.\n\n- `CRABBOX_BOOTSTRAP_TOKEN` – Optional owner break-glass token for setup/recovery\n- `GITHUB_CLIENT_ID` – GitHub OAuth app client ID (optional)\n- `GITHUB_CLIENT_SECRET` – GitHub OAuth app secret (optional)\n- `GITHUB_ORG` – GitHub org for membership check (default: `openclaw`)\n- `GITHUB_TOKEN` – GitHub token for all enabled repo issue/PR previews and private repo `CRABBOX.md` refreshes (optional; public/default repo paths work without it)\n- `CRABBOX_TOKEN_ENCRYPTION_KEY` – Optional encryption key for per-session GitHub OAuth tokens; defaults to `GITHUB_CLIENT_SECRET`\n- `CRABBOX_INTERACTIVE_PROVISION_URL` – Optional adapter endpoint for standalone Codex CLI workspaces\n- `CRABBOX_INTERACTIVE_PROVISION_TOKEN` – Optional bearer token sent to the interactive provision endpoint; required when backend URLs below are configured\n- `CRABBOX_RUNTIME_PROVISION_URL` – Optional generic backend URL used by `/api/provision/interactive`\n- `CRABBOX_RUNTIME_PROVISION_TOKEN` – Optional bearer token sent to the generic runtime backend\n- `CRABBOX_CLOUDFLARE_RUNNER_URL` – Optional Crabbox Cloudflare container runner URL used by `/api/provision/interactive`\n- `CRABBOX_CLOUDFLARE_RUNNER_TOKEN` – Optional bearer token sent to the Cloudflare runner\n- `CRABBOX_CLOUDFLARE_RUNNER_INSTANCE_TYPE` – Optional runner instance type, default `standard-4`\n- `CRABBOX_CLOUDFLARE_RUNNER_WORKDIR` – Optional base workdir for provisioned sandboxes, default `/workspace/crabbox`\n- `CRABBOX_CLOUDFLARE_RUNNER_TTL_SECONDS` – Optional sandbox TTL, default `14400`\n- `CRABBOX_CLOUDFLARE_RUNNER_IDLE_SECONDS` – Optional idle timeout, default `1800`\n- `CRABBOX_PTY_BRIDGE_URL` – Optional WebSocket PTY bridge URL/template for live Ghostty attach; supports `{id}`, `{leaseId}`, `{repo}`, `{branch}`, and `{runtime}`\n- `CRABBOX_PTY_BRIDGE_TOKEN` – Optional bearer token sent from Crabfleet to the PTY bridge\n- `CRABBOX_CLAWFLEET_URL` – Optional ClawFleet dashboard/API URL used by `/api/provision/interactive` for `crabbox` sessions\n- `CRABBOX_CLAWFLEET_TOKEN` – Optional bearer token sent to ClawFleet\n- `CRABBOX_CLAWFLEET_PUBLIC_URL` – Optional public ClawFleet URL used when building attach/VNC links\n- `CRABBOX_OPENCLAW_TOKEN` – Internal bearer token for OpenClaw/Discord service crabbox creation\n- `CRABFLEET_SSH_GATEWAY_TOKEN` / `CRABBOX_SSH_GATEWAY_TOKEN` – Shared bearer token for the Go SSH gateway internal API\n- `CRABFLEET_LOCAL_SANDBOX_BACKUPS` – Optional Cloudflare Sandbox checkpoint mode override; defaults to R2 binding uploads, set `0` for SDK presigned R2 uploads\n- `OPENAI_API_KEY` – Required for built-in Cloudflare Sandbox Codex CLI sessions; injected by the Worker outbound path for Cloudflare Sandbox requests\n\n### Verify Deployment\n\n```bash\ncurl -I https://crabfleet.ai/healthz\n# Should return: 200 OK\n\ncurl https://crabfleet.ai/docs/spec\n# Should return: HTML spec document\n```\n\n## Development\n\n### Setup\n\n```bash\n# Install dependencies\npnpm install\n\n# Build assets\npnpm build\n\n# Run type checks\npnpm check\n\n# Run linter\npnpm lint\n\n# Format code\npnpm format\n```\n\n### Test Stack\n\n- `tsgo --noEmit` through `pnpm build`\n- `oxlint` for linting\n- `oxfmt --check` for formatting\n- SQLite migration smoke checks for D1 schema compatibility\n- `codex-review` before feature commits\n- Browser/live smoke checks after deploy\n\n### Local Development\n\n```bash\n# Start local dev server with D1\nwrangler dev\n\n# Apply migrations locally\nwrangler d1 migrations apply DB --local\n```\n\n### SSH Gateway\n\nThe Worker exposes an internal SSH onboarding API guarded by `CRABFLEET_SSH_GATEWAY_TOKEN` or `CRABBOX_SSH_GATEWAY_TOKEN`.\nRun the Go gateway next to a host that can accept raw SSH:\n\n```bash\nCRABFLEET_API_URL=https://crabfleet.ai \\\nCRABFLEET_SSH_GATEWAY_TOKEN=... \\\nCRABFLEET_SSH_HOST_KEY=/var/lib/crabfleet/ssh_host_ed25519_key \\\nCRABFLEET_SSH_ADDR=:2222 \\\ngo run ./cmd/crabbox-ssh-gateway\n```\n\nUnknown public keys get a short GitHub OAuth link through `ssh link@host`. Linked keys can\nrun `whoami`, `list`, `new`, and `attach SESSION_ID`; `new` creates an interactive Codex\nsession and attaches.\n\nProduction should expose the gateway at `crabd.sh` as a DNS-only `A` record.\nUse `ssh link@crabd.sh` once to connect a GitHub-backed SSH key, then run\n`ssh crabd.sh whoami` or `ssh crabd.sh list`.\n\n### Go CLI\n\nThe `crabfleet` CLI is written in Go with Kong and delegates to SSH by default. API mode is available for service contexts with `CRABFLEET_SSH_GATEWAY_TOKEN` and `CRABFLEET_SSH_FINGERPRINT`.\n\n```bash\nbrew tap openclaw/tap\nbrew install crabfleet\n\ngo run ./cmd/crabfleet login\ngo run ./cmd/crabfleet list\ngo run ./cmd/crabfleet new --repo openclaw/crabfleet \"start on the release checklist\"\ngo run ./cmd/crabfleet attach \u003csession-id\u003e\ngo run ./cmd/crabfleet vnc --open \u003csession-id\u003e\n```\n\n### CLI Release\n\nTagged releases publish `crabfleet` with GoReleaser and dispatch the OpenClaw Homebrew tap updater:\n\n```bash\ngit tag v0.1.0\ngit push origin v0.1.0\n```\n\nThe release workflow builds macOS, Linux, and Windows archives, then updates `openclaw/homebrew-tap` through `update-formula.yml`.\n\n### OpenClaw / Discord Crabbox Hook\n\nOpenClaw can create repo-ready crabboxes for Discord-triggered work through the internal service endpoint:\n\n```bash\ncurl -fsS https://crabfleet.ai/api/openclaw/crabboxes \\\n  -H \"authorization: Bearer $CRABBOX_OPENCLAW_TOKEN\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\"owner\":\"@steipete\",\"repo\":\"openclaw/crabfleet\",\"prompt\":\"prep the meeting follow-up\"}'\n```\n\nThe created crabbox appears in the fleet grid under the requested owner. Provisioning still flows through the configured Crabbox/ClawFleet adapter, so VNC and terminal URLs come from the runtime backend.\n\n### Project Structure\n\n```\ncrabfleet/\n├── src/\n│   ├── index.ts          # Worker entry point, API routes, auth handlers\n│   ├── app.html          # Single-page app shell and styles\n│   ├── app/              # Preact app modules\n│   ├── generated.ts      # Build-time generated assets\n├── migrations/           # D1 database migrations\n├── scripts/              # Build scripts\n│   └── generate-assets.mjs\n├── vite.config.mjs       # Preact/Vite app bundle config\n├── docs/                 # Documentation (GitHub Pages)\n│   ├── CNAME             # docs.crabfleet.ai custom domain\n│   └── spec.md           # Product spec\n└── wrangler.jsonc       # Cloudflare Worker config\n```\n\n## Documentation\n\nFull documentation available at [docs.crabfleet.ai](https://docs.crabfleet.ai):\n\n- [Quickstart](https://docs.crabfleet.ai/quickstart) – Get started in 5 minutes\n- [Architecture](https://docs.crabfleet.ai/architecture) – System design and data model\n- [Cards](https://docs.crabfleet.ai/cards) – Card lifecycle and policies\n- [Runs](https://docs.crabfleet.ai/runs) – Runtime selection and execution\n- [Admin](https://docs.crabfleet.ai/admin) – Access control and policies\n- [API](https://docs.crabfleet.ai/api) – REST and WebSocket APIs\n- [Spec](https://docs.crabfleet.ai/spec) – Complete product specification\n\n## Security\n\n- All state-changing operations require authentication\n- Repo operations require allowlist membership\n- Direct merge requires maintainer role and policy approval\n- Runtime tokens are scoped and short-lived\n- Secrets never logged or stored in D1/R2\n- Audit events for all admin and merge operations\n\n## Status\n\nActive development. See [CHANGELOG.md](CHANGELOG.md) for recent updates.\n\nCurrent phase: MVP deployed with auth, board UI, admin controls, card management, Kysely-backed D1 persistence, durable run attempts, repo workflow evaluation, card diffs, Ghostty WASM terminal grid, R2 session log archives, authenticated PTY WebSocket proxying, and first-party Cloudflare Sandbox Codex CLI sessions.\n\nNext: bind autonomous card execution and merge automation to the same runtime layer.\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n## Not Affiliated\n\nCrabfleet is an OpenClaw project, not affiliated with Cloudflare, GitHub, or Anthropic.\n\n## Contributing\n\nThis is currently an internal OpenClaw tool. External contributions are not accepted at this time.\n\n## Support\n\nFor OpenClaw org members: use #crabfleet in Discord or open an issue in the private repo.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenclaw%2Fcrabfleet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenclaw%2Fcrabfleet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenclaw%2Fcrabfleet/lists"}