hebbs-ai/boringos

에이전트를 위한 운영체제(Operating System). 당신은 모듈(Modules)을 배포하며, 에이전트는 기술(skills)을 읽고 도구(tools)를 호출합니다. 그 외의 모든 것은 배관(plumbing) 작업입니다.

BoringOS는 에이전트 플랫폼을 구축하기 위한 오픈 소스 프레임워크입니다. 에이전트는 작업을 수신하고, CLI 서브프로세스(Claude Code, Codex, Gemini CLI, Ollama, …)를 통해 자율적으로 실행하며, 결과를 보고합니다. 이 프레임워크는 LLM API를 직접 호출하지 않습니다. CLI가 에이전트이며, BoringOS는 오케스트레이터(orchestrator) 역할을 합니다.

한 번에 읽는 논지(thesis): docs/thesis.md

— Hebbs가 무엇인지, 출시 첫날 무엇이 제공되는지(Shell), 그 위에 무엇을 설치하는지(Modules), 프레임워크가 어떻게 작동하는지, 그리고 우리가 어떻게 판매하는지에 대한 내용입니다. 이를 먼저 읽고, 새로운 문서나 마케팅 문구를 작성할 때 신뢰할 수 있는 근거(source of truth)로 사용하세요.

BoringOS가 실제로 실행되는 모습을 안내하는 가이드입니다. 먼저 Shell(운영체제 표면)을 살펴본 다음, 설치 가능한 모듈이 이를 어떻게 확장하는지 보여주는 CRM 모듈 예시를 확인합니다. **Next →**를 눌러 넘겨보세요.

섹션 바로가기:
Shell · 모듈 설치 · CRM 모듈 예시

한 화면에서 회사를 운영하세요: 진행 중인 업무, 온라인 상태인 에이전트, 주간 지출, 그리고 오늘 결정이 필요한 관찰 항목들을 확인합니다.

모든 작업에는 담당자, 차단 요소(blockers), 필요한 결정, 그리고 리스크가 명시됩니다. 댓글은 감사 추적(audit trail) 역할을 합니다. 이것이 CEO가 업무를 파악하는 방식입니다.

"Tesla 계정 브리프를 작성해줘." Copilot은 채팅 기록이 아닌, 진행 상황 차트, 결정 위원회, 그리고 즉시 보낼 수 있는 이메일을 반환합니다.

실제 운영 캐비닛: 상단에는 비서실장(Chief of Staff)이 있고, 그 아래로 GTM, RevOps, 엔지니어링 포드(pods)가 배치됩니다. 12명의 지정된 운영자, 하나의 차트, 명확한 책임 소재.

복잡한 워크플로우(예: 엔터프라이즈 딜 자격 검증)는 오른쪽에 스팬 트리(span tree)와 함께 엔드 투 엔드(end-to-end)로 실행됩니다. 실행 과정은 반복 가능하며 검사할 수 있습니다.

테넌트 한도, 팀별 한도, 에이전트 및 모델별 지출 내역을 확인하세요. 월말에 예상치 못한 비용이 발생하는 일은 없습니다.

플랫폼은 핵심 운영체제와 함께 배포됩니다. 새로운 영역(영업, 지원, 재무)은 서명된 .hebbsmod 패키지 형태로 제공됩니다.

클릭 한 번으로 CRM 모듈이 설치됩니다. 파이프라인 (Pipeline), 딜 (Deals), 연락처 (Contacts), 기업 (Companies)이 왼쪽 네비게이션에 즉시 나타나며, 이제 조직은 영업 접점 (sales surface)을 갖게 됩니다.

이사회 수준의 가시성: 모든 지정된 계정, 모든 가치, 모든 소유자, 모든 단계. CEO가 이사회 회의 전에 열어보는 바로 그 뷰입니다.

페르소나 (Persona), 여정 (journey), 인식 (recognition), 알림 (alerts) (TPU v5, LangChain redlines), 출처가 명시된 인용문. AE (Account Executive)가 미팅 전에 실제로 읽게 되는 브리핑입니다.

리더십, 전략 변화, 자본 지출 (capex) 주기, 경쟁사의 움직임 — 임원이 이사회 회의실에 들어갈 때 들고 가는 계정 브리핑입니다.

"방금 GPT-5.5 이벤트에서 Sam Altman을 만났습니다 — OpenAI에 대해 우리가 가진 모든 것을 스캔하고 후속 조치 초안을 작성하세요." 단 한 번의 턴 (turn)으로 딜, 연락처, 서류 (dossiers), 편지함 전체를 아우릅니다. 그 응답은 채팅 기록이 아니라 링크와 결정 사항입니다.

