Introduction
BlackRoad OS is a distributed operating system for autonomous agents, designed to run on edge hardware you own and control.
Prerequisites
You'll need at least one Raspberry Pi 5 (4GB+), a microSD card, and a network connection to get started.
Installation
Install the BlackRoad CLI to bootstrap your first node. The installer handles all dependencies automatically.
bash
curl -fsSL https://install.blackroad.io | bash
brctl init --node alice
brctl status
Architecture overview
BlackRoad OS consists of three layers: the mesh network (WireGuard), the service orchestrator (Docker Swarm), and the intelligence layer (Ollama + Hailo).
| Layer | Technology | Purpose |
|---|---|---|
| Network | WireGuard | Encrypted mesh between all nodes |
| Orchestration | Docker Swarm | Service deployment and scaling |
| Intelligence | Ollama | Local LLM inference |
| Acceleration | Hailo-8 | 52 TOPS neural compute |
Configuration
Each node is configured through a YAML file that defines its role, services, and network settings.
yaml
node:
name: alice
role: gateway
network:
wireguard:
address: 10.8.0.6/24
listen_port: 51820
services:
- pihole
- postgresql
- cloudflared
Important
Never expose WireGuard private keys in version control. Use environment variables or a secrets manager.
Next steps
- Set up your first node with the Quick Start guide
- Learn about the mesh network architecture
- Configure AI inference with Ollama and Hailo-8