fireclaw/README.md

# 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