clawdie-iso/REQUIREMENTS.md

# Clawdie ISO Requirements

Build and deployment requirements for the current unified Clawdie ISO.

---

## Quick Checklist

Before building:

- [ ] FreeBSD 15.0+ build host
- [ ] 150 GB free build space recommended
- [ ] 64 GB USB key minimum (`IMAGE_SIZE=50G`)
- [ ] Internet access for fetch phase
- [ ] root or `sudo` for image assembly
- [ ] optional Tailscale auth key for secure remote access

Before installing:

- [ ] Target disk selected and safe to erase
- [ ] Operator SSH public key available, if using key auth
- [ ] Tailscale auth key available, if remote first setup should be tailnet-only
- [ ] Provider/model choice ready for post-install `/setup`

---

## Build Host Requirements

### Operating System

- FreeBSD 15.0+
- ZFS recommended for comfortable build storage, but not required by `build.sh`

### Packages

Install the baseline tools:

```sh
sudo pkg install -y curl node24 npm-node24 qt6-base qt6-declarative qt6-buildtools sudo
```

`build.sh` sets its own FreeBSD tool PATH:

```text
/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
```

This keeps fetch/build behavior independent from the invoking user's login PATH.

### Disk Space

| Item                         | Typical size |
| ---------------------------- | ------------ |
| FreeBSD memstick cache       | ~2 GB        |
| Offline pkg repository       | varies       |
| Clawdie-AI offline tarball   | varies       |
| Working image                | 50 GB sparse |
| Output image                 | 50 GB sparse |

Recommended free space: **150 GB**.

### USB Key

| USB size | Image size | Status      |
| -------- | ---------- | ----------- |
| 64 GB    | 50 GB      | minimum     |
| 128 GB   | 100 GB     | recommended |
| 256 GB   | 200 GB     | comfortable |

Do not use a USB key smaller than the logical image size printed by `build.sh`.

---

## Network Requirements

### During Build

Outbound access:

- HTTPS/HTTP to FreeBSD package mirrors
- HTTPS to Codeberg for Clawdie-AI tarballs
- HTTPS to npm registry for bundled npm CLI tarballs

Inbound access: none.

### During Install / First Boot

Tailscale is recommended but optional.

With a Tailscale auth key:

- first boot joins the tailnet
- PF allows SSH on `tailscale0`
- public SSH is blocked after Tailscale is authenticated
- operator reaches setup through SSH tunneling to host loopback

Without a Tailscale auth key:

- install still proceeds
- public SSH on port 22 remains available
- operator is responsible for network exposure and SSH hardening

The controlplane setup page should be reached locally or through a tunnel:

```sh
ssh -L 3100:127.0.0.1:3100 clawdie@<host>
```

Then open:

```text
http://127.0.0.1:3100/setup
```

Do not expose port `3100` directly on the public internet.

---

## Target Machine Requirements

### Minimum Runtime Hardware

| Component | Minimum | Recommended | Notes                         |
| --------- | ------- | ----------- | ----------------------------- |
| CPU       | 4 cores | 4+ cores    | More helps jail provisioning  |
| RAM       | 8 GB    | 16 GB+      | ZFS + jails + Chromium        |
| Disk      | 50 GB   | 100 GB+     | More for datasets and caches  |
| Network   | 1 NIC   | 1 Gbps      | Needed for remote operation   |

Local AI models require substantially more disk/RAM and are optional.

### Display

The live installer uses a graphical Lumina/QML session. Headless/server flows
are still under active validation; use bhyve/console access for testing.

---

## Tailscale Auth Key

Generate a key at:

```text
https://login.tailscale.com/admin/settings/keys
```

Recommended options:

- reusable key for repeated test installs
- expiration appropriate for the test window
- optional tag if your tailnet policy uses tags

Export before build if you want it baked into the image environment:

```sh
export TAILSCALE_AUTHKEY="tskey-auth-..."
```

You can also enter/paste the key in the live installer if the UI path exposes it
for that build.

---

## Post-Install Setup Requirements

Provider keys and Telegram are no longer install-time requirements.

After first boot, the installed system creates a one-time bootstrap token at:

```text
/var/db/clawdie-installer/setup-token
```

Use it at:

```text
http://127.0.0.1:3100/setup
```

Recommended provider path:

- Pi `/login` with Codex/OpenAI subscription auth

Peer supported options include OpenAI API, Anthropic, z.ai, OpenRouter, Gemini,
Groq, DeepSeek, Azure OpenAI, Ollama, and other Pi-supported providers.

Telegram setup is optional and happens after a provider is configured.

---

## Build Commands

```sh
# full validation build
sudo ./build.sh

# fetch-only cache refresh
./build.sh --fetch-only

# assemble cached inputs
sudo ./build.sh --skip-fetch

# release build from a pinned Clawdie-AI tag
BUILD_CHANNEL=release sudo ./build.sh --clawdie-version 0.10.0
```

---

## Common Problems

| Symptom                                      | Likely cause                         | Fix                                      |
| -------------------------------------------- | ------------------------------------ | ---------------------------------------- |
| missing package archive                      | stale `tmp/packages` cache           | run `sudo ./build.sh`                    |
| `pkg` not found in normal shell              | user PATH lacks `/usr/local/sbin`    | update PATH; build script already guards |
| cannot attach md device                      | not root / stale md device           | run with sudo; clean stale mdconfig      |
| setup page unreachable remotely              | no tunnel / PF boundary              | use SSH tunnel to `127.0.0.1:3100`       |
| no Tailscale key                             | optional remote-access choice        | continue with public SSH or rebuild      |

---

**Last updated:** 12.maj.2026