⌁Crabyard.ai

Crabyard.ai Spec

Status: draft

Crabyard.ai is a Cloudflare-native control plane for running Codex sessions in cloud workspaces. It gives OpenClaw maintainers a Linear-like board where each card represents an intent, a live run, and its durable history.

Decisions

Goals

Non-Goals

Product Model

Card is the primary object.

Card source types:

Each card owns:

Cards may produce:

Card policy fields:

Card source rules:

Board

Design: Linear-like, minimal, dense, subtle crustacean branding.

Default visible lanes:

Default hidden lanes:

Lane means workflow state. Automerge is not a lane.

Automerge is a card policy:

The UI shows merge policy as a chip on the card. Subtle claw/check icon when armed.

Card rendering:

Primary views:

Top bar:

Branding:

Runtime Modes

Default runtime:

Runtime mode choices:

Manual Codex preference:

Autonomous Codex preference:

Runtime selection:

  1. If card requires VNC, choose Crabbox.
  2. If card is manual CLI takeover first, prefer Crabbox unless container PTY is explicitly allowed.
  3. If repo/job fits configured container limits, choose Cloudflare Container.
  4. If validation requires unsupported system dependencies, choose Crabbox.
  5. If org cap is reached, leave card queued.

Cloudflare Container expectations:

Crabbox expectations:

Attach Semantics

Attach modes:

When a user takes over:

VNC

VNC is available only for Crabbox-backed leases.

VNC is post-MVP unless Crabbox already exposes it for a lease.

Expected flow:

Auth

Login:

Access gate:

Admin UI:

Repo gate:

Admin roles:

Admin UI sections:

Secrets

Secrets are per org.

Secret types:

Storage:

Policy:

Secret delivery:

Merge Authority

Crabyard can merge directly when policy allows.

Merge paths:

Direct merge guardrails:

Direct merge sequence:

  1. Refresh PR state from GitHub.
  2. Verify repo/user/policy allow direct merge.
  3. Verify exact head SHA matches reviewed/validated SHA.
  4. Verify required checks and required review state.
  5. Verify branch update/merge queue requirements.
  6. Perform merge through GitHub App credentials.
  7. Record audit event with actor, PR, SHA, checks snapshot, and merge commit.
  8. Move card to Done.

ClawSweeper handoff:

Crabyard direct merge should stay conservative. If any guardrail is unknown, block direct merge and offer ClawSweeper handoff or human review.

Logs And Retention

Retention: 30 days by default.

Persist:

Storage:

After 30 days:

Log streams:

Replay requirements:

Resilience

Default org cap:

Caps are configurable:

Stall handling:

Run lifecycle:

Retry policy:

Heartbeat sources:

Workflow File

Crabyard may support repo-owned workflow config.

Recommended name: CRABYARD.md.

Purpose:

It is optional for MVP. Dashboard/org settings provide defaults.

Example:

---
runtime:
  default: auto
  allow:
    - container
    - crabbox
validation:
  required:
    - pnpm check
    - pnpm test
merge:
  default_policy: open_pr
  allow_direct_merge: false
codex:
  mode: cli
  model: gpt-5.5
  reasoning_effort: high
---

You are working in this repository for Crabyard.
Read AGENTS.md first.
Keep changes scoped.
Open a PR unless the card explicitly allows direct merge.

Resolution order:

  1. Card explicit settings
  2. Repo CRABYARD.md
  3. Org defaults
  4. Product defaults

Invalid CRABYARD.md:

Tech Stack

Language/tooling:

Frontend/app:

Cloudflare:

Runtime integrations:

Package Layout

apps/
  web/              TanStack Start app
  control/          Worker API, Durable Objects, Queues
packages/
  schema/           Valibot schemas and inferred types
  ui/               Crabyard UI components
  github/           GitHub adapters, issue/PR search
  crabbox/          Crabbox client
  codex-app-server/ JSON-RPC client and generated protocol types
  workflow/         CRABYARD.md parser/evaluator

Rule:

Data Model

Core D1 tables:

Durable Object state:

R2 layout:

orgs/{org}/runs/{run_id}/events.ndjson
orgs/{org}/runs/{run_id}/terminal.raw
orgs/{org}/runs/{run_id}/terminal.ndjson
orgs/{org}/runs/{run_id}/app-server.ndjson
orgs/{org}/runs/{run_id}/summary.json
orgs/{org}/runs/{run_id}/artifacts/{name}

API Surface

Representative endpoints:

WebSockets:

Service bindings:

Run Flow

Freeform prompt:

  1. User creates card with prompt and repo.
  2. Card enters Todo.
  3. Scheduler claims card when capacity exists.
  4. Dispatcher chooses runtime.
  5. Runtime checks out repo.
  6. Codex starts in CLI PTY or app-server mode.
  7. RunDO streams events/logs to browser and R2.
  8. Codex creates branch/PR or returns result.
  9. Card moves to Human Review, Merging, Done, or Rework.

Issue:

  1. User picks issue.
  2. Prompt is built from issue title/body/comments plus repo policy.
  3. Codex works from new branch.
  4. Result is PR or blocker.

PR:

  1. User picks PR.
  2. Runtime checks out PR head.
  3. Codex reviews/fixes/rebases according to card policy.
  4. Crabyard direct merge or ClawSweeper handoff handles merge.

Manual takeover:

  1. User attaches to live run.
  2. Watch mode streams only.
  3. Takeover mode grants input.
  4. Run records takeover.
  5. Auto-advance pauses by default.

GitHub Integration

Use GitHub OAuth for login and GitHub App for repo operations.

GitHub App permissions, draft:

Optional/conditional:

Picker behavior:

Deployment

Target domain:

Current DNS expectation:

Cloudflare account:

Worker names:

Initial deployable artifact:

Required deploy checks:

Security

Observability

Dashboard metrics:

Per-run timeline:

Cloudflare Components

BoardDO:

RunDO:

Dispatcher:

GitHubSync:

MergeController:

RetentionJob:

MVP

  1. Auth and admin allowlists.
  2. Board with cards and lanes.
  3. Freeform prompt card.
  4. GitHub issue/PR picker.
  5. Fake runner live logs.
  6. Cloudflare Container runner.
  7. Codex CLI PTY in Ghostty WASM.
  8. R2 log persistence and replay.
  9. Crabbox runner option.
  10. Direct PR creation.
  11. Direct merge with guardrails.
  12. ClawSweeper handoff for review/automerge.

Open Decisions