clawdie-iso/docs/VPS-MIGRATION.md

# VPS / Cloud Deployment Notes

**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.

---

## Current Direction

The target VPS flow should match the ISO contract:

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`.

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.

---

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

`setup.txt.tpl` now reflects the identity/substrate-first contract. The older
`clawdie.conf.tpl` path is deprecated.

---

## Provider Notes

| 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

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

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

---

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