에이전트의 프롬프트 (prompt)는 일반 데이터에서 가져온 두 개의 레지스트리 (registries)를 통해 구축됩니다 — 통합(integration)마다 수동으로 작성된 프로바이더 (providers)가 필요하지 않습니다.

기술 (Skills) — 모든 컴포넌트에서 제공되는 마크다운 (markdown) 파일 (SKILL.md). 에이전트의 프롬프트 내 ## Skills 섹션 아래로 로드됩니다. 에이전트에게 특정 도메인에 대해 생각하는 법을 가르칩니다.

도구 (Tools) — Zod 타입이 지정된 호출 가능한 연산 (callable operations). 모듈 (Modules)에 의해 등록되며, 하나의 URL로 디스패치 (dispatched)됩니다: POST /api/tools/<module>.<tool> 에이전트는 인벤토리 (inventory)를 읽고, 도구를 호출하며, 구조화된 에러와 함께 검증된 응답을 받습니다.

**모듈 (Module)**은 기술 + 도구 + (선택적으로) 스키마 (schema), UI, 기본 워크플로우 (default workflows), 기본 에이전트 (default agents), 루틴 (routines), OAuth, 웹훅 (webhooks)을 하나로 묶습니다. 세 가지 역할이 있으며 형태는 동일합니다:

커넥터 (Connector) — 제3자 API를 중개합니다 (connector-google, connector-slack)
역량 (Capability) — 다른 모듈에 의존하는 순수 로직입니다 (triage, prevent-churn)
하이브리드 (Hybrid) — 자체 데이터와 도구를 소유합니다 (crm, inbox)

모두 동일한 방식으로 등록됩니다: app.module(myModule). Notion을 추가하는 것은 하나의 모듈 패키지일 뿐이며, 프레임워크 수정은 전혀 필요하지 않습니다.

이 리포지토리를 클론한 환경 내에서 Open Cursor (또는 Claude Code, Codex, Gemini와 같은 모든 에이전트 기반 CLI)를 열고 다음과 같이 말해보세요:

"내 로컬호스트(localhost)에 boringos 쉘을 배포해줘 (deploy boringos shell on my localhost)\

에이전트가 의존성(dependencies)을 설치하고, 워크스페이스(workspace)를 빌드하며, 임베디드 Postgres를 부팅하고, http://localhost:3000에서 쉘(shell)을 시작합니다.

.

git clone https://github.com/BoringOS-dev/boringos.git
cd boringos
pnpm install
...

그 다음 http://localhost:3000을 여세요.

.

npx create-boringos my-app
cd my-app && pnpm install && pnpm dev

또는 인라인(inline)으로 연결할 수 있습니다:

import { BoringOS } from "@boringos/core";
import { z } from "@boringos/module-sdk";
import type { Module } from "@boringos/module-sdk";
...

