Quick Start

Get BlackRoad OS running in your environment.

Prerequisites

• Node.js 22+
• npm or yarn
• A running gateway instance

Install the CLI

npm install -g @blackroad/operator

# Verify installation
br --version
br helpCopy

Configure

# Set gateway URL
br config set gatewayUrl http://127.0.0.1:8787

# Set default agent
br config set defaultAgent octavia

# Verify connectivity
br gateway healthCopy

First Commands

# Check system status
br status

# List available agents
br agents

# Invoke an agent
br invoke octavia "run diagnostics"

# Search the knowledge base
br search-all "NATS configuration"Copy

Installation

Detailed setup for both TypeScript and Shell CLIs.

TypeScript CLI

git clone https://github.com/blackboxprogramming/blackroad-operator.git
cd blackroad-operator
npm install
npm run build
npm linkCopy

Shell CLI

chmod +x br
./br help
export PATH="$HOME/blackroad-operator:$PATH"Copy

Environment Variables

Variable	Default	Description
BLACKROAD_GATEWAY_URL	http://127.0.0.1:8787	Gateway endpoint
BLACKROAD_GATEWAY_PORT	8787	Gateway port
MCP_BRIDGE_TOKEN	—	Bearer token for MCP bridge
DEBUG	0	Enable debug logging

System Architecture

How BlackRoad OS is designed.

High-Level Architecture

                    +------------------+
                    |   Cloudflare     |
                    |  95+ Pages       |
                    |  40 KV, 8 D1    |
                    |  10 R2, 18 tun  |
                    +--------+---------+
                             |
              +--------------+--------------+
              |       WireGuard Mesh         |
              |     anastasia hub 10.8.0.x   |
              +--+------+------+------+--+---+
                 |      |      |      |  |
            +----+  +---+  +--+  +---+ +-+---+
            |Alice| |Cec.| |Oct.||Aria| |Luc.|
            |.49  | |.96 | |.101||.98 | |.38 |
            +-----+ +----+ +----++----+ +----+Copy

Tokenless Gateway

Agents never embed API keys. All LLM provider communication flows through the gateway.

[Agent CLIs] ---> [Gateway :8787] ---> [Ollama / Claude / OpenAI / Gemini]
                        |
                  Permission Matrix (agent-permissions.json)Copy

Agent Communication

# NATS subjects
agent.octavia.task     # Task assignment
agent.octavia.status   # Status updates
fleet.heartbeat        # Fleet-wide heartbeat
mesh.broadcast         # Broadcast to all agentsCopy

Memory System

Persistent memory via SQLite with FTS5. 156,675 entries across 228 databases.

• Journal + Chain — action logging
• Codex — solutions and patterns database
• TIL Broadcast — share learnings
• Task Marketplace — claimable tasks
• FTS5 Indexer — unified search + knowledge graph

Gateway

The tokenless gateway is the security boundary for all AI provider calls.

Providers

Provider	File	Endpoint
Ollama	providers/ollama.js	Local :11434
Anthropic	providers/anthropic.js	api.anthropic.com
OpenAI	providers/openai.js	api.openai.com
Gemini	providers/gemini.js	generativelanguage.googleapis.com

Configuration

cd blackroad-core/gateway
node server.js
curl http://127.0.0.1:8787/v1/healthCopy

Memory System

Persistent memory across sessions using SQLite and FTS5.

Core Scripts

Script	Purpose	Key Commands
memory-system.sh	Journal + chain	status, summary, log
memory-codex.sh	Solutions DB	search, stats, add-solution
memory-infinite-todos.sh	Long-running projects	list, show, add-todo
memory-task-marketplace.sh	Claimable tasks	list, claim, complete
memory-til-broadcast.sh	Share learnings	broadcast, list, search
memory-indexer.sh	FTS5 search	search, rebuild, patterns
memory-security.sh	Agent identity	status, identity, audit

Unified Search

br search-all "NATS configuration"
~/blackroad-operator/tools/search/index-all.py rebuildCopy

REST API

Gateway REST API for agent invocation and system health.

Endpoints

Method	Path	Description
GET	/v1/health	Health check
GET	/v1/agents	List agents
POST	/v1/invoke	Invoke agent

Health Check

curl http://127.0.0.1:8787/v1/health

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 86400,
  "agents": 5,
  "gateway": "tokenless"
}Copy

Invoke Agent

curl -X POST http://127.0.0.1:8787/v1/invoke \
  -H "Content-Type: application/json" \
  -d '{"agent": "octavia", "task": "run diagnostics"}'

{
  "agent": "octavia",
  "result": "All systems operational...",
  "duration_ms": 1240
}Copy

MCP Bridge API

Method	Path	Description
GET	/	Service info
GET	/system	System status
POST	/exec	Execute command
POST	/file/read	Read file
POST	/file/write	Write file
POST	/memory/write	Store key-value
POST	/memory/read	Retrieve key-value
GET	/memory/list	List memory keys

Agent API

Programmatic agent invocation and management.

List Agents

curl http://127.0.0.1:8787/v1/agents

{
  "agents": [
    {"name": "octavia", "role": "architect", "status": "active"},
    {"name": "lucidia", "role": "dreamer", "status": "active"},
    {"name": "alice", "role": "operator", "status": "active"},
    {"name": "aria", "role": "interface", "status": "active"},
    {"name": "shellfish", "role": "hacker", "status": "idle"}
  ]
}Copy

CLI Agent Commands

br agents
br agents --json
br invoke octavia "deploy to production"
br invoke lucidia "generate creative brief"
br invoke alice "check fleet health"Copy

Search API

Full-text search across all knowledge.

