# Headscale — Hive Mode coordination server

Self-hosted Tailscale control server for **LLMHosts Phase 3: Hive Mode**. Provides the mesh coordination plane so Hive members’ nodes can discover and reach each other over WireGuard.

## Quick start

```bash
cd infrastructure/headscale
docker compose up -d
```

- **Control plane**: http://127.0.0.1:8080  
- **Metrics**: http://127.0.0.1:9090/metrics  

## Create a user and pre-auth key (for LLMHosts nodes)

```bash
# Create a Headscale user (e.g. one per Hive or per member)
docker compose exec headscale headscale users create hive-alice

# Create a pre-auth key so nodes can join without interactive login
docker compose exec headscale headscale preauthkeys create --user hive-alice --reusable --expiration 24h

# List nodes
docker compose exec headscale headscale nodes list
```

Nodes (Tailscale clients) join with:

```bash
tailscale up --login-server=http://127.0.0.1:8080 --authkey=<key>
```

## Production

1. **Server URL**: Set `server_url` in `config/config.yaml` to your public URL (e.g. `https://headscale.llmhosts.com`). Clients must reach this URL to register.
2. **TLS**: Configure Let’s Encrypt in `config.yaml` (`tls_letsencrypt_hostname`, `acme_email`) or set `tls_cert_path` / `tls_key_path`.
3. **ACLs**: LLMHosts syncs per-Hive ACLs (same-Hive-only traffic, no cross-Hive) when `HEADSCALE_ACL_PATH` is set to the policy file (e.g. `config/acls.hujson`). Headscale has no policy REST API in v0.22 — policy is file-based. After `llmhosts hive create|join|leave`, the CLI writes the generated ACL to that path; reload Headscale so it picks up changes.

## How LLMHosts uses Headscale

- **Phase 3 Hive Mode**: Each Hive member runs a Tailscale client pointed at this Headscale instance. Nodes get Tailscale IPs and can reach each other for proxy traffic.
- **LLMHosts integration** (to be wired in `llmhost/hive/` and tunnel): On `llmhosts hive create` / `llmhosts hive join`, the CLI will use Headscale’s gRPC or HTTP API to create users and pre-auth keys, and instruct the user to run `tailscale up --login-server=... --authkey=...`.
- **ADR-004**: Headscale is used for Hive only. Personal remote access (Phase 2) stays on Tailscale/Cloudflare; Hive mesh uses this coordination server.

## Files

| Path | Purpose |
|------|--------|
| `docker-compose.yml` | Headscale service and volumes |
| `config/config.yaml` | Server, DNS, DB, TLS, policy path |
| `config/acls.hujson` | Tailscale ACL (MVP: allow all within tailnet) |

## References

- [Headscale docs](https://headscale.net/)
- [Tailscale ACL](https://tailscale.com/kb/1018/acls/)
- `docs/knowledge-base/hive-mode.md` — Hive architecture
- `docs/roadmap/detailed.md` — Phase 3 Week 15–16
