BlackRoad OS Documentation
The operating system for the AI age — where software adapts to humans, not the other way around.
What is BlackRoad OS?
BlackRoad OS is a governance and orchestration platform for AI agents. It provides:
- Governance Layer — Policies, audit trails, and permission management for AI operations
- Agent Orchestration — Coordinate multiple AI agents across tools and workflows
- Six Portals — Integrated experiences for personal AI, education, media, gaming, navigation, and privacy
Core Components
| Component | Purpose |
|---|---|
| Cece | Lucidia-class governance agent — the brain of BlackRoad |
| Policies | Rules that allow, deny, or modify AI actions |
| Ledger | Immutable audit trail of all governance events |
| Intents | Task and workflow state management |
| Claims & Delegations | Identity and permission management |
Documentation Structure
Vision & Strategy
- Manifesto — Why BlackRoad exists
- Vision & Mission — 5-year roadmap and success metrics
- Architecture — System design and component overview
Governance Layer
- Cece Agent Mode — System prompt for the governance agent
- Governance Roadmap — Sprint plan and implementation details
Technical Reference
- KV Schema — Data model for governance objects
- API Design — REST API specification
Operations
- Getting Started — Quick start guides
- Runbooks — Operational procedures
- Platform Guides — Deployment and configuration
Repository Map
| Repo | Purpose |
|---|---|
blackroad-os-docs |
Documentation (this repo) |
blackroad-os-core |
Desktop UI, auth, identity |
blackroad-os-api |
API gateway, REST endpoints |
blackroad-os-operator |
Job scheduler, background workers |
blackroad-os-agents |
Agent implementations |
blackroad-os-infra |
IaC, deployment configs |
blackroad-os-web |
Web frontend |
blackroad-os-prism-console |
Admin dashboard |
lucidia-core |
AI reasoning engines |
Quick Start
Prerequisites
- Node.js 20+ (see
package.jsonengines) - npm or pnpm for dependency management
Running locally
npm install
npm run start
The dev server runs at http://localhost:3000.
Building for production
npm run build
npm run serve
The Six Portals
| Portal | Domain | Description |
|---|---|---|
| Lucidia | Personal AI | Your AI that actually knows you — persistent memory, learned preferences |
| RoadWork | Education | Adaptive learning that evolves with your understanding |
| RoadView | Media | Video and image creation without the learning curve |
| RoadGlitch | Gaming | Games that evolve with your play style |
| RoadWorld | Navigation | Context-aware guidance with local knowledge |
| BackRoad | Privacy | Security and anonymization as infrastructure |
Implementation Status
Phase 1: Foundation (Current)
- Governance layer specification
- KV schema design
- API design
- Core implementation
- Agent bootstrap
Phase 2: Portals
- Lucidia MVP
- RoadWork prototype
- RoadView alpha
Phase 3: Ecosystem
- Developer SDK
- Agent marketplace
- Enterprise features
See IMPLEMENTATION-ROADMAP.md for full task tracking.
Contributing
Keep content concise, link across sections, and prefer iterative updates over monolithic rewrites. Mark components as planned, alpha, or in-flight when appropriate so operators, developers, and partners have an honest view of the system.
See CONTRIBUTING.md for style conventions, validation steps, and how to extend the sidebar when adding new pages.
Links
- Website: blackroad.io
- Docs: docs.blackroad.io
- GitHub: github.com/BlackRoad-OS
The road is long. The road is black. But we're building it together.