Revert "docs: deployment guide from Camellia experience"
Test Suite / Detect changes (push) Has been cancelled
Test Suite / Python (Windows, 3.14) (push) Has been cancelled
Test Suite / Python (minimum, 3.11) (push) Has been cancelled
Test Suite / Python (latest, 3.14 + coverage) (push) Has been cancelled
Test Suite / webui (push) Has been cancelled
Test Suite / docker (push) Has been cancelled
Test Suite / Detect changes (push) Has been cancelled
Test Suite / Python (Windows, 3.14) (push) Has been cancelled
Test Suite / Python (minimum, 3.11) (push) Has been cancelled
Test Suite / Python (latest, 3.14 + coverage) (push) Has been cancelled
Test Suite / webui (push) Has been cancelled
Test Suite / docker (push) Has been cancelled
This reverts commit ded5d4d8ed.
This commit is contained in:
nanobot
-155
@@ -1,155 +0,0 @@
|
|||||||
# 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`
|
|
||||||
Reference in New Issue
Block a user