https://github.com/hebbs-ai/boringos
BoringOS is the open-source operating system for AI agents - it ships with a shell portal plus installable modules, powered by agentic CLIs.
https://github.com/hebbs-ai/boringos
agent-native agents ai-agents boringos copilot developer-tools framework harness-framework llm multi-tenant open-source orchestration-framework typescript workflow-engine
Last synced: about 12 hours ago
JSON representation
BoringOS is the open-source operating system for AI agents - it ships with a shell portal plus installable modules, powered by agentic CLIs.
- Host: GitHub
- URL: https://github.com/hebbs-ai/boringos
- Owner: hebbs-ai
- License: agpl-3.0
- Created: 2026-04-08T11:04:44.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-17T15:15:50.000Z (21 days ago)
- Last Synced: 2026-07-01T17:06:20.839Z (7 days ago)
- Topics: agent-native, agents, ai-agents, boringos, copilot, developer-tools, framework, harness-framework, llm, multi-tenant, open-source, orchestration-framework, typescript, workflow-engine
- Language: TypeScript
- Homepage: https://BoringOS.dev
- Size: 8.63 MB
- Stars: 37
- Watchers: 2
- Forks: 6
- Open Issues: 35
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Cla: CLA.md
Awesome Lists containing this project
README
# BoringOS
> The operating system for agents. You ship Modules; the agent
> reads skills and calls tools. Everything else is plumbing.
BoringOS is an open-source framework for building agentic
platforms — agents receive tasks, execute autonomously via CLI
subprocesses (Claude Code, Codex, Gemini CLI, Ollama, …), and
report back. The framework never calls LLM APIs directly; CLIs
are the agents, BoringOS is the orchestrator.
> **The thesis in one read:** [`docs/thesis.md`](docs/thesis.md) —
> what Hebbs is, what ships on day zero (the Shell), what you
> install on top (Modules), how the framework works, and how we
> sell. Read this first, and use it as the source of truth when
> writing any new doc or marketing copy.
---
## Product tour
A 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.
**Jump to a section:**
[Shell](#1-executive-brief) · [Install a module](#7-modules--before-install) · [CRM module example](#9-pipeline--deals-by-stage)
---
### Shell — the operating system
#### 1. Executive brief
> Run the company from one screen: open work, agents online, weekly spend, and the watch items that need a decision today.
[Next →](#2-tasks--operating-units-of-work) · [↑ Tour](#product-tour)
---
#### 2. Tasks — operating units of work
> Every task names its owner, blockers, decisions needed, and risks. Comments are the audit trail. This is how a CEO reads work.
[← Prev](#1-executive-brief) · [Next →](#3-copilot--ask-and-get-decision-ready-output) · [↑ Tour](#product-tour)
---
#### 3. Copilot — ask and get decision-ready output
> "Build me a Tesla account brief." Copilot returns a progress chart, the decision committee, and a ready-to-send email — not a chat transcript.
[← Prev](#2-tasks--operating-units-of-work) · [Next →](#4-agents--your-cabinet) · [↑ Tour](#product-tour)
---
#### 4. Agents — your cabinet
> A real operating cabinet: Chief of Staff at the top; GTM, RevOps, and Engineering pods underneath. Twelve named operators, one chart, clear accountability.
[← Prev](#3-copilot--ask-and-get-decision-ready-output) · [Next →](#5-workflows--repeatable-execution-with-traces) · [↑ Tour](#product-tour)
---
#### 5. Workflows — repeatable execution with traces
> Complex workflows (e.g. enterprise deal qualification) run end-to-end with a span tree on the right. Execution is repeatable and inspectable.
[← Prev](#4-agents--your-cabinet) · [Next →](#6-budgets--ai-spend-with-guardrails) · [↑ Tour](#product-tour)
---
#### 6. Budgets — AI spend with guardrails
> Tenant cap, per-team caps, spend by agent and by model. No surprises at the end of the month.
[← Prev](#5-workflows--repeatable-execution-with-traces) · [Next →](#7-modules--before-install) · [↑ Tour](#product-tour)
---
### Install a module
#### 7. Modules — before install
> The platform ships with the core operating system. New surface areas (sales, support, finance) arrive as signed `.hebbsmod` packages.
[← Prev](#6-budgets--ai-spend-with-guardrails) · [Next →](#8-modules--after-install) · [↑ Tour](#product-tour)
---
#### 8. Modules — after install
> One click installs the CRM module. Pipeline, Deals, Contacts, and Companies appear instantly in the left nav — the org now has a sales surface.
[← Prev](#7-modules--before-install) · [Next →](#9-pipeline--deals-by-stage) · [↑ Tour](#product-tour)
---
### CRM module example — sales operations on the shell
#### 9. Pipeline — deals by stage
> Board-level visibility: every named account, every value, every owner, every stage. The view a CEO opens before the board call.
[← Prev](#8-modules--after-install) · [Next →](#10-contact-dossier--research-grade-context) · [↑ Tour](#product-tour)
---
#### 10. Contact dossier — research-grade context
> Persona, journey, recognition, alerts (TPU v5, LangChain redlines), sourced citations. The brief an AE actually reads before the meeting.
[← Prev](#9-pipeline--deals-by-stage) · [Next →](#11-company-detail--account-intelligence) · [↑ Tour](#product-tour)
---
#### 11. Company detail — account intelligence
> Leadership, strategy shifts, capex cycle, competitive moves — the account brief an exec walks into the boardroom with.
[← Prev](#10-contact-dossier--research-grade-context) · [Next →](#12-copilot--crm--one-prompt-the-full-operating-system) · [↑ Tour](#product-tour)
---
#### 12. Copilot × CRM — one prompt, the full operating system
> "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.
[← Prev](#11-company-detail--account-intelligence) · [↑ Tour](#product-tour)
---
## The two primitives
The agent's prompt is built from two registries, sourced from
plain data — no hand-written providers per integration.
- **Skills** — markdown files (`SKILL.md`) shipped by every
component. Loaded into the agent's prompt under `## Skills`.
Teach the agent how to think about a domain.
- **Tools** — Zod-typed callable operations. Registered by
Modules, dispatched at one URL: `POST /api/tools/.`.
The agent reads an inventory, calls them, gets validated
responses with structured errors.
## The one shape
A **Module** bundles skills + tools + (optionally) schema, UI,
default workflows, default agents, routines, OAuth, and webhooks.
Three roles, same shape:
- **Connector** — brokers a 3rd-party API (`connector-google`,
`connector-slack`)
- **Capability** — pure logic depending on other Modules
(`triage`, `prevent-churn`)
- **Hybrid** — owns its own data + tools (`crm`, `inbox`)
All registered the same way: `app.module(myModule)`. Adding
Notion is one Module package, zero framework edits.
---
## Get started
### The one-liner
Open Cursor (or any agentic CLI — Claude Code, Codex, Gemini)
inside a clone of this repo and say:
> **"deploy boringos shell on my localhost"**
The agent will install dependencies, build the workspace, boot
embedded Postgres, and start the shell on `http://localhost:3000`.
### Manual
```bash
git clone https://github.com/BoringOS-dev/boringos.git
cd boringos
pnpm install
pnpm -r build
pnpm dev
```
Then open `http://localhost:3000`.
### Scaffold your own host
```bash
npx create-boringos my-app
cd my-app && pnpm install && pnpm dev
```
Or wire one inline:
```typescript
import { BoringOS } from "@boringos/core";
import { z } from "@boringos/module-sdk";
import type { Module } from "@boringos/module-sdk";
const helloModule: Module = {
id: "hello",
name: "Hello",
version: "0.1.0",
description: "Demo module",
skills: [{ id: "hello", source: "module",
body: "Use `hello.greet` to say hi to someone." }],
tools: [{
name: "greet",
description: "Greet someone by name",
inputs: z.object({ name: z.string() }),
async handler({ name }) {
return { ok: true, result: { message: `Hello, ${name}!` } };
},
}],
};
const app = new BoringOS({});
app.module(helloModule);
await app.listen(3000);
```
Embedded Postgres boots automatically, the tool dispatcher
mounts at `/api/tools/*`, and the agent's prompt now includes
the `hello` skill plus the `hello.greet` tool.
For the step-by-step guide, see
[`BUILD-A-MODULE.md`](BUILD-A-MODULE.md).
---
## Connecting Google (Gmail + Calendar)
The `@boringos/connector-google` Module needs an OAuth client.
Two minutes in Google Cloud Console, then two env vars.
### 1. Google Cloud Console
[`console.cloud.google.com`](https://console.cloud.google.com)
1. **Create a project** (or pick an existing one).
2. **Enable APIs** — `APIs & Services` → `Library`:
- Gmail API
- Google Calendar API
3. **OAuth consent screen** — `APIs & Services` → `OAuth consent screen`:
- User type: `External` (or `Internal` if you're on Workspace)
- Add your email as a test user while in `Testing` status
- Add these scopes:
- `https://www.googleapis.com/auth/gmail.modify`
- `https://www.googleapis.com/auth/gmail.send`
- `https://www.googleapis.com/auth/calendar`
- `https://www.googleapis.com/auth/calendar.events`
4. **Create OAuth 2.0 Client** — `APIs & Services` → `Credentials`
→ `Create credentials` → `OAuth client ID`:
- Application type: `Web application`
- Authorized JavaScript origins: `http://localhost:3000`
- Authorized redirect URIs:
`http://localhost:3000/api/connectors/oauth/google/callback`
5. Copy the **Client ID** and **Client secret**.
### 2. Environment variables
Drop these in `.env.local` at the repo root:
```bash
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
# Required for the Connector SDK v2 credential encryption.
# 32 random bytes, hex or base64. Generate with:
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Losing this key means losing access to all stored OAuth credentials,
# with no recovery path. Store it in your secret manager in production.
BORINGOS_ENCRYPTION_KEY=64-char-hex-string-here
```
Restart `pnpm dev`, head to the shell's **Connectors** screen,
click **Connect Google**, and finish the OAuth flow. Gmail and
Calendar tools are now available to every agent in that tenant.
> For production hosts, swap `http://localhost:3000` for your
> public origin everywhere above and publish your OAuth consent
> screen.
---
## What's in the box
### Built-in Modules
| Module | Tools | Notes |
|---|---|---|
| `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 |
| `memory` | `memory.{remember,recall,prime,forget}` | Long-term memory (Hebbs or null) |
| `drive` | `drive.{read,write,write_binary,list,delete,stat,move}` | File storage with path-prefix ACL |
| `inbox` | `inbox.{list,archive,create_task}` | Inbound message queue |
| `triage` | `triage.{next_pending,classify}` | Inbox classification capability |
| `copilot` | `copilot.start_session` | Per-tenant assistant |
| `workflow` | `workflow.{run,list,get_run}` | DAG runtime + visual editor |
### Connectors
- `@boringos/connector-google` — Gmail (send, search, read,
archive) + Calendar
- `@boringos/connector-slack` — messages, threads, reactions
### Runtimes
Six pluggable CLI runtimes ship out of the box: Claude Code,
ChatGPT CLI, Gemini, Ollama, generic command, webhook.
### Persistence + transport
- Embedded Postgres by default; external via `DATABASE_URL`
- Drizzle ORM
- Hono HTTP server
- In-process job queue by default; BullMQ via `app.queue(...)`
---
## How an agent works
```
wake (comment / routine / event / admin)
→ coalesce + enqueue
→ fetch agent + create run row
→ build prompt: Skills (from registry) + Tools (from registry)
+ per-run context (task, comments, session, memory)
→ spawn CLI subprocess with $BORINGOS_CALLBACK_TOKEN
→ agent calls POST /api/tools/ with bearer JWT
→ dispatcher: Zod-validate → handler → tool_calls audit row
→ agent posts result comment + sets status=done
→ engine auto-rewakes if more todos remain (success only)
```
Every side effect goes through one URL, validated by one schema,
audited in one table.
---
## Reference docs
- [`BUILD-A-MODULE.md`](BUILD-A-MODULE.md) — step-by-step guide to
shipping your first Module (including dashboard widgets +
Light/Dark theme support)
- [`MODULES.md`](MODULES.md) — Module manifest spec, including the
[`--bos-*` theme contract](MODULES.md#theme-support---the---bos--contract)
every UI-shipping Module should follow
- [`TOOLS.md`](TOOLS.md) — Tool spec, error model, audit, idempotency
- [`SKILLS.md`](SKILLS.md) — Skill spec, file format, priorities
- [`CLAUDE.md`](CLAUDE.md) — orientation for contributors
- [`docs/install-flow.md`](docs/install-flow.md) — how Modules are
packaged, uploaded, installed per-tenant, and uninstalled
- [`docs/INDEX.md`](docs/INDEX.md) — full doc navigation
---
## Packages
| Package | Role |
|---|---|
| `@boringos/core` | `BoringOS` host, builder API, HTTP routes, Module registries |
| `@boringos/module-sdk` | Module / Tool / Skill type SDK (the spec) |
| `@boringos/agent` | Execution engine, context pipeline, registries + dispatcher |
| `@boringos/runtime` | 6 CLI runtimes + subprocess spawning |
| `@boringos/memory` | `MemoryProvider` interface + Hebbs adapter |
| `@boringos/drive` | `StorageBackend` + `DriveManager` |
| `@boringos/db` | Drizzle schema + embedded Postgres + migrations |
| `@boringos/workflow` | DAG runtime |
| `@boringos/workflow-ui` | React canvas + editor |
| `@boringos/pipeline` | Job queue (in-process / BullMQ) |
| `@boringos/connector-google` | Gmail + Calendar Module |
| `@boringos/connector-slack` | Slack Module |
| `@boringos/shell` | Browser shell SPA |
| `@boringos/ui` | Typed API client + React hooks |
| `create-boringos` | CLI generator |
| `@boringos/shared` | Base types, constants, utilities |
---
## Examples
- [`examples/quickstart/`](examples/quickstart/) — boot, create an
agent, assign a task, watch it execute
---
## Commands
```bash
pnpm install
pnpm -r build
pnpm -r typecheck
pnpm test:run
```
---
## License
BoringOS uses a three-tier license layout:
- **Framework** (everything under `packages/@boringos/` except the two
below) — **AGPL-3.0-or-later**. Strong network copyleft: anyone
running a modified version as a service must publish their changes.
- **`@boringos/module-sdk`** — **LGPL-3.0-or-later**. Linking
exception means modules can import the SDK under any license.
- **`@boringos/shared`** — **Apache-2.0**. Pure types/utilities,
permissive so anything can depend on them.
Root [`LICENSE`](LICENSE) holds the AGPL text. See
[`LICENSE.md`](LICENSE.md) for the short index and
[`docs/licensing.md`](docs/licensing.md) for the longer rationale.
Contributions welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md).