BoringOS

A framework for building agentic platforms. Like Rails extracted from Basecamp — but for AI agents.

Quick Start

import { BoringOS } from "@boringos/core";

const app = new BoringOS({});
const server = await app.listen(3000);
// Embedded Postgres boots, schema created, 6 runtimes registered
// Agent callback API at /api/agent/* (JWT authenticated)
// Health check at /health

Or scaffold a new project:

npx create-boringos my-app
cd my-app && npm run dev

Zero external dependencies required. Embedded Postgres starts automatically.

What is BoringOS?

BoringOS is a framework that lets you build platforms where AI agents receive tasks, execute autonomously via CLI tools, and report back. Agents run as CLI subprocesses (Claude Code, Codex, Gemini CLI, Ollama, or any command), not via raw LLM API calls.

The framework handles:

• Agent execution pipeline — wake → queue → build context → spawn runtime → stream output → persist state
• Context assembly — 12 composable providers that build system instructions + task context
• 6 runtime adapters — Claude, ChatGPT, Gemini, Ollama, generic command, webhook
• 12 persona bundles — CEO, CTO, engineer, researcher, PM, QA, DevOps, designer, PA, content creator, finance, default
• Workflow engine — DAG-based execution with condition branching, delays, and transforms
• Cognitive memory — pluggable memory providers (Hebbs or custom)
• File storage — local drive with organization rules agents understand
• Database — embedded or external Postgres with Drizzle ORM
• JWT-authenticated callback API — agents call back to update tasks, post comments, record work products
• Admin REST API — manage agents, tasks, runs, runtimes, approvals via API key auth
• SSE realtime events — live streaming of run status, task updates, approvals
• User auth — signup, login, session tokens, user-tenant membership
• Activity logging — audit trail for all admin mutations
• Budget enforcement — cost limits per agent/tenant with hard-stop + warnings
• Routine scheduler — cron-based recurring agent tasks
• Notifications — email via Resend (task completion, failures, approvals)
• Execution workspaces — git worktree provisioning for code tasks
• Skill system — sync from GitHub/URL, per-agent attachment, trust levels
• Plugin system — extensible jobs + webhooks, built-in GitHub plugin (guide)
• Projects & Goals — organize tasks into projects with repo config, auto-identifiers (ALPHA-001)
• Task features — labels, read states, attachments, checkout locks
• Drive features — file indexing, memory sync, drive skill revisions
• Onboarding — 5-step setup wizard per tenant
• Device auth — CLI login flow (generate code → browser approve → poll for token)
• Evaluations — A/B test agent quality with structured test cases
• Inbox — receive and triage external messages, convert to tasks
• Custom schema — .schema(ddl) to add your own tables that reference framework tables
• Entity linking — link domain entities (contacts, deals) to tasks, runs, inbox items
• Event-to-inbox routing — declaratively route connector events to inbox
• Cross-entity search — GET /api/admin/search?q= across tasks, agents, inbox
• Agent templates — createAgentFromTemplate(role) with built-in personas
• Team templates — createTeam("engineering") wires up CTO + engineers + QA with hierarchy
• Agent hierarchy — org tree, delegation to reports, escalation to manager
• Convention over configuration — everything works with zero config

Packages

Package	Purpose
@boringos/core	Application host — BoringOS class, builder API, HTTP server
@boringos/agent	Execution engine — context pipeline, wakeup coalescing, run lifecycle, personas
@boringos/runtime	6 runtime modules + registry + subprocess spawning
@boringos/memory	MemoryProvider interface + Hebbs provider + null provider
@boringos/drive	StorageBackend interface + local filesystem implementation
@boringos/db	Drizzle schema (17 tables) + embedded Postgres + migration manager
@boringos/workflow	DAG workflow engine + block handlers + workflow store
@boringos/pipeline	Pluggable job queue — in-process (default) or BullMQ (opt-in)
@boringos/connector	Connector SDK — interfaces, registry, OAuth, EventBus, test harness
@boringos/connector-slack	Slack reference connector (messages, threads, reactions)
@boringos/connector-google	Google Workspace connector (Gmail + Calendar)
@boringos/ui	Typed API client + headless React hooks (TanStack Query)
create-boringos	CLI generator — npx create-boringos my-app
@boringos/shared	Base types, constants, Hook utility, ID generation

Builder API

import { BoringOS, createHebbsMemory } from "@boringos/core";

const app = new BoringOS({
  database: { url: "postgres://..." },        // or omit for embedded
  drive: { root: "./data/drive" },             // or omit for default
  auth: { secret: "your-secret" },             // JWT signing secret
});

app.memory(createHebbsMemory({ endpoint: "...", apiKey: "..." }));
app.connector(slack({ signingSecret: "..." }));         // Slack integration
app.connector(google({ clientId: "...", clientSecret: "..." })); // Gmail + Calendar
app.queue(createBullMQQueue({ redis: "redis://..." })); // opt-in BullMQ
app.runtime(myCustomRuntime);                  // add custom runtimes
app.contextProvider(myProvider);               // add custom context providers
app.blockHandler(myWorkflowHandler);           // add custom workflow block handlers
app.persona("platform-engineer", bundle);      // add custom personas
app.plugin(myPlugin);                          // register plugins
app.beforeStart(async (ctx) => { ... });       // lifecycle hooks
app.route("/custom", honoApp);                 // mount custom routes

const server = await app.listen(3000);

Commands

pnpm install           # Install dependencies
pnpm -r build          # Build all packages
pnpm -r typecheck      # Typecheck all packages
pnpm test:run          # Run all tests (122 tests)

Examples

• examples/quickstart/ — Boot, create an agent, assign a task, watch it execute

Detailed Docs

See CLAUDE.md for the full agent orientation guide — package details, execution pipeline, all interfaces, environment variables.

License

MIT