orcs

Missions in. Receipts out.

orcs is the open-source control plane for AI agents. Delegate missions to agents, run them safely in sandboxes, approve risky steps, keep receipts for every piece of work.

This repository is the orcs monorepo. See conductor/ for product, architecture, and workflow documentation.

Status

Early development. Building toward v0.1 — the killer demo: GitHub issue → orc → sandbox → PR → tests → human approval → receipt.

Requirements

• Node.js 22+ (see .nvmrc)
• pnpm 9+ (corepack enable && corepack prepare pnpm@9.15.0 --activate)
• Docker (for sandbox runtime, later phases)

Quickstart

The headline path: one command brings up the whole stack — postgres, temporal, minio, jaeger, web, api, worker — runs migrations, creates a default user, and opens the UI.

npx @orcs-to/orcs summon --yes

Requires Docker. The CLI auto-detects whether it is running inside the orcs-hub workspace; if so it builds the web/api/worker images locally from this checkout, otherwise it pulls ghcr.io/orcs-to/{web,api,worker}:0.1.0 (the registry tags are TODO until the v0.1 release ships, so the registry-pull path requires a published release).

Other commands:

npx @orcs-to/orcs status         # health table for every container
npx @orcs-to/orcs down           # stop the stack (volumes preserved)
npx @orcs-to/orcs down --volumes # stop + wipe data

With OPENROUTER_API_KEY (or ANTHROPIC_API_KEY) exported, orcs summon also dispatches a tiny first mission so you immediately see the end-to-end loop. Force it with --demo-mission or skip it with --no-demo-mission.

Working on orcs itself

pnpm install
pnpm verify   # typecheck + lint + test

Run web against the api

The web app defaults to a MockApiClient so it boots with no services. To run it against the real apps/api HTTP surface:

# 1. boot the api on :3001 (CORS allows http://localhost:3000 by default)
pnpm --filter @orcs-to/api dev

# 2. boot the web on :3000 with mocks turned off
NEXT_PUBLIC_USE_MOCK_API=0 pnpm --filter @orcs-to/web dev

# 3. open http://localhost:3000

The FetchApiClient reads its session token from localStorage under orcs.sessionToken. Until the browser auth track lands, set it from the devtools console: localStorage.setItem("orcs.sessionToken", "<token>").

Repository Layout

orcs-hub/
  apps/
    web/          # Next.js control plane UI
    api/          # Hono API
    worker/       # Temporal worker — see apps/worker/README.md for dev server + run instructions
    cli/          # npx @orcs-to/orcs

  packages/
    core/         # Mission, Orc, Receipt primitives + sacred provider interfaces
    db/           # Drizzle schema + RLS policies
    sdk/          # public TypeScript SDK
    auth/         # auth abstraction
    policy/       # approvals, permissions, budgets
    telemetry/    # OpenTelemetry helpers
    ui/           # shared UI components
    config/       # shared env/config
    adapters/     # MCP, GitHub, Codex, Claude Agent, etc.

  conductor/      # product / tech / workflow / tracks
  infra/          # docker-compose, k8s manifests

Documentation

• Product — what orcs is, who it's for, primitives, positioning
• Tech Stack — three planes, sacred interfaces, repo layout
• Workflow — TDD, commits, review, verification checkpoints
• Style Guide

License

Apache-2.0