docs: deployment guide from Camellia experience

DEPLOYING.md

@@ -0,0 +1,155 @@
+# Deploying nanobot
+
+How I run on Camellia (NixOS VM, but most steps are distro-agnostic).
+
+## 1. Prerequisites
+
+- Python 3.11+ and `uv`
+- A Telegram bot token from [@BotFather](https://t.me/BotFather)
+- An OpenRouter API key (or other LLM provider)
+- systemd (Linux) or launchd (macOS) for service management
+
+## 2. Install
+
+```bash
+git clone https://github.com/HKUDS/nanobot.git ~/nanobot-src
+cd ~/nanobot-src
+uv sync
+```
+
+## 3. Configure
+
+Run the onboarding wizard:
+
+```bash
+uv run nanobot onboard
+```
+
+This creates `~/.nanobot/config.json`. Key settings:
+
+- **model**: `deepseek/deepseek-v4-pro` via OpenRouter
+- **Telegram token**: from BotFather
+- **Workspace**: `~/.nanobot/workspace` (holds SOUL.md, USER.md, memory, skills)
+
+If behind a proxy, set it in your shell rc (`http_proxy`, `https_proxy`, `all_proxy`) — nanobot picks these up. For Telegram specifically, you can set `socks5://...` in the channel config.
+
+## 4. Install as a systemd user service
+
+```bash
+uv run nanobot gateway install-service
+```
+
+This creates `~/.config/systemd/user/nanobot.service` with `Restart=always`.
+
+Enable lingering so the user service survives logout:
+
+```bash
+loginctl enable-linger $USER
+```
+
+## 5. Workspace files
+
+After first run, populate the workspace:
+
+- **SOUL.md** — assistant personality, rules, guardrails
+- **USER.md** — user profile, timezone, interests
+- **memory/MEMORY.md** — long-term memory (system details, quirks, timeline)
+
+These are managed by Dream (the background memory agent), but seed them initially.
+
+## 6. NixOS notes (if applicable)
+
+Add to `configuration.nix`:
+
+```nix
+# FHS symlinks some tools expect
+systemd.tmpfiles.rules = [
+  "L+ /bin/bash - - - - ${pkgs.bash}/bin/bash"
+  "L+ /usr/bin/env - - - - ${pkgs.coreutils}/bin/env"
+];
+
+# Needed for uv/Python
+environment.systemPackages = with pkgs; [ python313 uv git ];
+```
+
+Use `/run/wrappers/bin/sudo` instead of the default `/run/current-system/sw/bin/sudo` (the default lacks setuid).
+
+## 7. Hardening
+
+```bash
+# Firewall: allow only needed ports
+# SSH (22), HTTP (80), gateway health (18790), WebSocket (8765)
+
+# fail2ban for SSH
+# Kernel: syncookies=1, rp_filter=1, accept_redirects=0, kptr_restrict=1
+
+# Swap: at least 2 GB to survive memory pressure
+# earlyoom: prevents OOM killer from taking down the assistant
+```
+
+## 8. Watchdog
+
+systemd `Restart=always` + `RestartSec=5s` handles crashes. Additionally, a systemd timer pings the gateway health endpoint every 60s and restarts if dead.
+
+Create `~/.config/systemd/user/nanobot-watchdog.service` and `.timer`:
+
+```ini
+# nanobot-watchdog.service
+[Service]
+Type=oneshot
+ExecStart=/run/wrappers/bin/systemctl --user start nanobot
+```
+
+```ini
+# nanobot-watchdog.timer
+[Timer]
+OnUnitActiveSec=60s
+[Install]
+WantedBy=timers.target
+```
+
+## 9. Rollback safety
+
+Always deploy from a git checkout so you can revert:
+
+```bash
+cd ~/nanobot-src
+git checkout known-good  # or any known-working commit
+systemctl --user restart nanobot
+```
+
+Tag working versions with `git tag -f known-good` after verifying.
+
+## 10. Session recovery
+
+nanobot persists `pending_user_turn` and `runtime_checkpoint` markers per session. On startup after a crash, `recover_stale_sessions()`:
+
+- Sends a "🔄 nanobot was restarted" notification
+- Re-triggers interrupted turns automatically
+
+Graceful shutdowns (SIGTERM) clear these markers — only crashes trigger recovery.
+
+## 11. Verify
+
+```bash
+# Check gateway is running
+systemctl --user status nanobot
+
+# Check logs
+journalctl --user -u nanobot -f
+
+# Health check
+curl http://localhost:18790/api/health
+```
+
+## TL;DR checklist
+
+- [ ] Python + uv installed
+- [ ] `git clone` + `uv sync`
+- [ ] `uv run nanobot onboard`
+- [ ] Populate workspace (SOUL.md, USER.md, MEMORY.md)
+- [ ] `uv run nanobot gateway install-service`
+- [ ] `loginctl enable-linger $USER`
+- [ ] Firewall, swap, earlyoom
+- [ ] Watchdog timer
+- [ ] Tag working version: `git tag known-good`