{"id":51514825,"url":"https://github.com/hebbs-ai/boringos","last_synced_at":"2026-07-08T10:30:25.945Z","repository":{"id":350313849,"uuid":"1204812825","full_name":"hebbs-ai/boringos","owner":"hebbs-ai","description":"BoringOS is the open-source operating system for AI agents - it ships with a shell portal plus installable modules, powered by agentic CLIs.","archived":false,"fork":false,"pushed_at":"2026-06-17T15:15:50.000Z","size":9048,"stargazers_count":37,"open_issues_count":35,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-07-01T17:06:20.839Z","etag":null,"topics":["agent-native","agents","ai-agents","boringos","copilot","developer-tools","framework","harness-framework","llm","multi-tenant","open-source","orchestration-framework","typescript","workflow-engine"],"latest_commit_sha":null,"homepage":"https://BoringOS.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hebbs-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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":"CLA.md"}},"created_at":"2026-04-08T11:04:44.000Z","updated_at":"2026-06-29T08:18:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hebbs-ai/boringos","commit_stats":null,"previous_names":["boringos-dev/boringos"],"tags_count":145,"template":false,"template_full_name":null,"purl":"pkg:github/hebbs-ai/boringos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hebbs-ai%2Fboringos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hebbs-ai%2Fboringos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hebbs-ai%2Fboringos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hebbs-ai%2Fboringos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hebbs-ai","download_url":"https://codeload.github.com/hebbs-ai/boringos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hebbs-ai%2Fboringos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35107506,"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-04T02:00:05.987Z","response_time":113,"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-native","agents","ai-agents","boringos","copilot","developer-tools","framework","harness-framework","llm","multi-tenant","open-source","orchestration-framework","typescript","workflow-engine"],"created_at":"2026-07-08T10:30:25.180Z","updated_at":"2026-07-08T10:30:25.931Z","avatar_url":"https://github.com/hebbs-ai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BoringOS\n\n![BoringOS — The Operating System for AI](./poster.png)\n\n\u003e The operating system for agents. You ship Modules; the agent\n\u003e reads skills and calls tools. Everything else is plumbing.\n\nBoringOS is an open-source framework for building agentic\nplatforms — agents receive tasks, execute autonomously via CLI\nsubprocesses (Claude Code, Codex, Gemini CLI, Ollama, …), and\nreport back. The framework never calls LLM APIs directly; CLIs\nare the agents, BoringOS is the orchestrator.\n\n\u003e **The thesis in one read:** [`docs/thesis.md`](docs/thesis.md) —\n\u003e what Hebbs is, what ships on day zero (the Shell), what you\n\u003e install on top (Modules), how the framework works, and how we\n\u003e sell. Read this first, and use it as the source of truth when\n\u003e writing any new doc or marketing copy.\n\n---\n\n## Product tour\n\nA guided walk through what BoringOS actually looks like running. First the **Shell** (the operating system surface), then a **CRM module example** showing how an installable module extends it. Tap **Next →** to swipe through.\n\n**Jump to a section:**\n[Shell](#1-executive-brief) · [Install a module](#7-modules--before-install) · [CRM module example](#9-pipeline--deals-by-stage)\n\n---\n\n### Shell — the operating system\n\n#### 1. Executive brief\n\n\u003e Run the company from one screen: open work, agents online, weekly spend, and the watch items that need a decision today.\n\n![Executive brief](./repo-assets/home.png)\n\n[Next →](#2-tasks--operating-units-of-work) · [↑ Tour](#product-tour)\n\n---\n\n#### 2. Tasks — operating units of work\n\n\u003e Every task names its owner, blockers, decisions needed, and risks. Comments are the audit trail. This is how a CEO reads work.\n\n![Task detail](./repo-assets/task_detail.png)\n\n[← Prev](#1-executive-brief) · [Next →](#3-copilot--ask-and-get-decision-ready-output) · [↑ Tour](#product-tour)\n\n---\n\n#### 3. Copilot — ask and get decision-ready output\n\n\u003e \"Build me a Tesla account brief.\" Copilot returns a progress chart, the decision committee, and a ready-to-send email — not a chat transcript.\n\n![Copilot](./repo-assets/copilot.png)\n\n[← Prev](#2-tasks--operating-units-of-work) · [Next →](#4-agents--your-cabinet) · [↑ Tour](#product-tour)\n\n---\n\n#### 4. Agents — your cabinet\n\n\u003e A real operating cabinet: Chief of Staff at the top; GTM, RevOps, and Engineering pods underneath. Twelve named operators, one chart, clear accountability.\n\n![Agents org chart](./repo-assets/agents_org.png)\n\n[← Prev](#3-copilot--ask-and-get-decision-ready-output) · [Next →](#5-workflows--repeatable-execution-with-traces) · [↑ Tour](#product-tour)\n\n---\n\n#### 5. Workflows — repeatable execution with traces\n\n\u003e Complex workflows (e.g. enterprise deal qualification) run end-to-end with a span tree on the right. Execution is repeatable and inspectable.\n\n![Workflow run drawer](./repo-assets/workflows_run.png)\n\n[← Prev](#4-agents--your-cabinet) · [Next →](#6-budgets--ai-spend-with-guardrails) · [↑ Tour](#product-tour)\n\n---\n\n#### 6. Budgets — AI spend with guardrails\n\n\u003e Tenant cap, per-team caps, spend by agent and by model. No surprises at the end of the month.\n\n![Budgets](./repo-assets/budgets.png)\n\n[← Prev](#5-workflows--repeatable-execution-with-traces) · [Next →](#7-modules--before-install) · [↑ Tour](#product-tour)\n\n---\n\n### Install a module\n\n#### 7. Modules — before install\n\n\u003e The platform ships with the core operating system. New surface areas (sales, support, finance) arrive as signed `.hebbsmod` packages.\n\n![Modules pre-install](./repo-assets/modules_pre.png)\n\n[← Prev](#6-budgets--ai-spend-with-guardrails) · [Next →](#8-modules--after-install) · [↑ Tour](#product-tour)\n\n---\n\n#### 8. Modules — after install\n\n\u003e One click installs the CRM module. Pipeline, Deals, Contacts, and Companies appear instantly in the left nav — the org now has a sales surface.\n\n![Modules post-install](./repo-assets/modules_post.png)\n\n[← Prev](#7-modules--before-install) · [Next →](#9-pipeline--deals-by-stage) · [↑ Tour](#product-tour)\n\n---\n\n### CRM module example — sales operations on the shell\n\n#### 9. Pipeline — deals by stage\n\n\u003e Board-level visibility: every named account, every value, every owner, every stage. The view a CEO opens before the board call.\n\n![Pipeline](./repo-assets/pipeline.png)\n\n[← Prev](#8-modules--after-install) · [Next →](#10-contact-dossier--research-grade-context) · [↑ Tour](#product-tour)\n\n---\n\n#### 10. Contact dossier — research-grade context\n\n\u003e Persona, journey, recognition, alerts (TPU v5, LangChain redlines), sourced citations. The brief an AE actually reads before the meeting.\n\n![Contact dossier](./repo-assets/contact_dossier_intel.png)\n\n[← Prev](#9-pipeline--deals-by-stage) · [Next →](#11-company-detail--account-intelligence) · [↑ Tour](#product-tour)\n\n---\n\n#### 11. Company detail — account intelligence\n\n\u003e Leadership, strategy shifts, capex cycle, competitive moves — the account brief an exec walks into the boardroom with.\n\n![Company detail](./repo-assets/company_detail.png)\n\n[← Prev](#10-contact-dossier--research-grade-context) · [Next →](#12-copilot--crm--one-prompt-the-full-operating-system) · [↑ Tour](#product-tour)\n\n---\n\n#### 12. Copilot × CRM — one prompt, the full operating system\n\n\u003e \"I just met Sam Altman at the GPT-5.5 event — scan everything we have on OpenAI and draft a follow-up.\" One turn reaches across deals, contacts, dossiers, and the inbox; the reply is links and decisions, not a chat transcript.\n\n![Copilot — OpenAI follow-up](./repo-assets/copilot_openai.png)\n\n[← Prev](#11-company-detail--account-intelligence) · [↑ Tour](#product-tour)\n\n---\n\n## The two primitives\n\nThe agent's prompt is built from two registries, sourced from\nplain data — no hand-written providers per integration.\n\n- **Skills** — markdown files (`SKILL.md`) shipped by every\n  component. Loaded into the agent's prompt under `## Skills`.\n  Teach the agent how to think about a domain.\n- **Tools** — Zod-typed callable operations. Registered by\n  Modules, dispatched at one URL: `POST /api/tools/\u003cmodule\u003e.\u003ctool\u003e`.\n  The agent reads an inventory, calls them, gets validated\n  responses with structured errors.\n\n## The one shape\n\nA **Module** bundles skills + tools + (optionally) schema, UI,\ndefault workflows, default agents, routines, OAuth, and webhooks.\nThree roles, same shape:\n\n- **Connector** — brokers a 3rd-party API (`connector-google`,\n  `connector-slack`)\n- **Capability** — pure logic depending on other Modules\n  (`triage`, `prevent-churn`)\n- **Hybrid** — owns its own data + tools (`crm`, `inbox`)\n\nAll registered the same way: `app.module(myModule)`. Adding\nNotion is one Module package, zero framework edits.\n\n---\n\n## Get started\n\n### The one-liner\n\nOpen Cursor (or any agentic CLI — Claude Code, Codex, Gemini)\ninside a clone of this repo and say:\n\n\u003e **\"deploy boringos shell on my localhost\"**\n\nThe agent will install dependencies, build the workspace, boot\nembedded Postgres, and start the shell on `http://localhost:3000`.\n\n### Manual\n\n```bash\ngit clone https://github.com/BoringOS-dev/boringos.git\ncd boringos\npnpm install\npnpm -r build\npnpm dev\n```\n\nThen open `http://localhost:3000`.\n\n### Scaffold your own host\n\n```bash\nnpx create-boringos my-app\ncd my-app \u0026\u0026 pnpm install \u0026\u0026 pnpm dev\n```\n\nOr wire one inline:\n\n```typescript\nimport { BoringOS } from \"@boringos/core\";\nimport { z } from \"@boringos/module-sdk\";\nimport type { Module } from \"@boringos/module-sdk\";\n\nconst helloModule: Module = {\n  id: \"hello\",\n  name: \"Hello\",\n  version: \"0.1.0\",\n  description: \"Demo module\",\n  skills: [{ id: \"hello\", source: \"module\",\n    body: \"Use `hello.greet` to say hi to someone.\" }],\n  tools: [{\n    name: \"greet\",\n    description: \"Greet someone by name\",\n    inputs: z.object({ name: z.string() }),\n    async handler({ name }) {\n      return { ok: true, result: { message: `Hello, ${name}!` } };\n    },\n  }],\n};\n\nconst app = new BoringOS({});\napp.module(helloModule);\nawait app.listen(3000);\n```\n\nEmbedded Postgres boots automatically, the tool dispatcher\nmounts at `/api/tools/*`, and the agent's prompt now includes\nthe `hello` skill plus the `hello.greet` tool.\n\nFor the step-by-step guide, see\n[`BUILD-A-MODULE.md`](BUILD-A-MODULE.md).\n\n---\n\n## Connecting Google (Gmail + Calendar)\n\nThe `@boringos/connector-google` Module needs an OAuth client.\nTwo minutes in Google Cloud Console, then two env vars.\n\n### 1. Google Cloud Console\n\n[`console.cloud.google.com`](https://console.cloud.google.com)\n\n1. **Create a project** (or pick an existing one).\n2. **Enable APIs** — `APIs \u0026 Services` → `Library`:\n   - Gmail API\n   - Google Calendar API\n3. **OAuth consent screen** — `APIs \u0026 Services` → `OAuth consent screen`:\n   - User type: `External` (or `Internal` if you're on Workspace)\n   - Add your email as a test user while in `Testing` status\n   - Add these scopes:\n     - `https://www.googleapis.com/auth/gmail.modify`\n     - `https://www.googleapis.com/auth/gmail.send`\n     - `https://www.googleapis.com/auth/calendar`\n     - `https://www.googleapis.com/auth/calendar.events`\n4. **Create OAuth 2.0 Client** — `APIs \u0026 Services` → `Credentials`\n   → `Create credentials` → `OAuth client ID`:\n   - Application type: `Web application`\n   - Authorized JavaScript origins: `http://localhost:3000`\n   - Authorized redirect URIs:\n     `http://localhost:3000/api/connectors/oauth/google/callback`\n5. Copy the **Client ID** and **Client secret**.\n\n### 2. Environment variables\n\nDrop these in `.env.local` at the repo root:\n\n```bash\nGOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGOOGLE_CLIENT_SECRET=your-client-secret\n\n# Required for the Connector SDK v2 credential encryption.\n# 32 random bytes, hex or base64. Generate with:\n#   node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"\n# Losing this key means losing access to all stored OAuth credentials,\n# with no recovery path. Store it in your secret manager in production.\nBORINGOS_ENCRYPTION_KEY=64-char-hex-string-here\n```\n\nRestart `pnpm dev`, head to the shell's **Connectors** screen,\nclick **Connect Google**, and finish the OAuth flow. Gmail and\nCalendar tools are now available to every agent in that tenant.\n\n\u003e For production hosts, swap `http://localhost:3000` for your\n\u003e public origin everywhere above and publish your OAuth consent\n\u003e screen.\n\n---\n\n## What's in the box\n\n### Built-in Modules\n\n| Module | Tools | Notes |\n|---|---|---|\n| `framework` | `tasks.{read,create,patch}`, `comments.post`, `work_products.record`, `runs.report_cost`, `agents.{create,list,wake}`, `inbox.{read,update}` | The agent's universal callback API |\n| `memory` | `memory.{remember,recall,prime,forget}` | Long-term memory (Hebbs or null) |\n| `drive` | `drive.{read,write,write_binary,list,delete,stat,move}` | File storage with path-prefix ACL |\n| `inbox` | `inbox.{list,archive,create_task}` | Inbound message queue |\n| `triage` | `triage.{next_pending,classify}` | Inbox classification capability |\n| `copilot` | `copilot.start_session` | Per-tenant assistant |\n| `workflow` | `workflow.{run,list,get_run}` | DAG runtime + visual editor |\n\n### Connectors\n\n- `@boringos/connector-google` — Gmail (send, search, read,\n  archive) + Calendar\n- `@boringos/connector-slack` — messages, threads, reactions\n\n### Runtimes\n\nSix pluggable CLI runtimes ship out of the box: Claude Code,\nChatGPT CLI, Gemini, Ollama, generic command, webhook.\n\n### Persistence + transport\n\n- Embedded Postgres by default; external via `DATABASE_URL`\n- Drizzle ORM\n- Hono HTTP server\n- In-process job queue by default; BullMQ via `app.queue(...)`\n\n---\n\n## How an agent works\n\n```\nwake (comment / routine / event / admin)\n  → coalesce + enqueue\n  → fetch agent + create run row\n  → build prompt: Skills (from registry) + Tools (from registry)\n                  + per-run context (task, comments, session, memory)\n  → spawn CLI subprocess with $BORINGOS_CALLBACK_TOKEN\n  → agent calls POST /api/tools/\u003cname\u003e with bearer JWT\n  → dispatcher: Zod-validate → handler → tool_calls audit row\n  → agent posts result comment + sets status=done\n  → engine auto-rewakes if more todos remain (success only)\n```\n\nEvery side effect goes through one URL, validated by one schema,\naudited in one table.\n\n---\n\n## Reference docs\n\n- [`BUILD-A-MODULE.md`](BUILD-A-MODULE.md) — step-by-step guide to\n  shipping your first Module (including dashboard widgets +\n  Light/Dark theme support)\n- [`MODULES.md`](MODULES.md) — Module manifest spec, including the\n  [`--bos-*` theme contract](MODULES.md#theme-support---the---bos--contract)\n  every UI-shipping Module should follow\n- [`TOOLS.md`](TOOLS.md) — Tool spec, error model, audit, idempotency\n- [`SKILLS.md`](SKILLS.md) — Skill spec, file format, priorities\n- [`CLAUDE.md`](CLAUDE.md) — orientation for contributors\n- [`docs/install-flow.md`](docs/install-flow.md) — how Modules are\n  packaged, uploaded, installed per-tenant, and uninstalled\n- [`docs/INDEX.md`](docs/INDEX.md) — full doc navigation\n\n---\n\n## Packages\n\n| Package | Role |\n|---|---|\n| `@boringos/core` | `BoringOS` host, builder API, HTTP routes, Module registries |\n| `@boringos/module-sdk` | Module / Tool / Skill type SDK (the spec) |\n| `@boringos/agent` | Execution engine, context pipeline, registries + dispatcher |\n| `@boringos/runtime` | 6 CLI runtimes + subprocess spawning |\n| `@boringos/memory` | `MemoryProvider` interface + Hebbs adapter |\n| `@boringos/drive` | `StorageBackend` + `DriveManager` |\n| `@boringos/db` | Drizzle schema + embedded Postgres + migrations |\n| `@boringos/workflow` | DAG runtime |\n| `@boringos/workflow-ui` | React canvas + editor |\n| `@boringos/pipeline` | Job queue (in-process / BullMQ) |\n| `@boringos/connector-google` | Gmail + Calendar Module |\n| `@boringos/connector-slack` | Slack Module |\n| `@boringos/shell` | Browser shell SPA |\n| `@boringos/ui` | Typed API client + React hooks |\n| `create-boringos` | CLI generator |\n| `@boringos/shared` | Base types, constants, utilities |\n\n---\n\n## Examples\n\n- [`examples/quickstart/`](examples/quickstart/) — boot, create an\n  agent, assign a task, watch it execute\n\n---\n\n## Commands\n\n```bash\npnpm install\npnpm -r build\npnpm -r typecheck\npnpm test:run\n```\n\n---\n\n## License\n\nBoringOS uses a three-tier license layout:\n\n- **Framework** (everything under `packages/@boringos/` except the two\n  below) — **AGPL-3.0-or-later**. Strong network copyleft: anyone\n  running a modified version as a service must publish their changes.\n- **`@boringos/module-sdk`** — **LGPL-3.0-or-later**. Linking\n  exception means modules can import the SDK under any license.\n- **`@boringos/shared`** — **Apache-2.0**. Pure types/utilities,\n  permissive so anything can depend on them.\n\nRoot [`LICENSE`](LICENSE) holds the AGPL text. See\n[`LICENSE.md`](LICENSE.md) for the short index and\n[`docs/licensing.md`](docs/licensing.md) for the longer rationale.\n\nContributions welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhebbs-ai%2Fboringos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhebbs-ai%2Fboringos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhebbs-ai%2Fboringos/lists"}