🦞 red-larvae

Ephemeral, disposable OpenClaw agents in Docker containers. Spawn them, give them a task, talk to them, kill them — their work persists after death.

Larvae are baby lobsters. They hatch, do their thing, and the results survive even after the container is gone.

Forked from clawd-larvae — adapted for the RedBotster ecosystem.

Quick Start

# 1. Build the larva image
docker build -t larva .

# 2. Spawn a larva
./larvae.sh spawn alice --model sonnet "Build a REST API for a todo app"

# 3. Talk to it (it remembers context)
./larvae.sh talk alice "Add authentication middleware"
./larvae.sh talk alice "Now write tests for everything"

# 4. Check on it
./larvae.sh status alice
./larvae.sh list

# 5. Kill it (files persist!)
./larvae.sh kill alice

# 6. Your code is still here
ls shared-workspace/alice/

How It Works

┌──────────────────────────────────────────┐
│  Host Machine (macOS/Linux)              │
│                                          │
│  larvae.sh orchestrator                  │
│    ├── spawn: docker run → larva container
│    ├── talk:  docker exec → openclaw agent
│    ├── list:  show all running larvae    │
│    ├── kill:  docker stop (files stay)   │
│    └── status: health + workspace files  │
│                                          │
│  shared-workspace/                       │
│    ├── alice/    ← volume mount          │
│    ├── bob/      ← volume mount          │
│    └── charlie/  ← volume mount          │
│                                          │
│  ┌────────────┐  ┌────────────┐          │
│  │ larva-alice │  │ larva-bob  │  ...     │
│  │ (Docker)    │  │ (Docker)   │          │
│  │             │  │            │          │
│  │ OpenClaw    │  │ OpenClaw   │          │
│  │ Gateway     │  │ Gateway    │          │
│  │ + Agent     │  │ + Agent    │          │
│  │             │  │            │          │
│  │ /root/wksp  │  │ /root/wksp │          │
│  │  ↕ volume   │  │  ↕ volume  │          │
│  └────────────┘  └────────────┘          │
└──────────────────────────────────────────┘

Each larva is a Docker container running an OpenClaw gateway. The larvae.sh orchestrator:

1. Spawns a container with a volume-mounted workspace directory
2. Talks to the agent inside via docker exec openclaw agent
3. Files persist in shared-workspace/<name>/ on the host even after the container is killed

The agent inside each container has full OpenClaw capabilities: file read/write, shell exec, web search, browser, etc. It's a complete AI coding agent in a box.

Models

Use any model — cloud APIs or local Ollama:

Shortcut	Model	Notes
opus	anthropic/claude-opus-4-6	Most capable, $$
sonnet	anthropic/claude-sonnet-4-5	Fast + smart (default)
gpt	openai/gpt-5.2	OpenAI flagship
qwen	ollama/qwen3-next:80b	Local, free
devstral	ollama/devstral:latest	Local, code-focused
deepseek	ollama/deepseek-r1:70b	Local, reasoning
llama	ollama/llama3.3:latest	Local, general
coder	ollama/qwen2.5-coder:32b	Local, code-focused

# Cloud models (need API keys)
./larvae.sh spawn smart-worker --model opus "Architect a microservices system"

# Local models (need Ollama running on host)
./larvae.sh spawn local-worker --model coder "Refactor this Python module"

# Full model strings work too
./larvae.sh spawn custom --model anthropic/claude-sonnet-4-5 "Do something"

ethskills Integration

By default, every larva fetches the complete ethskills.com knowledge base at spawn time and bakes it into its context. This means the larva doesn't just know about Ethereum — it has internalized ethskills as core knowledge before it ever processes your first command.

What happens at spawn:

1. All 17 ethskills SKILL.md files are fetched in parallel (~190KB total)
2. They're assembled into ETHSKILLS.md in the larva's workspace
3. ETHSKILLS.md is injected into the agent's system prompt via projectContext
4. A default SOUL.md is written with non-negotiable rules to follow ethskills exactly

The result: the larva uses Scaffold-ETH 2, follows the phase system, uses the correct file paths, and doesn't improvise when ethskills gives explicit instructions.

# Default: ethskills baked in
./larvae.sh spawn token-dev --model opus "Build a RED token dashboard dApp on Base"

# Custom SOUL on top of ethskills
./larvae.sh spawn my-dev --model sonnet --soul roles/security-auditor.md

# Non-ETH tasks: skip ethskills
./larvae.sh spawn scraper --model gpt --no-ethskills "Scrape Hacker News"

Commands

./larvae.sh spawn <name> [options] "task"
  --model <m>         Model shortcut or full provider/model string
  --workspace <dir>   Custom workspace directory
  --soul <file>       Custom SOUL.md for personality/role
  --profile <p>       Agent profile (builder, auditor, qa, frontend, all)
  --no-ethskills      Skip baking ethskills (for non-ETH tasks)

./larvae.sh list
./larvae.sh talk <name> "message"
./larvae.sh watch <name> "message"
./larvae.sh status <name>
./larvae.sh logs <name> [lines]
./larvae.sh kill <name>
./larvae.sh killall

Requirements

• Docker
• API key(s) as environment variables:
  • ANTHROPIC_API_KEY — for Claude models
  • OPENAI_API_KEY — for GPT models
  • Ollama models connect to host.docker.internal:11434 (Ollama running on host)

Custom Workspace

Point a larva at any directory on your machine:

# Work on the RedBotster project directly
./larvae.sh spawn reviewer --model sonnet --workspace ~/RedBotster "Review the fee-claim-and-buy.sh script for bugs"

# The larva can read/write files in ~/RedBotster
./larvae.sh talk reviewer "What did you find? Any issues with the swap logic?"

Multi-Larva Workflows

Spawn multiple larvae for parallel or collaborative work:

# Architect designs, coder implements, reviewer checks
./larvae.sh spawn architect --model opus "Design a DeFi treasury dashboard"
./larvae.sh spawn coder --model sonnet "Implement the Uniswap integration"
./larvae.sh spawn reviewer --model sonnet "Review the code for security issues"

# Check on everyone
./larvae.sh list

# Kill them all when done
./larvae.sh killall

How OpenClaw Orchestrates Larvae

The parent OpenClaw instance (the one you're chatting with) can spawn and manage larvae on your behalf. Just say:

"Spawn a larva named alice on sonnet to build a REST API" "Check on alice" "Tell bob to add unit tests" "Kill all larvae"

The parent runs larvae.sh commands via shell exec and relays the results back to you.

Architecture

• Image: larva — Node 22 slim + OpenClaw pre-installed (~200MB)
• Config: openclaw.json baked into image, model overridden at spawn time
• Networking: Each larva gets a unique host port (28700+) mapped to internal port 18789
• Storage: Volume mount from shared-workspace/<name>/ → /root/workspace
• Communication: docker exec openclaw agent --local with session persistence
• Isolation: Each container is fully isolated with its own filesystem, processes, and network

Related

• RedBotster — AI DeFi treasury bot on Base
• clawd-larvae — Original upstream project
• OpenClaw — AI agent runtime

License

MIT