임베디드 Postgres가 자동으로 부팅되며, 툴 디스패처(tool dispatcher)가 /api/tools/*에 마운트(mount)됩니다. 또한 에이전트의 프롬프트(prompt)에는 이제 hello 스킬(skill)과 hello.greet 툴(tool)이 포함됩니다.

단계별 가이드는 BUILD-A-MODULE.md를 참조하세요.

@boringos/connector-google 모듈(Module)은 OAuth 클라이언트(client)가 필요합니다. Google Cloud Console에서 2분 정도 설정한 뒤, 두 개의 환경 변수(env vars)를 입력하면 됩니다.

프로젝트 생성(또는 기존 프로젝트 선택).
API 활성화—APIs & Services → Library

• Gmail API
• Google Calendar API

OAuth 동의 화면(OAuth consent screen)—APIs & Services → OAuth consent screen

• 사용자 유형(User type):
  External (또는 Workspace 사용자인 경우 Internal)
• Testing 상태인 동안 테스트 사용자로 본인의 이메일을 추가하세요.
• 다음 스코프(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

OAuth 2.0 클라이언트 생성—APIs & Services → Credentials → Create credentials → OAuth client ID

• 애플리케이션 유형(Application type):
  Web application
• 승인된 JavaScript 출처(Authorized JavaScript origins):
  http://localhost:3000
• 승인된 리디렉션 URI(Authorized redirect URIs):
  http://localhost:3000/api/connectors/oauth/google/callback
• Client ID와 Client secret을 복사하세요.

이 값들을 레포지토리(repo) 루트의 .env.local 파일에 넣으세요:

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
# Connector SDK v2 자격 증명 암호화(credential encryption)를 위해 필요합니다.
...

pnpm dev를 재시작하세요.

, 셸의 Connectors 화면으로 이동하여,
Connect Google을 클릭하고 OAuth 흐름을 완료하세요. 이제 해당 테넌트(tenant)의 모든 에이전트(agent)가 Gmail 및 Calendar 도구를 사용할 수 있습니다.

프로덕션 호스트(production hosts)의 경우, 위에서 언급된 모든 http://localhost:3000을 공개 오리진(public origin)으로 교체하고 OAuth 동의 화면을 게시하세요.

모듈 (Module)	도구 (Tools)	비고 (Notes)
framework	tasks.{read,create,patch}, comments.post, work_products.record, runs.report_cost, agents.{create,list,wake}, inbox.{read,update}	에이전트의 유니버설 콜백 API (universal callback API)
memory	memory.{remember,recall,prime,forget}	장기 메모리 (Hebbs 또는 null)
drive	drive.{read,write,write_binary,list,delete,stat,move}	경로 접두사 ACL이 적용된 파일 스토리지 (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 런타임 + 시각적 에디터 (visual editor)

@boringos/connector-google — Gmail (send, search, read, archive) + Calendar
@boringos/connector-slack — 메시지, 스레드, 리액션 (messages, threads, reactions)

여섯 가지 플러거블 CLI 런타임(pluggable CLI runtimes)이 기본 제공됩니다: Claude Code, ChatGPT CLI, Gemini, Ollama, 일반 명령(generic command), 웹훅(webhook).

• 기본적으로 임베디드 Postgres 사용; DATABASE_URL을 통해 외부 연결 가능
• Drizzle ORM
• Hono HTTP 서버
• 기본적으로 인프로세스 작업 큐(In-process job queue) 사용; app.queue(...)를 통해 BullMQ 사용

wake (comment / routine / event / admin)
→ coalesce + enqueue
→ fetch agent + create run row
...

모든 사이드 이펙트(side effect)는 하나의 URL을 통과하며, 하나의 스키마(schema)에 의해 검증되고, 하나의 테이블에서 감사(audit)됩니다.

BUILD-A-MODULE.md — 첫 번째 모듈을 출시하기 위한 단계별 가이드 (대시보드 위젯 + 라이트/다크 테마 지원 포함)
MODULES.md — 모든 UI 출시 모듈이 따라야 하는 --bos-* 테마 계약을 포함한 모듈 매니페스트 사양 (Module manifest spec)
TOOLS.md — 도구 사양(Tool spec), 에러 모델(error model), 감사(audit), 멱등성(idempotency)
SKILLS.md

— Skill 사양 (Skill spec), 파일 형식 (file format), 우선순위 (priorities)
CLAUDE.md

— 기여자(contributors)를 위한 오리엔테이션 (orientation for contributors)
docs/install-flow.md

— 모듈(Modules)이 패키징, 업로드, 테넌트별 설치(per-tenant installation) 및 삭제되는 방식
docs/INDEX.md

— 전체 문서 탐색 (full doc navigation)

패키지 (Package)	역할 (Role)
@boringos/core	BoringOS 호스트 (host), 빌더 API (builder API), HTTP 라우트 (HTTP routes), 모듈 레지스트리 (Module registries)
@boringos/module-sdk	모듈 (Module) / 도구 (Tool) / 스킬 (Skill) 타입 SDK (사양)
@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) + 임베디드 Postgres (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	타입 지정 API 클라이언트 (Typed API client) + React 훅 (hooks)
create-boringos	CLI 생성기 (generator)
@boringos/shared	기본 타입 (Base types), 상수 (constants), 유틸리티 (utilities)

examples/quickstart/

— 부팅 (boot), 에이전트 생성 (create an agent), 작업 할당 (assign a task), 실행 감시 (watch it execute)

pnpm install
pnpm -r build
pnpm -r typecheck
...

BoringOS는 3계층 라이선스 레이아웃을 사용합니다:

프레임워크 (Framework) (아래 두 가지를 제외한 packages/@boringos/ 하위의 모든 것) — AGPL-3.0-or-later. 강력한 네트워크 카피레프트 (network copyleft): 수정된 버전을 서비스로 운영하는 누구라도 변경 사항을 공개해야 합니다.
— @boringos/module-sdk
LGPL-3.0-or-later. 링크 예외 (Linking exception) 조항에 따라 모듈은 어떤 라이선스 하에서도 SDK를 임포트(import)할 수 있습니다.
— @boringos/shared
Apache-2.0. 순수 타입/유틸리티 (Pure types/utilities)이며, 허용적(permissive)이어서 무엇이든 이에 의존할 수 있습니다.

루트 LICENSE 파일은 AGPL 텍스트를 보유하고 있습니다. 짧은 인덱스는 LICENSE.md를, 더 자세한 근거는 docs/licensing.md를 참조하십시오.

기여를 환영합니다 — CONTRIBUTING.md를 참조하십시오.