Unified Search

# CLI
br search-all "NATS configuration"

# REST
curl https://search.blackroad.io/api/search?q=NATS+configurationCopy

Index Sources

23 indexers, 28 entity types, 1,383 entries: codex, TILs, journal, websites, repos, agents, wiki, scripts, domains, docs, and more.

Fleet Nodes

5 Raspberry Pi compute nodes form the edge fleet.

Node	IP	Role	Hardware
Alice	.49	Gateway, DNS, Database	Pi-hole, PostgreSQL, Qdrant
Cecilia	.96	AI Inference	16 Ollama, Hailo-8 (26T)
Octavia	.101	Gitea, Docker Swarm	207 repos, Hailo-8 (26T)
Aria	.98	Frontend, UX	Web serving
Lucidia	.38	Web Apps, CI	334 apps

Network

WireGuard mesh networking.

WireGuard Mesh

# Hub: anastasia (DigitalOcean NYC1)
# Subnet: 10.8.0.x / Port: 51820
wg show
ping 10.8.0.1Copy

SSH Access

Node	Users	Sudo
Alice	alice, pi	NOPASSWD
Cecilia	cecilia, blackroad	NOPASSWD
Octavia	pi	NOPASSWD
Lucidia	pi, octavia	NOPASSWD

Services

All services running across the fleet.

Service	Node	Port
Gitea	Octavia	3100
Ollama	Cecilia	11434
Qdrant	Alice	6333
PostgreSQL	Alice	5432
NATS	Multiple	4222
Pi-hole	Alice	80
AI Gateway	Fleet	7000
WireGuard	anastasia	51820

Cloudflare Resources

• 95+ Pages
• 40 KV namespaces
• 8 D1 databases
• 10 R2 buckets
• 18 tunnels
• 20 domains

Agent System

Autonomous agents with identity, communication, and coordination.

How Agents Work

1. Identity — manifest with name, role, capabilities
2. Communication — NATS pub/sub messaging
3. Coordination — task marketplace
4. Memory — persistent SQLite FTS5
5. Gateway — tokenless AI provider access

Agent Lifecycle

agents/
  active/      # Currently running
  idle/        # Available
  processing/  # Working on tasks
  archive/     # Completed runsCopy

Core Agents

The five core agents.

Agent	Role	Description
Octavia	The Architect	Systems design, strategy
Lucidia	The Dreamer	Creative vision, education
Alice	The Operator	DevOps, automation
Aria	The Interface	Frontend, UX
Shellfish	The Hacker	Security, exploits

Invoking Agents

br invoke octavia "design the new auth system"

curl -X POST http://127.0.0.1:8787/v1/invoke \
  -d '{"agent": "octavia", "task": "design auth"}'

nats pub agent.octavia.task '{"task": "design auth"}'Copy

Agent SDK

Build and deploy your own agents.

Agent Manifest

{
  "name": "my-agent",
  "role": "custom",
  "capabilities": ["code", "search", "deploy"],
  "gateway": "http://127.0.0.1:8787",
  "nats": "nats://127.0.0.1:4222",
  "memory": "~/.blackroad/my-agent.db"
}Copy

Shell Agent Template

#!/bin/bash
set -e
AGENT_NAME="my-agent"
GATEWAY="http://127.0.0.1:8787"

curl -s -X POST "$GATEWAY/v1/agents/register" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"$AGENT_NAME\", \"role\": \"custom\"}"

nats sub "agent.$AGENT_NAME.task" | while read -r msg; do
  echo "Received task: $msg"
doneCopy

Security Model

Tokenless architecture with audit and permissions.

Principles

• Tokenless — agents never embed API keys
• Permission Matrix — agent-permissions.json
• Audit Trail — every action logged
• Localhost Binding — gateway on 127.0.0.1
• Bearer Auth — MCP bridge requires tokens

Verify No Leaked Tokens

./blackroad-core/scripts/verify-tokenless-agents.shCopy

Authentication

JWT-based auth via auth.blackroad.io.

• Endpoint: auth.blackroad.io
• Users: 42 registered
• Method: JWT tokens
• Storage: D1 (Cloudflare)

MCP Bridge Auth

export MCP_BRIDGE_TOKEN="your-token-here"
curl http://127.0.0.1:8420/system \
  -H "Authorization: Bearer $MCP_BRIDGE_TOKEN"Copy

Contributing

How to contribute to BlackRoad OS.

Development Setup

git clone https://github.com/blackboxprogramming/blackroad-operator.git
cd blackroad-operator
npm install && npm run build
npm test
npm run formatCopy

Adding a CLI Command

1. Create src/cli/commands/my-cmd.ts
2. Register in src/cli/commands/index.ts
3. Add tests in test/

Adding a Tool

1. Create tools/my-tool/br-my-tool.sh
2. Add route to br dispatcher
3. chmod +x

Code Style

Conventions for BlackRoad OS code.

TypeScript

// Copyright (c) 2025-2026 BlackRoad OS, Inc. All Rights Reserved.
import { Command } from 'commander'

export const myCommand = new Command('my-cmd')
  .description('Do something')
  .action(async () => {
    console.log('done')
  })Copy

Shell

#!/bin/zsh
# Copyright (c) 2025-2026 BlackRoad OS, Inc. All Rights Reserved.
GREEN='\033[0;32m'; RED='\033[0;31m'; NC='\033[0m'
DB_FILE="$HOME/.blackroad/my-tool.db"

case "$1" in
    list) sqlite3 "$DB_FILE" "SELECT * FROM items;" ;;
    *) echo "Usage: br my-tool [list]" ;;
esacCopy