# 🦆🐸 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

```bash
# One command - duck handles everything
just duck

# Or directly
bb toaducken/duck.bb
```

## Testing

### 1. Local Duckhole Server

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

### 2. Connect to VM with API Keys

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

# Example
just duck 6a4ede1d
```

### 3. List VMs

```bash
just duck vms
```

### 4. Query DuckDB

```bash
just duck query "SELECT * FROM vm_inventory LIMIT 5"
```

### 5. Build Toad ACP Image

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

### 6. Register with Chelsea

```bash
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)

```bash
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:

```bash
# 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)