{"id":51609557,"url":"https://github.com/safetymp/corpos","last_synced_at":"2026-07-12T06:02:08.142Z","repository":{"id":368215156,"uuid":"1283409030","full_name":"SafetyMP/CorpOS","owner":"SafetyMP","description":"A greenfield reference architecture for an autonomous company — a TypeScript multi-agent runtime with a policy, approval, and audit control plane.","archived":false,"fork":false,"pushed_at":"2026-07-12T01:35:44.000Z","size":596,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-12T03:07:26.004Z","etag":null,"topics":["agent-orchestration","ai","approval-workflow","autonomous-agents","control-plane","llm","multi-agent","multi-tenant","openrouter","policy-engine","simulation","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/SafetyMP/CorpOS","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SafetyMP.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-28T22:35:31.000Z","updated_at":"2026-07-12T01:06:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SafetyMP/CorpOS","commit_stats":null,"previous_names":["safetymp/corpos"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SafetyMP/CorpOS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SafetyMP%2FCorpOS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SafetyMP%2FCorpOS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SafetyMP%2FCorpOS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SafetyMP%2FCorpOS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SafetyMP","download_url":"https://codeload.github.com/SafetyMP/CorpOS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SafetyMP%2FCorpOS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35383520,"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-07-12T02:00:06.386Z","response_time":87,"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-orchestration","ai","approval-workflow","autonomous-agents","control-plane","llm","multi-agent","multi-tenant","openrouter","policy-engine","simulation","typescript"],"created_at":"2026-07-12T06:02:07.371Z","updated_at":"2026-07-12T06:02:08.135Z","avatar_url":"https://github.com/SafetyMP.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CorpOS\n\n\u003e A reference architecture for an autonomous company — a TypeScript multi-agent runtime with a policy, approval, and audit control plane.\n\n[![CI](https://github.com/SafetyMP/CorpOS/actions/workflows/ci.yml/badge.svg)](https://github.com/SafetyMP/CorpOS/actions/workflows/ci.yml)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%E2%89%A5%2020-green.svg)](package.json)\n[![Tests](https://img.shields.io/badge/tests-38%20passing-brightgreen.svg)](test)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/img/dashboard.png\" alt=\"CorpOS control-plane dashboard\" width=\"860\" /\u003e\n\u003c/p\u003e\n\nCorpOS is a **greenfield, architecture-first** system: a clean, layered design for running an organization of LLM-driven agents where **every consequential action is policy-gated**. Department agents (support, sales, ops, finance, engineering) reason via an LLM, call permissioned tools, and coordinate through a shared orchestrator. Spend, external comms, and mutations never run autonomously — they route through an approval engine and produce audit events.\n\nIt's built **simulation-first**: the entire multi-agent loop, tool-calling, approval gates, spend tracking, and dashboard are fully demonstrable and tested with **no LLM key and no network**. Drop in an OpenRouter key to switch the agents to live reasoning.\n\n---\n\n## Design principles\n\nCorpOS is built as an open reference architecture, not a black box. The decisions that shape it:\n\n- **Architecture over implementation.** The value lives in the layers — a typed runtime, a permissioned tool registry, a policy chokepoint, and a control plane — not in any one agent or integration.\n- **Policy as the single chokepoint.** There is exactly one place a consequential action is authorized. Tools can't bypass it; agents can't bypass it. Auditability is a side-effect of the design, not a feature bolted on.\n- **Simulation-first = reproducible.** The reasoning loop is LLM-driven but fully deterministic under the `SimulationProvider`. The whole system builds and tests in CI with zero network and zero cost.\n- **Human-in-the-loop by default.** Consequential actions pause for approval. Agents resume from the exact conversation state where they paused — no lost context, no re-prompting.\n- **Boring, durable tech.** TypeScript, SQLite, Express, vanilla web. No agent framework lock-in; every primitive is readable in a single file.\n\n## Architecture\n\n```\n┌─────────────────────────── Control plane (src/api) ───────────────────────────┐\n│  Express REST (tasks, agents, approvals, spend, events) · WebSocket · dashboard │\n└──────────────────────────────────────┬────────────────────────────────────────┘\n                                       │\n┌─────────────────────────────── Orchestrator (src/core) ───────────────────────┐\n│  lifecycle · dispatch · concurrency · retries · approval resume                │\n└──────────────────────────────────────┬────────────────────────────────────────┘\n                                       │\n            ┌──────────────────────────┼───────────────────────────┐\n            ▼                          ▼                           ▼\n       Agent (loop)              Policy engine                Tool registry\n   reason → tool → observe      allow / deny / approve       typed, JSON-schema,\n   pause/resume on gates        spend caps, approvals         permission-gated\n            │                          │                           │\n            └────────────── LLM provider ──────────── Store (SQLite) ─┘\n                  Simulation (default)         tasks · events · approvals\n                  OpenRouter / Z.AI / OpenAI   spend · memory · audit\n```\n\n| Layer             | Path                         | Responsibility                                                                                                        |\n| ----------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |\n| **Runtime**       | `src/core/`                  | types, llm, logger(+audit), event-bus, store (SQLite), tool registry, policy engine, memory, agent loop, orchestrator |\n| **Agents**        | `src/agents/`                | one file per department — system prompt + tool subset                                                                 |\n| **Tools**         | `src/tools/`                 | CRM, comms, billing, knowledge, system packs over shared seeded state + agent-to-agent delegate                       |\n| **Control plane** | `src/api/`, `src/dashboard/` | Express REST + WebSocket + static dashboard                                                                           |\n\n## Quick start\n\n```bash\ngit clone https://github.com/SafetyMP/CorpOS.git\ncd CorpOS\nnpm install\nnpm run dev        # boot the server + dashboard on $PORT or 3000\n```\n\nOpen `http://localhost:3000/`. With no key set, agents run in **simulation** — click **▶ Run demo** to watch a curated 5-agent scenario auto-play through real approval gates.\n\n\u003e **Node version:** requires Node 20+ (verified through Node 26). If `npm install`\n\u003e fails while compiling `better-sqlite3` (a V8-API error from node-gyp), you're on\n\u003e an unsupported Node — use Node 22 LTS. On supported versions the install uses a\n\u003e prebuilt binary, so no compiler is needed.\n\n### Live demo (one-click deploy)\n\nNo clone required — run the control plane in the cloud in simulation mode, then\nclick **▶ Run demo**:\n\n[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/SafetyMP/CorpOS)\n\nPrefer Fly.io? It's one command (uses the published image):\n\n```bash\nflyctl launch --image ghcr.io/safelymp/corpos:0.1.0\n```\n\nSet `OPENROUTER_API_KEY` in either dashboard to switch the agents from\nsimulation to live reasoning. See [Deployment](#deployment) below.\n\n### Go live (OpenRouter / Owl Alpha)\n\n```bash\ncp .env.example .env\n# edit .env:\n#   OPENROUTER_API_KEY=sk-or-...\n#   OPENROUTER_MODEL=\u003cyour Owl Alpha slug\u003e\nnpm run dev\n```\n\nThe header badge flips from `simulation` to `live · openrouter`, and agents reason against the real model. Z.AI and OpenAI are also supported (auto-detected by key).\n\n## Demo mode\n\nOne click on **▶ Run demo** posts a curated 5-agent scenario — support refund, ops service restart, finance goodwill credit, sales follow-up, engineer diagnosis — and **auto-resolves every approval gate** so the full policy-gated loop plays out without manual steps. Deterministic in simulation; genuine reasoning when live.\n\n## How an action gets approved\n\n1. A task is enqueued; the orchestrator assigns it to an agent.\n2. The agent reasons and emits tool calls. Each call is evaluated by the **policy engine**.\n3. A `read` call runs; a `spend` / `communicate` / mutating call **pauses** and creates a pending approval.\n4. A human approves via the dashboard or `POST /api/approvals/:id/decide`.\n5. On approval the agent **resumes from where it paused** (conversation preserved), executes the action, records spend, and produces a final summary — all audited.\n\n## Commands\n\n| Command             | What it does                                      |\n| ------------------- | ------------------------------------------------- |\n| `npm install`       | Install dependencies                              |\n| `npm run dev`       | Boot API + dashboard (tsx watch)                  |\n| `npm run scenario`  | Run a recorded deterministic multi-agent scenario |\n| `npm test`          | Run the vitest suite (deterministic, no network)  |\n| `npm run typecheck` | `tsc --noEmit`                                    |\n| `npm run build`     | Compile to `dist/`                                |\n\n## REST + WebSocket API (selected)\n\n| Method         | Path                        | Purpose                                 |\n| -------------- | --------------------------- | --------------------------------------- |\n| `GET`          | `/api/health`               | Liveness + provider mode                |\n| `GET`          | `/api/agents`               | Registered agents + tools               |\n| `GET` / `POST` | `/api/tasks`                | List / submit tasks                     |\n| `GET`          | `/api/approvals`            | Pending approvals                       |\n| `POST`         | `/api/approvals/:id/decide` | `{decision:\"approved\"\\|\"rejected\", by}` |\n| `GET`          | `/api/spend`                | Spend ledger totals                     |\n| `GET`          | `/api/events?limit=50`      | Recent events                           |\n| `WS`           | `/ws`                       | Live snapshot + event stream            |\n\n```bash\ncurl -X POST http://localhost:3000/api/tasks \\\n  -H 'content-type: application/json' \\\n  -d '{\"title\":\"Refund for Ada\",\"description\":\"ada@example.com wants a $49 refund on sub_ada_pro.\",\"assignedTo\":\"agent_support\",\"priority\":2}'\n```\n\n## Configuration\n\nEnvironment variables (auto-loaded from `.env` on boot — see `.env.example`):\n\n| Var                                       | Default                | Purpose                                       |\n| ----------------------------------------- | ---------------------- | --------------------------------------------- |\n| `OPENROUTER_API_KEY`                      | —                      | Live OpenRouter key. Unset → simulation mode. |\n| `OPENROUTER_MODEL`                        | `openrouter/owl-alpha` | Model slug.                                   |\n| `OPENROUTER_REFERER` / `OPENROUTER_TITLE` | —                      | OpenRouter attribution headers.               |\n| `OPENAI_API_KEY` / `ZAI_API_KEY`          | —                      | Alternative providers (auto-detected).        |\n| `PORT`                                    | `3000`                 | HTTP port.                                    |\n| `LOG_LEVEL`                               | `info`                 | `debug` / `info` / `warn` / `error`.          |\n\nNever commit a real `.env` (it's gitignored).\n\n## Project structure\n\n```\nsrc/\n  core/         runtime: types, llm, store, tool, policy, memory, agent, orchestrator, app\n  agents/       department agents (support, sales, finance, ops, engineer)\n  tools/        tool packs (crm, comms, billing, knowledge, system, delegate) + seeded state\n  api/          Express REST + WebSocket server\n  dashboard/    static dashboard (single-file HTML/CSS/JS)\n  index.ts      composition root — wires core + agents + tools + server, loads .env\n  scenario.ts   deterministic multi-agent demo\ntest/           vitest unit + e2e (deterministic via SimulationProvider)\n.github/        CI workflow\ndocs/           screenshots / assets\n```\n\n## Tech stack\n\nTypeScript (ESM, strict) · Node ≥ 20 · better-sqlite3 · Express · ws · zod · nanoid · vitest · tsx. The dashboard is dependency-free vanilla HTML/CSS/JS.\n\n## Deployment\n\nA prebuilt multi-arch image is published to the GitHub Container Registry on\nevery push to `main` and every release:\n\n```bash\ndocker run --rm -p 3000:3000 ghcr.io/safelymp/corpos:latest\n# → http://localhost:3000  (simulation mode, zero config)\n```\n\nGo live by passing a key:\n\n```bash\ndocker run --rm -p 3000:3000 \\\n  -e OPENROUTER_API_KEY=sk-or-... \\\n  -e OPENROUTER_MODEL=\u003cyour Owl Alpha slug\u003e \\\n  ghcr.io/safelymp/corpos:latest\n```\n\nManaged options (both auto-detect the `Dockerfile`, both run the simulation\ndemo by default):\n\n- **Render** — one click via the \"Deploy to Render\" button above; configured by\n  [`render.yaml`](render.yaml).\n- **Fly.io** — `flyctl launch --image ghcr.io/safelymp/corpos:0.1.0`; configured\n  by [`fly.toml`](fly.toml), with a release-triggered\n  [deploy workflow](.github/workflows/deploy.yml) (needs `FLY_API_TOKEN`).\n\n⚠️ **Do not deploy to a public URL without reading [SECURITY.md](SECURITY.md)\nfirst** — the control plane has no authentication, and anyone who can reach it\ncan approve gated actions. For a public demo, keep it in simulation mode and\nrestart it periodically (the in-memory agent state resets on restart).\n\n## Security\n\nCorpOS is a **reference architecture and research/demo project, not production-hardened.** Consequential actions are policy-gated by design, but the control plane has no authentication, authorization, or rate limiting — do not expose it to untrusted networks. See [SECURITY.md](SECURITY.md) for the full posture and vulnerability reporting.\n\n## Contributing\n\nContributions are welcome. The codebase is intentionally readable and layered — each core primitive fits in a single file. See [AGENTS.md](AGENTS.md) for the engineering rules and conventions the project follows (commit style, verification, code style) and [CONTEXT.md](CONTEXT.md) for architecture orientation. Run `npm test` before opening a PR; CI enforces typecheck + tests.\n\n## License\n\nApache License 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE). Copyright © 2026 SafetyMP.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsafetymp%2Fcorpos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsafetymp%2Fcorpos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsafetymp%2Fcorpos/lists"}