Initial commit — fireclaw multi-agent system
Firecracker microVM-based multi-agent system with IRC orchestration and local LLMs. Features: - Ephemeral command runner with VM snapshots (~1.1s) - Multi-agent orchestration via overseer IRC bot - 5 agent templates (worker, coder, researcher, quick, creative) - Tool access (shell + podman containers inside VMs) - Persistent workspace + memory system (MEMORY.md pattern) - Agent hot-reload (model/persona swap via SSH + SIGHUP) - Non-root agents, graceful shutdown, crash recovery - Agent-to-agent communication via IRC - DM support, /invite support - Systemd service, 20 regression tests Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
251
README.md
Normal file
251
README.md
Normal file
@@ -0,0 +1,251 @@
|
||||
# Fireclaw
|
||||
|
||||
Multi-agent system powered by Firecracker microVMs. Each AI agent runs in its own hardware-isolated VM, connects to IRC, and responds via local LLMs.
|
||||
|
||||
## What it does
|
||||
|
||||
**Command runner:** Execute arbitrary commands in ephemeral microVMs with KVM isolation.
|
||||
|
||||
```
|
||||
$ fireclaw run "uname -a"
|
||||
Linux 172.16.0.200 5.10.225 #1 SMP x86_64 Linux
|
||||
```
|
||||
|
||||
**Multi-agent system:** Spawn AI agents as long-running VMs. Each agent connects to IRC, responds via Ollama, has tool access, and remembers across restarts.
|
||||
|
||||
```
|
||||
# In IRC (#control):
|
||||
<human> !invoke worker
|
||||
<overseer> Agent "worker" started: worker [qwen2.5:7b] (172.16.0.2)
|
||||
|
||||
# In IRC (#agents):
|
||||
<human> worker: what's your uptime?
|
||||
<worker> System has been up for 3 minutes with load average 0.00.
|
||||
|
||||
# Private message:
|
||||
/msg worker hello
|
||||
<worker> Hey! How can I help?
|
||||
|
||||
# Hot-reload model:
|
||||
<human> !model worker phi4-mini
|
||||
<worker> [reloaded: model=phi4-mini]
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
grogbox host
|
||||
├── fireclaw overseer systemd service, IRC bot in #control
|
||||
├── Ollama 0.0.0.0:11434, 5 models available
|
||||
└── nyx.fireclaw.local ngircd IRC server (FireclawNet)
|
||||
|
||||
Firecracker VMs (fcbr0 bridge, 172.16.0.0/24)
|
||||
├── worker (172.16.0.2) general assistant in #agents
|
||||
├── coder (172.16.0.3) code-focused agent in #agents
|
||||
└── research (172.16.0.4) research agent in #agents
|
||||
```
|
||||
|
||||
Each agent VM:
|
||||
- Runs a Python IRC bot (stdlib only, zero deps)
|
||||
- Connects to nyx.fireclaw.local at 172.16.0.1:6667
|
||||
- Calls Ollama at 172.16.0.1:11434 for LLM responses
|
||||
- Has tool access — shell commands + podman containers
|
||||
- Has persistent workspace at `/workspace` (survives restarts)
|
||||
- Has persistent memory — saves/loads facts across restarts
|
||||
- Accepts `/invite` to join any channel
|
||||
- Responds to DMs without mention
|
||||
- Runs as unprivileged `agent` user
|
||||
- Is fully isolated from the host and other agents
|
||||
|
||||
## Requirements
|
||||
|
||||
- Linux with KVM (`/dev/kvm`)
|
||||
- Firecracker v1.15+ at `/usr/local/bin/firecracker`
|
||||
- `sudo` access (for tap devices, rootfs mounting)
|
||||
- Node.js 20+
|
||||
- Ollama (for LLM responses)
|
||||
- ngircd (for IRC)
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
cd ~/projects/fireclaw
|
||||
npm install
|
||||
npm run build
|
||||
sudo npm link
|
||||
|
||||
# One-time setup
|
||||
fireclaw setup
|
||||
fireclaw snapshot create
|
||||
|
||||
# Start the overseer (or use systemd)
|
||||
sudo systemctl start fireclaw-overseer
|
||||
|
||||
# Connect to IRC and start spawning agents
|
||||
# irssi -c localhost -n human
|
||||
# /join #control
|
||||
# !invoke worker
|
||||
# /join #agents
|
||||
# worker: hello!
|
||||
```
|
||||
|
||||
## IRC Channel Layout
|
||||
|
||||
| Channel | Purpose |
|
||||
|---|---|
|
||||
| `#control` | Overseer commands only (!invoke, !destroy, !list, etc.) |
|
||||
| `#agents` | Common room — all agents join here |
|
||||
| `/msg <nick>` | Private DM with an agent (no mention needed) |
|
||||
| `/invite <nick> #room` | Pull an agent into any channel |
|
||||
|
||||
## CLI Reference
|
||||
|
||||
```
|
||||
fireclaw run [options] "<command>" Run a command in an ephemeral microVM
|
||||
-t, --timeout <seconds> Command timeout (default: 60)
|
||||
-v, --verbose Show boot/cleanup progress
|
||||
--no-snapshot Force cold boot
|
||||
|
||||
fireclaw overseer [options] Start the overseer daemon
|
||||
--server <host> IRC server (default: localhost)
|
||||
--port <port> IRC port (default: 6667)
|
||||
--nick <nick> Bot nickname (default: overseer)
|
||||
--channel <chan> Control channel (default: #control)
|
||||
|
||||
fireclaw agent start <template> Start an agent VM
|
||||
--name <name> Override agent name
|
||||
--model <model> Override LLM model
|
||||
|
||||
fireclaw agent stop <name> Stop an agent VM
|
||||
fireclaw agent list List running agents
|
||||
fireclaw snapshot create Create VM snapshot for fast restores
|
||||
fireclaw setup One-time setup
|
||||
```
|
||||
|
||||
## IRC Commands (via overseer in #control)
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `!invoke <template> [name]` | Spawn an agent VM |
|
||||
| `!destroy <name>` | Kill an agent VM (graceful IRC QUIT) |
|
||||
| `!list` | Show running agents |
|
||||
| `!model <name> <model>` | Hot-reload agent's LLM model |
|
||||
| `!templates` | List available agent templates |
|
||||
| `!help` | Show commands |
|
||||
|
||||
## Agent Templates
|
||||
|
||||
Templates live in `~/.fireclaw/templates/`:
|
||||
|
||||
| Template | Nick | Model | Tools | Role |
|
||||
|---|---|---|---|---|
|
||||
| worker | worker | qwen2.5:7b | yes | General purpose |
|
||||
| coder | coder | qwen2.5-coder:7b | yes | Code-focused |
|
||||
| researcher | research | llama3.1:8b | yes | Thorough research |
|
||||
| quick | quick | phi4-mini | no | Fast one-liners (~5s) |
|
||||
| creative | muse | gemma3:4b | no | Writing, brainstorming |
|
||||
|
||||
## Available Models
|
||||
|
||||
| Model | Size | Speed (CPU) | Tools | Best for |
|
||||
|---|---|---|---|---|
|
||||
| qwen2.5-coder:7b | 4.7 GB | ~15s | yes | Code tasks |
|
||||
| qwen2.5:7b | 4.7 GB | ~15s | partial | General chat |
|
||||
| llama3.1:8b | 4.9 GB | ~15s | partial | Instruction following |
|
||||
| gemma3:4b | 3.3 GB | ~8s | no | Creative, balanced |
|
||||
| phi4-mini | 2.5 GB | ~5s | no | Fast, simple answers |
|
||||
|
||||
## Performance
|
||||
|
||||
| Mode | Time |
|
||||
|---|---|
|
||||
| Snapshot restore (ephemeral run) | ~1.1s |
|
||||
| Cold boot (ephemeral run) | ~2.9s |
|
||||
| Agent VM boot to IRC connect | ~5s |
|
||||
|
||||
## Security Model
|
||||
|
||||
- Agent processes run as unprivileged `agent` user inside VMs
|
||||
- Root SSH retained for overseer management only
|
||||
- Each VM gets hardware-level KVM isolation
|
||||
- Persistent workspace is per-agent — no cross-agent access
|
||||
- Overseer runs on host (trusted), agents in VMs (untrusted)
|
||||
- Agent-to-agent cooldown (10s) prevents infinite loops
|
||||
- Graceful shutdown — agents send IRC QUIT before VM kill
|
||||
|
||||
## Source Files
|
||||
|
||||
```
|
||||
src/
|
||||
index.ts Entry point
|
||||
cli.ts CLI commands (commander)
|
||||
vm.ts Ephemeral VM lifecycle (cold boot + snapshot)
|
||||
firecracker-api.ts Firecracker REST client
|
||||
snapshot.ts Snapshot creation workflow
|
||||
overseer.ts Overseer daemon (IRC + agent lifecycle)
|
||||
agent-manager.ts Start/stop/list/reload agent VMs
|
||||
network.ts Bridge, tap devices, IP allocation
|
||||
rootfs.ts Image copy, SSH key injection
|
||||
ssh.ts SSH execution (ssh2)
|
||||
cleanup.ts Signal handlers
|
||||
config.ts Constants, paths
|
||||
types.ts Interfaces
|
||||
setup.ts One-time setup
|
||||
|
||||
agent/
|
||||
agent.py Python IRC bot (stdlib only, baked into rootfs)
|
||||
|
||||
scripts/
|
||||
setup-bridge.sh Create fcbr0 bridge + NAT rules
|
||||
teardown-bridge.sh Remove bridge + NAT rules
|
||||
|
||||
tests/
|
||||
test-suite.sh Regression tests (20 tests)
|
||||
```
|
||||
|
||||
## Data Directory
|
||||
|
||||
```
|
||||
~/.fireclaw/
|
||||
vmlinux Firecracker kernel (5.10)
|
||||
base-rootfs.ext4 Alpine base (ephemeral runs)
|
||||
agent-rootfs.ext4 Agent image (1 GiB sparse, Alpine + Python + podman)
|
||||
snapshot-rootfs.ext4 Snapshot rootfs
|
||||
snapshot.{state,mem} VM snapshot
|
||||
id_ed25519[.pub] SSH keypair
|
||||
agents.json Running agent state
|
||||
templates/ Agent persona templates
|
||||
workspaces/ Persistent agent storage (64 MiB ext4 each)
|
||||
runs/ Per-agent rootfs copies
|
||||
ip-pool.json IP allocation
|
||||
```
|
||||
|
||||
### Agent Workspace (inside VM at /workspace)
|
||||
|
||||
```
|
||||
/workspace/
|
||||
MEMORY.md Memory index — loaded into system prompt
|
||||
memory/
|
||||
user_prefs.md Learned facts about users
|
||||
project_x.md Ongoing project context
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Requires overseer running via systemd
|
||||
./tests/test-suite.sh
|
||||
```
|
||||
|
||||
20 tests covering: overseer commands, agent lifecycle, IRC interaction, tool access, error handling, CLI operations, crash recovery, graceful shutdown.
|
||||
|
||||
## Known Limitations
|
||||
|
||||
- Snapshot mode doesn't support concurrent ephemeral runs (single fixed IP/tap)
|
||||
- `sudo` required for tap device and rootfs mount operations
|
||||
- CPU inference: 5-30s per response depending on model
|
||||
- No thin provisioning — full rootfs copy per agent (~146 MiB)
|
||||
|
||||
## License
|
||||
|
||||
Apache-2.0
|
||||
Reference in New Issue
Block a user