clawdie/clawdie-iso
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Align ISO config docs with post-install setup

Browse source
This commit is contained in:
Sam & Claude 2026-05-12 19:58:33 +02:00 • committed by 123kupola
parent 014edc1d9f
commit f81f487560
6 changed files with 113 additions and 154 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
build.cfg
View file

@ -33,7 +33,6 @@ IMAGE_SIZE="50G"
# post-install setup/token flow. Use --clawdie-version X.Y.Z for release builds.
CLAWDIE_VERSION="main"
CLAWDIE_REF="${CLAWDIE_REF:-main}"
CLAWDIE_TARBALL_URL="https://codeberg.org/Clawdie/Clawdie-AI/archive/${CLAWDIE_REF}.tar.gz"
# Default installer choices (can be overridden by setup.txt on the writable USB config partition)
DEFAULT_PKG_BRANCH="latest" # latest or quarterly
@ -53,7 +52,7 @@ AGENT_DOMAIN="${AGENT_DOMAIN:-}"
AGENT_GENDER="${AGENT_GENDER:-}"
TZ="${TZ:-}"
# LLM provider (default: zai with glm-5)
# LLM provider/model. Leave blank for post-install setup and Clawdie-AI profile defaults.
PI_TUI_PROVIDER="${PI_TUI_PROVIDER:-}"
PI_TUI_MODEL="${PI_TUI_MODEL:-}"
@ -62,7 +61,8 @@ ZAI_API_KEY="${ZAI_API_KEY:-}"
OPENROUTER_API_KEY="${OPENROUTER_API_KEY:-}"
ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-}"
# Embeddings (default: OpenRouter with bge-m3)
# Embeddings. Leave base URL blank to let Clawdie-AI choose OpenRouter when
# OPENROUTER_API_KEY is present, otherwise local llama-server.
EMBED_BASE_URL="${EMBED_BASE_URL:-}"
EMBED_MODEL="${EMBED_MODEL:-}"
EMBED_API_KEY="${EMBED_API_KEY:-}"

175
docs/VPS-MIGRATION.md
View file

