← Back to Dashboard

Hive

Multi-tenant VM hosting platform. Users get full Alpine Linux VMs via Telegram and Solana payments.

Quick Start

Build

make build

Configure (environment variables or config file)

export TELEGRAM_BOT_TOKEN="your-token"

export SOLANA_RPC="mainnet"

Or use config file as first argument

Run (requires root for TAP networking)

sudo ./hive

Access admin dashboard at `http://localhost:49160` (deployed at `https://krons.cx/hive`)

What It Does

• Users send `/start` to Telegram bot, pay with SOL, receive a full VM
• VMs are real QEMU/KVM virtual machines with root access
• Each VM includes: Go, Node.js, Python 3.14, Bun, Caddy, vim, tmux, ripgrep, fzf
• takopi and Claude CLI pre-installed for AI agent workflows
• Browser-based terminal via WebSocket proxy with login shell (auto-loads PATH)
• Credential updates pushed to running VMs without restart
• Real-time SSE updates to dashboard and notification banners
• Agent health checking for accurate VM state (booting vs running)

VM Environment

Alpine Linux 3.21 with:

• Languages: Go, Node.js (npm), Python 3.14 (uv), Bun
• Tools: git, vim, tmux, htop, ncdu, jq, yq, ripgrep, fd, fzf, bat
• Build: gcc, make, build-base, sqlite-dev
• Network: curl, wget, netcat, socat, tcpdump
• Web: Caddy (file server from /, WebDAV write access to /root)
• Platform: takopi, claude-code, wscat, pnpm
• Claude CLI install retries on network errors

Configuration

| Variable | Default | Description |

|----------|---------|-------------|

| `ADDRESS` | `0.0.0.0:49160` | API listen address |

| `DATA_DIR` | `/srv/data/hive` | VM storage path |

| `SPOOL_DIR` | `/srv/spool/hive` | Download cache |

| `TELEGRAM_BOT_TOKEN` | Required | Platform bot token |

| `SOLANA_RPC` | `mainnet` | Solana RPC endpoint |

| `PAYMENT_AMOUNT` | `0.1` | SOL per VM |

See [internal/util/config.go](internal/util/config.go) for all options.

Deployment

Production deployment at `krons.cx/hive` uses nginx reverse proxy:

• All URLs respect `X-Forwarded-Prefix` header
• Frontend uses centralized `apiUrl()` helper for path construction
• Backend constructs URLs with prefix awareness
• WebSocket connections work through proxy

Local development runs on `localhost:49160` without prefix.

Networking

• Bridge: `br-hive` (10.1.0.1/16)
• DHCP via dnsmasq (10.1.0.10 - 10.1.255.254)
• TAP device per VM: `tap-{vmid[:8]}`
• MAC address: 52:54:XX:XX:XX:XX (deterministic from VM ID)
• SSH port forwarding: host:52301-52399 -> VM:22
• VMs reach internet via host NAT

API Endpoints

| Method | Path | Description |

|--------|------|-------------|

| `POST` | `/api/vm` | Create VM (auto-starts) |

| `GET` | `/api/vm` | List VMs (?archived=true/false) |

| `GET` | `/api/vm/{id}` | VM details |

| `DELETE` | `/api/vm/{id}` | Soft delete VM |

| `POST` | `/api/vm/{id}/start` | Start VM |

| `POST` | `/api/vm/{id}/stop` | Stop VM |

| `POST` | `/api/vm/{id}/archive` | Archive VM |

| `POST` | `/api/vm/{id}/unarchive` | Unarchive VM |

| `POST` | `/api/vm/{id}/config` | Update credentials (pushed to agent) |

| `GET` | `/api/vm/{id}/log` | Serial console log |

| `*` | `/api/vm/{id}/proxy/*` | HTTP/WS proxy to agent |

| `*` | `/api/vm/{id}/files/*` | Caddy file browser (entire filesystem) |

| `*` | `/api/vm/{id}/files/webdav/root/*` | WebDAV write access to /root |

| `GET` | `/api/events` | SSE stream of VM events |

| `GET` | `/api/generate-name` | Generate artist-themed name |

| `GET` | `/health` | Health check |

WebSocket terminal: `ws://localhost:49160/api/vm/{id}/proxy/v1/shell` (login shell for PATH)

WebSocket Claude: `ws://localhost:49160/api/vm/{id}/proxy/v1/claude-stream`

Agent endpoints at `:11435` in each VM:

• `GET /status` - Health check with configured state
• `POST /restart` - Restart takopi service
• `POST /config` - Receive config updates from platform

Key Features

**Reverse Proxy Support**: Centralized API URL handling via `apiUrl()` helper respects `X-Forwarded-Prefix` header for deployment at `krons.cx/hive`. All fetch calls and WebSocket connections work transparently whether running locally or behind nginx.

**Agent Health Checking**: Platform queries agent `/status` endpoint to distinguish between booting (QEMU running but agent not ready) and running (fully operational) states.

**Login Shell**: WebSocket terminal spawns `bash -l` to automatically source `/etc/profile` and `/etc/profile.d/*`, ensuring tools like `uv`, `bun`, `g`, and npm globals are in PATH.

**File Access**: Caddy serves entire filesystem from `/` with browse enabled. WebDAV provides read-only access to all files, write access to `/root` only. Protected by HTTP Basic Auth when credentials configured.

**Event Notifications**: SSE events trigger UI notification banners in header (max 5, FIFO eviction). Auto-dismiss after timeout or manual close.

**Retry Logic**: Claude CLI installation retries once after 5s delay on network errors during VM provisioning.

Development

make build # Build api and agent

make test # Fast unit tests (<5s)

make smoke # Full e2e suite (~80s)

make lint # go vet, staticcheck

make fmt # go fmt

Testing

E2E Tests (193 comprehensive tests)

cd tests/web

npx playwright test # Run all tests

npx playwright test archive # Specific test file

npx playwright test --headed # With browser UI

npx playwright test --grep @slow # Only slow tests

Test suite covers:

• VM lifecycle (create, start, stop, archive, delete)
• Network allocation (TAP, DHCP, SSH ports)
• Configuration updates (Telegram, Claude, SSH, WebDAV)
• Agent behavior (polling, config push, service restart)
• UI integration (SSE events, WebSocket proxy, terminal)
• Error paths (timeouts, race conditions, disk errors)

See [tests/web/TEST_SUITE_SUMMARY.md](tests/web/TEST_SUITE_SUMMARY.md) for details.

Requirements

• Linux host with KVM support
• Root or CAP_NET_ADMIN for TAP networking
• Go 1.21+, QEMU, genisoimage
• Node.js (for Playwright tests)

Project Structure

cmd/hive/ API server entry point

internal/

├── util/ Configuration, name generation

├── vm/ VM lifecycle, networking, QEMU

├── platform/ User management, Telegram, payments, events

└── server/ HTTP handlers and routing

agent/ Guest agent (:11435 in each VM)

web/ Admin dashboard (htmx + xterm.js)

tests/ Integration and E2E tests

cloud-init.tmpl VM provisioning template

See [ARCHITECTURE.md](ARCHITECTURE.md) for system design, [CLAUDE.md](CLAUDE.md) for developer reference.