diff --git a/agent/docs/install.md b/agent/docs/install.md
new file mode 100644
index 0000000..a98181a
--- /dev/null
+++ b/agent/docs/install.md
@@ -0,0 +1,104 @@
+# Agent Install (per Proxmox host)
+
+## Prerequisites on the Proxmox host
+
+- Proxmox VE 8.3+ (OpenZFS 2.3+ for the `-j` flags on `zpool`/`zfs`)
+- Root SSH access
+- Outbound HTTPS to the monitor server
+
+No Erlang or Elixir needed — the Burrito binary ships its own runtime.
+
+## 1. Build the binary (operator workstation)
+
+```bash
+cd proxmox_monitor/agent
+./scripts/build-linux.sh            # requires Docker
+ls dist/
+# proxmox-monitor-agent_linux_amd64
+# proxmox-monitor-agent_linux_arm64
+```
+
+## 2. Register the host in the dashboard
+
+From the dashboard at `https://monitor.example.com/admin/hosts`:
+
+1. "Register a new host" → enter the short name (e.g. `pve-host-01`).
+2. Copy the one-time token shown.
+
+## 3. Copy files to the Proxmox host
+
+```bash
+HOST=pve-host-01
+scp dist/proxmox-monitor-agent_linux_amd64 \
+    root@$HOST:/usr/local/bin/proxmox-monitor-agent
+ssh root@$HOST 'chmod 0755 /usr/local/bin/proxmox-monitor-agent'
+
+# systemd unit (included in the repo)
+scp rel/proxmox-monitor-agent.service \
+    root@$HOST:/etc/systemd/system/
+```
+
+## 4. Write the config
+
+On the Proxmox host:
+
+```bash
+install -d -m 0700 /etc/proxmox-monitor
+cat > /etc/proxmox-monitor/agent.toml <<EOF
+server_url = "wss://monitor.example.com/socket/websocket"
+token = "<paste-token-from-dashboard>"
+host_id = "pve-host-01"
+
+[intervals]
+fast_seconds = 30
+medium_seconds = 300
+slow_seconds = 1800
+EOF
+chmod 0600 /etc/proxmox-monitor/agent.toml
+```
+
+## 5. Enable the service
+
+```bash
+install -d -m 0700 /var/cache/proxmox-monitor-agent
+systemctl daemon-reload
+systemctl enable --now proxmox-monitor-agent
+journalctl -u proxmox-monitor-agent -f
+```
+
+Expected within ~10s:
+```
+agent: starting with host_id=pve-host-01
+reporter: connected, joining host:pve-host-01
+reporter: joined host:pve-host-01
+```
+
+The host's card on the dashboard should flip to `online`.
+
+## 6. Token rotation
+
+If a token leaks: dashboard → Admin → "Rotate". Copy the new token, update
+`/etc/proxmox-monitor/agent.toml` on the affected host, `systemctl restart
+proxmox-monitor-agent`. Old token is invalidated immediately.
+
+## 7. Upgrade flow
+
+```bash
+# operator
+./scripts/build-linux.sh
+scp dist/proxmox-monitor-agent_linux_amd64 root@$HOST:/usr/local/bin/proxmox-monitor-agent.new
+
+# on the host
+mv /usr/local/bin/proxmox-monitor-agent{.new,}
+systemctl restart proxmox-monitor-agent
+```
+
+## Troubleshooting
+
+| Symptom                                 | Check                                                           |
+|------------------------------------------|-----------------------------------------------------------------|
+| `enoent` errors for `zpool`/`pvesh`      | You're not on a Proxmox host, or binaries aren't in `$PATH`.    |
+| `handshake_failed: :nxdomain`            | DNS for the monitor hostname fails from this host.              |
+| `unknown_host` rejection on join          | Host name in `agent.toml` doesn't match the dashboard entry.    |
+| `invalid_token` rejection                 | Token was rotated; paste the new one.                           |
+| Agent reconnects every 30s                | Server's WebSocket timeout hit — check Caddy `read_timeout 90s`.|
diff --git a/docs/deployment-overview.md b/docs/deployment-overview.md
new file mode 100644
index 0000000..80e2b4f
--- /dev/null
+++ b/docs/deployment-overview.md
@@ -0,0 +1,51 @@
+# Deployment Overview
+
+Two artifacts, built independently, deployed independently.
+
+```
+                ┌─────────────────────────┐
+                │   Server (LXC in RZ)    │
+  agents ──WSS─>│  - Phoenix release      │
+                │  - SQLite               │
+                │  - Caddy (TLS)          │
+                └─────────────────────────┘
+                        ▲
+                        │ ssh
+                        │
+                ┌─────────────────────────┐
+                │  Operator workstation   │
+                │  - Builds server release│
+                │  - Builds agent binary  │
+                └─────────────────────────┘
+                        │ scp
+                        ▼
+                ┌─────────────────────────┐
+                │ Proxmox host (any of N) │
+                │  - Burrito agent binary │
+                │  - systemd unit         │
+                └─────────────────────────┘
+```
+
+## What runs where
+
+| Component | Host | Port / Path                              |
+|-----------|------|------------------------------------------|
+| Caddy     | Server LXC | 443 public, forwards → 127.0.0.1:4000 |
+| Phoenix   | Server LXC | 127.0.0.1:4000 (HTTP + WS)            |
+| SQLite    | Server LXC | file at $DATABASE_PATH                 |
+| Agent     | Proxmox host | no listening ports                   |
+
+## Secrets the operator must provide
+
+| Variable                  | Where      | How to generate                                 |
+|---------------------------|------------|-------------------------------------------------|
+| `SECRET_KEY_BASE`         | Server env | `mix phx.gen.secret`                            |
+| `DASHBOARD_PASSWORD_HASH` | Server env | `mix run -e 'IO.puts(Argon2.hash_pwd_salt("..."))'` |
+| Agent token               | Server DB  | Admin UI → "Add host" reveals it once           |
+
+## Build flow
+
+1. `cd server && MIX_ENV=prod mix release` → produces `_build/prod/rel/server/`
+2. `cd agent && ./scripts/build-linux.sh` → produces `dist/proxmox-monitor-agent_linux_amd64`
+
+See `server/docs/deploy-lxc.md` and `agent/docs/install.md` for step-by-step.
diff --git a/server/docs/deploy-lxc.md b/server/docs/deploy-lxc.md
new file mode 100644
index 0000000..3bffe70
--- /dev/null
+++ b/server/docs/deploy-lxc.md
@@ -0,0 +1,125 @@
+# Server Deployment (LXC + Caddy)
+
+Target: a Proxmox LXC container running Debian 12 in the RZ, publicly reachable
+on port 443 via Caddy. ~1 GB RAM, 2 cores, 10 GB disk covers >20 agents.
+
+## 1. Create the LXC (on the hypervisor)
+
+```bash
+pct create 200 \
+  /var/lib/vz/template/cache/debian-12-standard_12.7-1_amd64.tar.zst \
+  --hostname proxmox-monitor \
+  --memory 1024 --cores 2 \
+  --rootfs local-zfs:10 \
+  --net0 name=eth0,bridge=vmbr0,ip=dhcp \
+  --unprivileged 1 --features nesting=0 --onboot 1
+pct start 200
+pct enter 200
+```
+
+## 2. Inside the LXC: base packages
+
+```bash
+apt-get update && apt-get install -y \
+  ca-certificates curl debian-keyring debian-archive-keyring apt-transport-https
+# Caddy's apt repo
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | \
+  gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
+curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
+  > /etc/apt/sources.list.d/caddy-stable.list
+apt-get update && apt-get install -y caddy sqlite3
+```
+
+## 3. Upload the release
+
+From the operator workstation:
+
+```bash
+cd proxmox_monitor/server
+MIX_ENV=prod mix release --overwrite
+tar -czf server_release.tgz -C _build/prod/rel server
+scp server_release.tgz root@<LXC-IP>:/tmp/
+```
+
+Back in the LXC:
+
+```bash
+mkdir -p /opt/proxmox-monitor
+tar -xzf /tmp/server_release.tgz -C /opt/proxmox-monitor
+```
+
+## 4. Directories & env file
+
+```bash
+install -d -m 0700 /var/lib/proxmox-monitor
+cat > /etc/default/proxmox-monitor <<EOF
+DATABASE_PATH=/var/lib/proxmox-monitor/monitor.db
+SECRET_KEY_BASE=$(/opt/proxmox-monitor/server/bin/server eval 'IO.puts(64 |> :crypto.strong_rand_bytes() |> Base.encode64())' 2>/dev/null | tail -1)
+DASHBOARD_PASSWORD_HASH='<paste from: mix run -e "IO.puts(Argon2.hash_pwd_salt(\"your-password\"))">'
+PHX_SERVER=true
+PHX_HOST=monitor.example.com
+PORT=4000
+EOF
+chmod 0600 /etc/default/proxmox-monitor
+```
+
+## 5. systemd unit
+
+```ini
+# /etc/systemd/system/proxmox-monitor.service
+[Unit]
+Description=Proxmox Monitor Server
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=exec
+EnvironmentFile=/etc/default/proxmox-monitor
+ExecStartPre=/opt/proxmox-monitor/server/bin/server eval 'Server.Release.migrate()'
+ExecStart=/opt/proxmox-monitor/server/bin/server start
+ExecStop=/opt/proxmox-monitor/server/bin/server stop
+Restart=always
+RestartSec=5
+User=root
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+systemctl daemon-reload
+systemctl enable --now proxmox-monitor
+journalctl -u proxmox-monitor -f   # verify it listens on 4000
+```
+
+## 6. Caddy
+
+```bash
+install -m 0644 /opt/proxmox-monitor/server/lib/server-0.1.0/priv/docs/Caddyfile.example /etc/caddy/Caddyfile
+# Edit monitor.example.com to match your real DNS.
+nano /etc/caddy/Caddyfile
+systemctl reload caddy
+```
+
+(If Caddy isn't the one in this LXC, copy the template to wherever Caddy lives.)
+
+## 7. Create the first host
+
+```bash
+/opt/proxmox-monitor/server/bin/server rpc 'Server.Release.register_host("pve-host-01")'
+```
+
+Copy the printed TOKEN — you'll paste it into the agent config.
+
+## 8. Upgrade flow
+
+```bash
+# operator
+cd server && MIX_ENV=prod mix release --overwrite
+scp _build/prod/rel/server.tar.gz root@<LXC>:/tmp/server_release.tgz
+
+# LXC
+systemctl stop proxmox-monitor
+tar -xzf /tmp/server_release.tgz -C /opt/proxmox-monitor --overwrite
+systemctl start proxmox-monitor   # ExecStartPre runs migrate automatically
+```