@ -1,149 +1,76 @@
# Clawdie-VPS — Linux→FreeBSD Migration for VPS
# VPS / Cloud Deployment Notes
**Status:** Ready for testing — 2026-03-18
**Target:** Vultr, Hetzner, OVH, any VPS with custom ISO support
**Status:** experimental / legacy path. The primary validation target is the
unified ISO live installer. VPS/cloud deployment remains supported as a design
goal, but the scripts under `vps/` have not yet been brought fully in line with
the current post-install `/setup` flow.
Use this page as orientation, not as a release checklist.
---
## Quick Start (Vultr)
## Current Direction
### Step 1: Upload mfsBSD ISO
The target VPS flow should match the ISO contract:
1. Download mfsBSD ISO: https://depenguin.me/files/mfsbsd-15.0-RELEASE-amd64.iso
2. In Vultr panel: **Server → Settings → Custom ISO → Upload ISO**
3. Attach the ISO to your server
4. Reboot
1. install FreeBSD 15.x on the VPS,
2. copy the Clawdie firstboot payload,
3. boot into `clawdie-firstboot`,
4. run `just install`,
5. start the loopback-bound controlplane,
6. rotate a one-time setup token,
7. finish provider/model, Telegram, and operator account setup at `/setup`.
### Step 2: Boot and SSH
After reboot, the server boots into mfsBSD (FreeBSD in RAM):
```bash
ssh mfsbsd@<your-vps-ip>
# password: mfsroot
```
### Step 3: Run Installer
```bash
fetch -o - https://clawdie.si/vps-setup.sh | sh
```
Or with custom config:
```bash
fetch -o setup.sh https://clawdie.si/vps-setup.sh
# Edit ASSISTANT_NAME, AGENT_DOMAIN, TZ at the top
vi setup.sh
sh setup.sh
```
### Step 4: After Reboot
```bash
ssh clawdie@<your-vps-ip>
cd ~/clawdie-ai
just install
```
Done! Clawdie-AI is running on FreeBSD.
Provider keys and Telegram credentials are **not** install-time requirements.
They can be pre-baked only for controlled images, but the preferred path is
post-install setup.
---
## How It Works
## Existing Files
```text
vps/
├── setup.txt.tpl # current preferred config template shape
├── firstboot-vps.sh # legacy/experimental headless firstboot entrypoint
├── clawdie.conf.tpl # deprecated compatibility template
└── clawdie-vps-migrate.sh
```
Vultr VPS
└─ Boot from mfsBSD ISO (FreeBSD in RAM)
└─ SSH as mfsbsd
└─ Run clawdie-vps-setup.sh
├─ Partition disk (ZFS)
├─ Install FreeBSD base
├─ Configure system (users, network, TZ)
├─ Install packages (node24, git, tmux, etc.)
├─ Download Clawdie-AI from Codeberg
├─ Generate secrets + .env
└─ Reboot
Final boot from HDD
└─ FreeBSD + Clawdie-AI ready
└─ Run: just install
```
`setup.txt.tpl` now reflects the identity/substrate-first contract. The older
`clawdie.conf.tpl` path is deprecated.
---
## Provider Support
## Provider Notes
| Provider | Method | Difficulty | Notes |
|----------|--------|------------|-------|
| **Vultr** | Custom ISO | Easy ⭐ | Upload mfsBSD ISO directly |
| **Hetzner** | Rescue + depenguin.me | Medium | Use depenguin.me script first |
| **OVH** | Rescue mode | Medium | Same as Hetzner |
| **Hostinger** | Check panel | Unknown | Look for ISO upload or rescue |
| **DigitalOcean** | Recovery console | Hard | No ISO support, use depenguin.me |
---
## Configuration Options
Edit these at the top of `clawdie-vps-setup.sh`:
| Variable | Default | Description |
|----------|---------|-------------|
| `ASSISTANT_NAME` | Clawdie | Display name |
| `AGENT_NAME` | clawdie | System hostname (auto-derived) |
| `AGENT_DOMAIN` | clawdie.local | Domain name |
| `TZ` | UTC | Timezone (e.g., Europe/Ljubljana) |
| `PI_PROVIDER` | anthropic | LLM provider |
| `CLAWDIE_VERSION` | 0.8.2 | Clawdie-AI release |
---
## Files
```
clawdie-iso/vps/
├── clawdie-vps-setup.sh ← Main installer (runs on mfsBSD)
├── clawdie-vps-migrate.sh ← Linux→mfsBSD migration (for rescue mode)
├── clawdie.conf.tpl ← Headless config template
└── firstboot-vps.sh ← Alternative: interactive wizard
```
| Provider | Likely path | Status |
| ---------------- | ----------------------------------- | ------------ |
| Vultr | Custom ISO or mfsBSD rescue | experimental |
| Hetzner / OVH | Rescue shell then FreeBSD bootstrap | experimental |
| DigitalOcean | Recovery console / custom image | hard |
| Generic baremetal| Unified ISO live installer | primary |
---
## Security Notes
1. **Change mfsBSD password** after first SSH if concerned
2. **All secrets auto-generated** with 32-char random strings
3. **.env mode 600** — only clawdie user can read
4. **Wheel group has passwordless sudo** — change if desired
- Prefer Tailscale for remote SSH access when possible.
- If no Tailscale auth key is available, SSH on port 22 remains public and must
be secured by the operator.
- Do not expose `http://127.0.0.1:3100/setup` directly to the public internet.
Use console access or SSH tunneling:
---
## Troubleshooting
### SSH connection refused
- Wait 30-60 seconds after reboot for mfsBSD to start
- Check Vultr console for boot progress
### Disk not detected
- Check with: `sysctl kern.disks`
- Manually set: `DISK=/dev/da0 ./clawdie-vps-setup.sh`
### Install fails
- Check internet: `fetch http://example.com`
- Check logs in `/var/log/install.log`
---
## Alternative: Build Custom ISO
For fully offline installs, you can build a custom mfsBSD ISO with Clawdie pre-bundled:
```bash
cd clawdie-iso
./build-vps.sh
# Output: tmp/output/clawdie-vps-DD.mmm.YYYY.iso
```sh
ssh -L 3100:127.0.0.1:3100 clawdie@<host>
```
This requires more setup and is optional — the script approach above is simpler.
---
## Cleanup Needed Before Release
- Reconcile `firstboot-vps.sh` with the current ISO live firstboot contract.
- Remove the deprecated `clawdie.conf.tpl` path after migration is complete.
- Add a real VPS validation run to `TESTING.md` once the path is exercised.
**Last updated:** 12.maj.2026

18
firstboot/MODULE-MANIFEST.md
View file

@ -42,8 +42,8 @@
**Wizard Inputs:** None
**Outputs (Exports):**
- `ASSISTANT_NAME`, `HOSTNAME`, `AGENT_DOMAIN`, `TZ`
- `OPENROUTER_API_KEY`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_ADMIN_ID`
- identity/substrate values: `ASSISTANT_NAME`, `HOSTNAME`, `AGENT_DOMAIN`, `TZ`
- optional pre-baked provider/channel values, if present for backward compatibility
- `ZFS_POOL`, `ZFS_LAYOUT`, `ZFS_DATA_DISKS`, `ZFS_HOT_SPARES`, `ZFS_PREFIX`
- optional hardware hints from `system.env`
@ -52,7 +52,7 @@
**Skip Condition:**
- no `CLAWDIE` FAT32 partition found
- or `setup.txt` missing
- or one of the three required bootstrap keys is blank
- or identity/substrate values are incomplete for the non-interactive path
**Error Handling:**
- safe-fail back to wizard
@ -89,13 +89,13 @@
- `TZ` — Timezone (e.g., "Europe/Ljubljana")
**Wizard Inputs (Tier 2 - Optional):**
- `LLM_PROVIDER` — default: "anthropic"
- `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc. — API keys (optional)
- `TELEGRAM_BOT_TOKEN` — Telegram integration (optional)
- Provider/model values — normally configured after first boot in `/setup`
- Provider API keys — optional backward-compatible pre-bake only
- Telegram credentials — optional backward-compatible pre-bake only
**Outputs (Created):**
- `$ENV_FILE` — `/home/clawdie/.env` (chmod 600)
- Contains: identity + feature flags from the firstboot wizard
- Contains: identity + feature flags from the live installer handoff or fallback wizard
- Copied into: `/home/clawdie/clawdie-ai/.env` by shell-deploy (1.6)
- Completed by: Clawdie-AI onboarding (secrets + derived defaults)
@ -609,7 +609,7 @@ Use this manifest to:
3. **Handle wizard tiers:**
- Tier 1 (required): ASSISTANT_NAME, AGENT_DOMAIN, TZ
- Tier 2 (optional): LLM_PROVIDER, API keys, Telegram token
- Tier 2 (optional): provider/model and Telegram values for backward-compatible pre-bake
4. **Define checkpoint names** for progress tracking
@ -617,7 +617,7 @@ Use this manifest to:
## Version History
- **v1.0.2** (current): 12 modules, ZFS/desktop/npm-globals, bundled npm CLIs
- **current dev ISO**: live QML installer, post-install setup token, 12 shell modules, ZFS/desktop/npm-globals, bundled npm CLIs
- **v0.9.0**: 8 modules, runtime GPU detection, no ZFS/desktop/npm-globals
- **v0.5.0**: 6 modules, PF firewall, glasspane VNC support
- **v1.1 (planned):** Add shell-gpu-passthrough.sh, add shell-upgrade.sh

4
firstboot/integration-test.sh
View file

@ -83,7 +83,7 @@ touch "$LOG_FILE" "$PROGRESS_FILE" "$RC_CONF" "$LOADER_CONF" "$SYSCTL_CONF"
echo ""
echo "╔════════════════════════════════════════════════════════════════╗"
echo "║ Clawdie Shell v1.0.2 Integration Test ║"
echo "║ Clawdie Shell Integration Test ║"
echo "║ 8-module sequential execution (cloud/VM scenario) ║"
echo "╚════════════════════════════════════════════════════════════════╝"
echo ""
@ -159,7 +159,7 @@ echo "║ System State: ║"
[ -d "$CLAWDIE_AI_DIR" ] && echo "║ Clawdie-AI: deployed ║" || echo "║ Clawdie-AI: MISSING ║"
echo "║ ║"
echo "║ GPU Support (v1.0.2): ║"
echo "║ GPU Support: ║"
echo "║ ✓ Intel integrated (i915kms) ║"
echo "║ ✓ AMD AMDGPU ║"
echo "║ ✓ VESA fallback ║"

40
firstboot/shell-env.sh
View file

@ -100,11 +100,10 @@ clawdie_shell_env_append_new_keys() {
fi
}
# Keys added in v0.10.x / v1.0.0 that older installs may not have
# Keys added in v0.10.x / v1.0.0 that older installs may not have.
# Do not append provider/model defaults here; Clawdie-AI resolves those at
# runtime unless the operator explicitly configures them.
_env_append_if_missing "DB_RUNTIME" '"jail"'
_env_append_if_missing "EMBED_BASE_URL" '"https://openrouter.ai/api/v1"'
_env_append_if_missing "EMBED_MODEL" '"BAAI/bge-m3"'
_env_append_if_missing "EMBED_API_KEY" '""'
_env_append_if_missing "EMBED_DIMENSIONS" '"1024"'
_env_append_if_missing "LOCAL_LLM_PROVIDER" '"none"'
_env_append_if_missing "FEATURE_OLLAMA" '"NO"'
@ -146,6 +145,29 @@ clawdie_shell_env_write_file() {
cp_secret=$(openssl rand -base64 32)
auth_secret=$(openssl rand -base64 32)
# Provider/model are intentionally unset by default; Clawdie-AI resolves the
# recommended runtime profile and post-install setup writes the operator's
# chosen provider. Embeddings follow the Clawdie-AI default: OpenRouter only
# when an OpenRouter key exists, otherwise local llama-server.
local pi_tui_provider pi_tui_model embed_base_url embed_model embed_api_key
pi_tui_provider="${PI_TUI_PROVIDER:-}"
pi_tui_model="${PI_TUI_MODEL:-}"
if [ -n "${EMBED_BASE_URL:-}" ]; then
embed_base_url="$EMBED_BASE_URL"
elif [ -n "${OPENROUTER_API_KEY:-}" ]; then
embed_base_url="https://openrouter.ai/api/v1"
else
embed_base_url="http://localhost:8080/v1"
fi
embed_model="${EMBED_MODEL:-BAAI/bge-m3}"
if [ -n "${EMBED_API_KEY:-}" ]; then
embed_api_key="$EMBED_API_KEY"
elif [ "$embed_base_url" = "https://openrouter.ai/api/v1" ]; then
embed_api_key="${OPENROUTER_API_KEY:-}"
else
embed_api_key=""
fi
# Remove existing .env if present
rm -f "$ENV_FILE" 2>/dev/null || true
@ -174,8 +196,8 @@ SYSTEM_LOCALE="$SYSTEM_LOCALE"
KEYMAP="$KEYMAP"
# === LLM Provider ===
PI_TUI_PROVIDER="${PI_TUI_PROVIDER:-zai}"
PI_TUI_MODEL="${PI_TUI_MODEL:-glm-5}"
PI_TUI_PROVIDER="$pi_tui_provider"
PI_TUI_MODEL="$pi_tui_model"
ZAI_API_KEY="${ZAI_API_KEY:-}"
ZAI_API_BASE="${ZAI_API_BASE:-https://api.z.ai/api/coding/paas/v4}"
OPENROUTER_API_KEY="${OPENROUTER_API_KEY:-}"
@ -183,9 +205,9 @@ ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-}"
CLAUDE_CODE_OAUTH_TOKEN="${CLAUDE_CODE_OAUTH_TOKEN:-}"
# === Embeddings ===
EMBED_BASE_URL="${EMBED_BASE_URL:-https://openrouter.ai/api/v1}"
EMBED_MODEL="${EMBED_MODEL:-BAAI/bge-m3}"
EMBED_API_KEY="${EMBED_API_KEY:-}"
EMBED_BASE_URL="$embed_base_url"
EMBED_MODEL="$embed_model"
EMBED_API_KEY="$embed_api_key"
EMBED_DIMENSIONS="${EMBED_DIMENSIONS:-1024}"
# === Database ===

24
vps/setup.txt.tpl
View file

@ -1,14 +1,13 @@
# setup.txt — Headless VPS installation config
# Copy to /usr/local/share/clawdie-iso/setup.txt before running firstboot-vps.sh
#
# This is the same first-boot setup contract used by the USB installer.
OPENROUTER_API_KEY=
TELEGRAM_BOT_TOKEN=
TELEGRAM_ADMIN_ID=
# Provider keys and Telegram are no longer required at install time. Configure
# them after first boot through the Clawdie setup page unless you deliberately
# want to pre-bake credentials for a controlled image.
ASSISTANT_NAME=Clawdie
HOSTNAME=clawdie
AGENT_DOMAIN=clawdie.home.arpa
TIMEZONE=UTC
INSTALL_MODE=fresh
@ -18,7 +17,18 @@ ZFS_DATA_DISKS=1
ZFS_HOT_SPARES=0
ZFS_PREFIX=clawdie-runtime
# Optional
# Optional access
# SSH_AUTHORIZED_KEY=ssh-ed25519 AAAA...
# CLAWDIE_USER_PASSWORD=
# Optional pre-baked provider/channel credentials (prefer post-install /setup)
# OPENROUTER_API_KEY=
# OPENAI_API_KEY=
# ANTHROPIC_API_KEY=
# ZAI_API_KEY=
# TELEGRAM_BOT_TOKEN=
# TELEGRAM_ADMIN_ID=
# Optional locale
# SYSTEM_LOCALE=en_US.UTF-8
# KEYMAP=us
# SSH_AUTHORIZED_KEY=ssh-ed25519 AAAA...