The Nest
Explore
0
README.md

🦆🐸 Toaducken

A duck stuffed inside a toad. The duck inhabits the toad.

The duck inhabits the toad. First TUI experience for Vers VMs with ACP (Agent Client Protocol) support.

Quick Start

# One command - duck handles everything
just duck

# Or directly
bb toaducken/duck.bb

Testing

1. Local Duckhole Server

just duck serve
# Opens http://localhost:8080 - Duckhole web portal

2. Connect to VM with API Keys

# Shows detected API keys, passes them to VM, shows Toad banner
just duck <vm-id>

# Example
just duck 6a4ede1d

3. List VMs

just duck vms

4. Query DuckDB

just duck query "SELECT * FROM vm_inventory LIMIT 5"

5. Build Toad ACP Image

just duck build
# Builds toad-acp:latest using Apple container CLI

6. Register with Chelsea

export VERS_API_KEY=<your-key>
just duck register
# Registers toad-acp as custom base image

API Keys Detected

Duck automatically detects and passes these to VMs:

  • OPENAI_API_KEY
  • ANTHROPIC_API_KEY
  • GOOGLE_API_KEY
  • MISTRAL_API_KEY
  • GROQ_API_KEY
  • ELEVENLABS_API_KEY
  • VERS_API_KEY
  • ... and more

7. Carnage (delete all VMs)

just duck carnage
# 🦆💀 Deletes ALL VMs - use with care

Files

| File | Purpose | |------|---------| | duck.bb | Main entry point - the duck decides its form | | vers-duckhole.bb | Web server for DuckDB conversation viewer | | Duckerfile | Minimal Fedora image with Toad + Codex + WireGuard |

Architecture

just duck → duck.bb
              │
              ├── (no args) → Connect to VM with Toad banner + API keys
              ├── serve     → Start duckhole web server
              ├── vms       → Query VM inventory from DuckDB
              ├── query     → SQL across conversation history
              ├── build     → Build toad-acp container image
              └── register  → Register with Chelsea API

ACP Integration

Toad serves ACP on port 9000 inside the VM:

# From inside VM or via tunnel
curl -X POST http://localhost:9000 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Interaction Pattern

  1. Local: just duck detects API keys locally
  2. Inject: Keys passed to VM via vers execute
  3. Connect: SSH to VM with Toad as first experience
  4. ACP: Toad serves ACP endpoint for agent communication

Requirements

  • bb (Babashka)
  • vers CLI
  • DuckDB (for queries)
  • API keys in environment (optional but recommended)