constella 0.1.0

package/docs/en/UPDATE.md

@@ -0,0 +1,301 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/UPDATE.md) · [✦ Constella](../../README.md)
+
+# 🚀 Update — relaunching the central ship
+
+![](../assets/divider-orbit.svg)
+
+Constella checks npm for a newer release, shows you the changelog, and applies the update **the way that fits how this process is running** — global install, npx, dev source, Docker VPS, or a portable USB drive. It always backs up your `.env` and database first, and it never fabricates a "success" it didn't earn.
+
+---
+
+## ✦ When to use
+
+- A new Constella version is published and you want to pull it down.
+- You want to read the changelog before upgrading (the "What's new" panel).
+- You want to confirm you are already on the latest version (`constella update --check`).
+- You need the **exact command** for your environment (dev / npx / VPS / portable), because some contexts can't be updated from inside the running web server.
+
+---
+
+## 🌌 How it works
+
+Two halves cooperate:
+
+| Half | File | Responsibility |
+| --- | --- | --- |
+| **Check** | `src/server/update-check.ts` | Ask the npm registry for `latest`, compare versions, fetch the changelog. Cached, fails silent. |
+| **Apply** | `src/server/update-run.ts` | Detect the run context, back up local config, then either auto-run (global) or hand back the exact command. |
+| **Context** | `src/lib/run-context.ts` | `detectRunContext()` → `dev \| global \| npx \| vps \| portable`. |
+| **UI** | `src/components/modules/update-screen.tsx` | Versions, context hint, "Update now", changelog, live poll of the background updater. |
+| **Actions** | `src/server/actions/update-actions.ts` | Server actions the UI calls: `getUpdateStatus`, `getUpdateContext`, `runUpdate`, `pollUpdateResult`. |
+| **CLI** | `bin/constella.mjs` (`update` subcommand) | Standalone check/apply that runs **outside** the web server. |
+
+The central rule (from the code comment in `update-run.ts`): *only the `global` npm install auto-runs* — every other context returns the precise command for you to run, because executing those from the web server is environment-specific.
+
+---
+
+## 🛰️ Main flow
+
+```mermaid
+flowchart TD
+  A["Open /update or run `constella update`"] --> B["checkForUpdate()"]
+  B --> C{"npm registry reachable?"}
+  C -- "no" --> D["latest = null · no update · fail silent"]
+  C -- "yes" --> E["compare latest vs current (isNewer)"]
+  E -- "not newer" --> F["Already up to date"]
+  E -- "newer" --> G["fetch CHANGELOG · sliceChangelog(latest)"]
+  G --> H["startUpdate() → detectRunContext()"]
+  H --> I["backupBeforeUpdate() — copy .env + db"]
+  I --> J{"context?"}
+  J -- "global" --> K["spawn detached npm i -g · write last-update.json"]
+  J -- "dev / npx / vps / portable" --> L["return exact command (no auto-run)"]
+  K --> M["UI polls getUpdateResult() every 3s"]
+  M --> N["running → done / error · prompt restart"]
+```
+
+---
+
+## 🪐 Key concepts
+
+### Version check (`checkForUpdate`)
+
+- Reads the **installed** version via `currentVersion()` (`src/lib/version.ts`): `CONSTELLA_VERSION` env (set by the CLI) → launch-dir `package.json` → `"0.0.0"`.
+- Fetches `https://registry.npmjs.org/constella/latest` for the published `version`.
+- `isNewer(latest, current)` does a numeric 3-part semver compare (pre-release suffixes stripped). `bumpType` classifies the jump as `major | minor | patch`.
+- Returns an `UpdateInfo`: `{ current, latest, updateAvailable, type, command, changelog }`. The default `command` is `npm install -g constella@latest`.
+- **6-hour in-memory cache** (`TTL = 6 * 60 * 60 * 1000`) so client polling never hammers the registry. `checkForUpdate(true)` forces a refresh.
+- **Fails closed/silent**: any offline / unpublished / timeout (3 s `AbortController`) path yields `latest: null`, `updateAvailable: false`. It never throws and never fabricates "updated".
+
+### Changelog fetch
+
+- Only fetched when `updateAvailable` is true.
+- Pulls `https://raw.githubusercontent.com/gabriel7silva/constella/main/CHANGELOG.md`.
+- `sliceChangelog(md, version)` extracts the `## [x.y.z] …` section up to the next `##` heading; if the exact version heading isn't found, it falls back to the first section in the file.
+- Rendered in the UI's "What's new in v{version}" card via `react-markdown` + `remark-gfm`.
+
+### Run-context detection (`detectRunContext`)
+
+Order matters — the first match wins:
+
+| Order | Test | Context |
+| --- | --- | --- |
+| 1 | `isDevMode()` (running from source) | `dev` |
+| 2 | `getRunMode() === "vps"` **or** `/.dockerenv` exists | `vps` |
+| 3 | `getRunMode() === "portable"` | `portable` |
+| 4 | `launchDir()` path contains `/_npx/` (npm's npx cache) | `npx` |
+| 5 | (fallback) | `global` |
+
+`isDevMode()` (`src/lib/build-mode.ts`): `CONSTELLA_PUBLIC=1` → `false`; else `CONSTELLA_DEV=1` → `true`; else `NODE_ENV !== "production"`. A CLI launch sets `CONSTELLA_PUBLIC=1`, so installed runs are never mistaken for dev.
+
+### Backup before update (`backupBeforeUpdate`)
+
+- Best-effort, runs before any update in `startUpdate()`.
+- Creates `<HOME>/backups/<timestamp>/` (timestamp = ISO with `:`/`.` replaced by `-`).
+- Copies, if present: `.env`, `constella.db`, `constella.db-wal`, `constella.db-shm`.
+- Returns the backup directory path (surfaced in the UI as "Backup saved: …"). Any copy failure is skipped silently — backup never blocks the update.
+- `<HOME>` resolves via `constellaHome()`: `CONSTELLA_HOME` (resolved against the launch dir) or `~/.constella`.
+
+### Context-aware apply (`startUpdate`)
+
+| Context | `ok` | Auto-runs? | Command returned | `needsRestart` |
+| --- | --- | --- | --- | --- |
+| `global` | `true` | ✅ detached `npm install -g constella@latest` | `npm install -g constella@latest` | ✅ |
+| `dev` | `false` | ❌ | `git pull && pnpm install && pnpm build` | — |
+| `npx` | `false` | ❌ | `npx constella@latest` | — |
+| `vps` | `false` | ❌ | `docker compose pull && docker compose up -d` | ✅ |
+| `portable` | `false` | ❌ | `npm install -g constella@latest` (after free-space/backup check) | ✅ |
+
+> If `updateAvailable` is false, `startUpdate()` short-circuits with `ok: true, message: "Already up to date."` — no backup, no command.
+
+### The detached global updater + result polling
+
+Because a global npm update can't reliably finish before the web server is replaced, `startUpdate()` for `global`:
+
+1. Writes `<HOME>/backups/last-update.json` with `{ status: "running", to, at }`.
+2. Spawns a **detached** `node -e` one-liner (no separate script file — works even from a global install) that runs `npm install -g constella@latest` and rewrites the result file with `status: "done" | "error"`, the npm exit `code`, and `at`.
+3. `child.unref()`s so the updater outlives the request.
+4. Returns `{ ok: true, started: true, needsRestart: true, … }`.
+
+The UI (`update-screen.tsx`) then polls `pollUpdateResult()` → `getUpdateResult()` every **3 seconds**, reading `last-update.json`. Statuses: `idle` (no file), `running`, `done`, `error`. On `done`/`error` it stops polling and prompts a restart (or shows the rollback hint).
+
+---
+
+## 🌠 Tables
+
+### `UpdateInfo` (returned by `checkForUpdate`)
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `current` | `string` | Installed version. |
+| `latest` | `string \| null` | npm `latest`, or `null` when the registry is unreachable. |
+| `updateAvailable` | `boolean` | `latest` exists and is newer. |
+| `type` | `"major" \| "minor" \| "patch" \| null` | Size of the version jump. |
+| `command` | `string` | Default upgrade command. |
+| `changelog` | `string \| null` | Sliced changelog section for `latest`. |
+
+### `UpdateResult` (returned by `startUpdate` / `runUpdate`)
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `ok` | `boolean` | Operation succeeded (global started, or already current). |
+| `started` | `boolean?` | The detached global updater was launched → UI should poll. |
+| `context` | `string` | Detected run context. |
+| `command` | `string` | The command for this context. |
+| `message` | `string` | Human-readable status / instruction. |
+| `backupDir` | `string?` | Where `.env`/db were copied. |
+| `needsRestart` | `boolean?` | Restart Constella to load the new version. |
+
+### `last-update.json` (background updater state)
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `status` | `"idle" \| "running" \| "done" \| "error"` | Updater state (`idle` = file absent). |
+| `to` | `string` | Target version. |
+| `code` | `number` | npm exit code (on completion). |
+| `at` | `string` | ISO timestamp. |
+
+---
+
+## 🕳️ Update flow per context
+
+```mermaid
+flowchart LR
+  X["detectRunContext()"] --> G["global"]
+  X --> D["dev"]
+  X --> N["npx"]
+  X --> V["vps"]
+  X --> P["portable"]
+
+  G --> G1["detached npm i -g constella@latest"] --> G2["poll last-update.json → restart"]
+  D --> D1["git pull && pnpm install && pnpm build"]
+  N --> N1["npx constella@latest"]
+  V --> V1["docker compose pull && docker compose up -d"]
+  P --> P1["check free space + back up drive, then npm i -g constella@latest"]
+```
+
+---
+
+## ✦ Step-by-step
+
+### In the app
+
+1. Open the **Update** module (`/update`). The page calls `getUpdateStatus()` and `getUpdateContext()`.
+2. Read the **Installed → Latest** versions and the bump pill (`major`/`minor`/`patch`).
+3. The context line tells you how this process runs (e.g. "Global npm install — can update in place.").
+4. If an update is available, review **"What's new in v…"**.
+5. Click **Update now** → `runUpdate()` (auth-gated via `requireWorkspace()`).
+   - **global** → background updater starts; watch the live poll (`running → installed`), then restart Constella.
+   - **dev / npx / vps / portable** → copy the exact command shown and run it in your terminal.
+6. The **Backup saved** line shows where your `.env`/db were copied.
+
+### From the CLI
+
+```bash
+# Just check (no apply) — prints "Constella x.y.z · latest a.b.c"
+constella update --check
+
+# Check + apply (global install path)
+constella update
+```
+
+The CLI `update` subcommand (`bin/constella.mjs`):
+- Reads the local version from the package's own `package.json`, fetches npm `latest` (4 s timeout).
+- `--check` → print and exit.
+- If the registry is unreachable, or `latest === current`, it says so and exits 0.
+- If it detects **source** (`.git` + `src/` in CWD), it tells you to `git pull && pnpm install && pnpm build` and exits.
+- Otherwise it runs `npm install -g constella@latest` (uses `npm.cmd` on Windows, no shell) with inherited stdio, then asks you to restart.
+
+---
+
+## 🛰️ Examples
+
+**Already current (offline-safe):**
+```text
+Constella 0.1.0 · (npm registry unavailable)
+Couldn't reach the npm registry — try again later.
+```
+
+**Global update from the UI** — `runUpdate()` returns:
+```json
+{
+  "ok": true,
+  "started": true,
+  "needsRestart": true,
+  "context": "global",
+  "command": "npm install -g constella@latest",
+  "backupDir": "/home/you/.constella/backups/2026-06-22T10-15-03-000Z",
+  "message": "Updating to 0.2.0 in the background — restart Constella when it completes."
+}
+```
+…and the poll reads `<HOME>/backups/last-update.json`:
+```json
+{ "status": "done", "to": "0.2.0", "code": 0, "at": "2026-06-22T10:15:41.220Z" }
+```
+
+**VPS** — no auto-run; you get:
+```json
+{ "ok": false, "context": "vps", "command": "docker compose pull && docker compose up -d", "needsRestart": true,
+  "message": "On a VPS, update with Docker: docker compose pull && docker compose up -d" }
+```
+
+---
+
+## 🌌 Possible states
+
+| State | How it shows | Source |
+| --- | --- | --- |
+| Up to date | "You're on the latest version." | `updateAvailable === false` |
+| Update available | Version pill + "Update now" | `updateAvailable === true` |
+| Registry unreachable | `latest = —`, no button | `latest === null` |
+| Updating (global) | "Updating…" + spinner | `started === true`, `busy` |
+| Poll: running | "Updater: running…" | `last-update.json.status === "running"` |
+| Poll: done | "✓ installed — restart Constella to load it." | `status === "done"` |
+| Poll: error | "✖ failed — see rollback below." + rollback hint | `status === "error"` |
+| Manual command | Command shown in a `<pre>`; no auto-run | `dev / npx / vps / portable` |
+
+---
+
+## 🪐 Related integrations
+
+- **[VPS_MODE](./VPS_MODE.md)** — the Docker `docker compose pull && up -d` path.
+- **[PORTABLE_MODE](./PORTABLE_MODE.md)** — USB drive, free-space checks before updating.
+- **[INSTALLATION](./INSTALLATION.md)** / **[PUBLISHING](./PUBLISHING.md)** — how versions land on npm.
+- **[START_MODE](./START_MODE.md)** / **[AUTH_MODE](./AUTH_MODE.md)** — run modes that feed `detectRunContext()`.
+- **[CONFIGURATION](./CONFIGURATION.md)** — env vars (`CONSTELLA_HOME`, `CONSTELLA_VERSION`, `CONSTELLA_PUBLIC`).
+
+---
+
+## 🕳️ Security
+
+- **Auth-gated apply.** `runUpdate()` calls `requireWorkspace()` before doing anything.
+- **Backup first, always.** `.env` + the SQLite DB (and WAL/SHM) are copied to `<HOME>/backups/<timestamp>/` before any update path.
+- **No shell injection in the CLI.** The global install spawns `npm`/`npm.cmd` directly with an argv array — no shell string interpolation.
+- **Fail-closed checks.** The registry/changelog fetches use a 3–4 s `AbortController` timeout and swallow errors, so a hostile or dead network can't hang or crash the update screen — it just reports "no update".
+- **Honest results.** The detached updater writes a real npm exit code into `last-update.json`; the UI reflects `done`/`error` truthfully and never claims success on failure.
+
+---
+
+## 🌠 Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| "registry unavailable" | Offline / npm down / firewall | Retry later; check connectivity to `registry.npmjs.org`. |
+| Latest shown but stale | 6 h cache | Force a fresh check: `checkForUpdate(true)` (UI re-fetch) or `constella update --check`. |
+| Wrong context detected | Env mismatch | Verify `CONSTELLA_PUBLIC`/`CONSTELLA_DEV`, `CONSTELLA_RUN_MODE`, and `/.dockerenv` presence. |
+| Global poll stuck on "running" | Detached `npm` still installing or blocked | Wait; if it never resolves, run `npm install -g constella@latest` manually. |
+| Poll: error | npm exited non-zero (permissions?) | Re-run with elevated permissions; rollback: `npm i -g constella@<current>`, then restore the backup. |
+| Version still old after restart | Old process still running | Fully stop and relaunch Constella so `CONSTELLA_VERSION` re-reads. |
+| Dev install won't auto-update | Intentional | Run `git pull && pnpm install && pnpm build` (or `next build`). |
+
+---
+
+## ✦ Related links
+
+- [INSTALLATION](./INSTALLATION.md)
+- [CONFIGURATION](./CONFIGURATION.md)
+- [VPS_MODE](./VPS_MODE.md)
+- [PORTABLE_MODE](./PORTABLE_MODE.md)
+- [START_MODE](./START_MODE.md)
+- [PUBLISHING](./PUBLISHING.md)
+- [ARCHITECTURE](./ARCHITECTURE.md)
+- [TROUBLESHOOTING](./TROUBLESHOOTING.md)

package/docs/en/VPS_MODE.md

@@ -0,0 +1,334 @@
+[← Docs index](./README.md) · [🇧🇷 Português](../pt/VPS_MODE.md) · [✦ Constella](../../README.md)
+
+# VPS Mode 🛰️
+
+![](../assets/divider-orbit.svg)
+
+Run the central ship on a remote server. **VPS mode** boots Constella inside Docker on a VPS, binds the web server to `0.0.0.0`, and exposes it **only** over your Tailscale tailnet — a private orbit reachable from any device you've authorized, and from nowhere else.
+
+---
+
+## When to use 🌌
+
+Pick VPS mode when you want a **24/7 control plane** that keeps planning, building, reviewing and shipping while your laptop is closed — without putting the dashboard on the open internet.
+
+| You want… | VPS mode gives you |
+| --- | --- |
+| The agent constellation always running | A long-lived server process (web + worker), supervised + auto-restarted |
+| Private remote access | Bound to `0.0.0.0` but reachable **only on your Tailscale tailnet** |
+| Real authentication | Email + password required every session (`requiresLogin: true`) |
+| A reproducible install | A `Dockerfile` + `docker-compose.yml` + a one-shot `vps-install.sh` bootstrap |
+| Hardened-by-default execution | Container jail + agent CLI in `acceptEdits` (edits-only) mode |
+
+If you just want a local always-on instance on your own machine, use [START_MODE](./START_MODE.md) or [AUTH_MODE](./AUTH_MODE.md). For a drive-you-carry instance, see [PORTABLE_MODE](./PORTABLE_MODE.md).
+
+---
+
+## How it works 🪐
+
+VPS is one of four **run modes** declared in `src/lib/run-mode.ts`:
+
+```ts
+export type RunMode = "start" | "auth" | "vps" | "portable";
+
+export const RUN_MODES = {
+  // …
+  vps: { label: "VPS", requiresLogin: true,
+         note: "Access over your Tailscale tailnet; runs in Docker." },
+};
+```
+
+The mode is chosen **at launch**, never in the UI (a CLI launch sets `CONSTELLA_PUBLIC=1`, which hides the in-app mode picker). It is resolved in `bin/constella.mjs` from the `--vps` flag (with legacy `--bind tailnet` mapping to the same mode), then exported as `CONSTELLA_RUN_MODE=vps` and persisted onto the organization row (`organization.run_mode`) at onboarding via `getRunMode()`.
+
+Three things make VPS distinct from the other modes:
+
+1. **Bind address `0.0.0.0`.** In `bin/constella.mjs`, `host = --host || (vps|portable ? "0.0.0.0" : "127.0.0.1")`. The server listens on all interfaces so the Tailscale layer can reach it.
+2. **Login is enforced.** `requiresLogin()` returns `true`, and `src/proxy.ts` redirects every unauthenticated request to `/login` (only `start` mode skips this).
+3. **Run context = `vps`.** `detectRunContext()` in `src/lib/run-context.ts` returns `"vps"` when `getRunMode() === "vps"` **or** when `/.dockerenv` exists — so the in-app Update flow knows to use `docker compose` rather than `npm`/`git`. See [UPDATE](./UPDATE.md).
+
+> 🛰️ **Tailscale is assumed externally configured.** Constella does not manage your tailnet, ACLs or auth keys. The bootstrap script and compose file *join* a tailnet for you, but the tailnet itself (devices, MagicDNS, ACLs) is yours to own at <https://login.tailscale.com>. Constella only binds `0.0.0.0`; the tailnet is what keeps that bind private.
+
+---
+
+## Main flow 🌠
+
+```mermaid
+flowchart TD
+  A["operator: bash scripts/vps-install.sh"] --> B["install Docker"]
+  B --> C["install Tailscale + tailscale up"]
+  C --> D["TS_AUTHKEY written to .env"]
+  D --> E["docker compose up -d --build"]
+  E --> F["tailscale sidecar joins tailnet"]
+  E --> G["constella container builds + boots"]
+  G --> H["bin/constella.mjs --vps --host 0.0.0.0 --port 3000"]
+  H --> I["generate/persist secrets in /data/.env (chmod 600)"]
+  H --> J["drizzle migrate against /data/constella.db"]
+  H --> K["supervise: next start + worker"]
+  F & K --> L["reachable at http://<tailscale-ip>:3000"]
+```
+
+---
+
+## Key concepts ✦
+
+### The two containers
+
+`docker-compose.yml` runs **two services that share one network namespace**:
+
+- **`tailscale`** — the official `tailscale/tailscale` image, acting as a sidecar. It owns `/dev/net/tun`, holds `net_admin` + `sys_module` caps, joins the tailnet headlessly with `TS_AUTHKEY`, and persists node state in the `tailscale-state` volume.
+- **`constella`** — built from the `Dockerfile`, joined to the sidecar's network with `network_mode: service:tailscale`. Because they share the namespace, Constella is reachable **only at the Tailscale IP** on port 3000 — never on the host's public interfaces.
+
+### Runtime root on a volume
+
+Inside the container, `CONSTELLA_HOME=/data` (a named Docker volume, `constella-data`). All runtime state lives there:
+
+- `/data/constella.db` — the SQLite database (`DATABASE_URL=file:/data/constella.db`).
+- `/data/.env` — generated secrets (`chmod 600`), survives restarts because the volume is stable.
+- `/data/organizations/<orgId>/workspace/` — the agent workspace tree (the FS jail). See [ARCHITECTURE](./ARCHITECTURE.md).
+
+### Worker over loopback (even on `0.0.0.0`)
+
+The dual-process model (web + worker) is preserved in VPS mode. The launcher spawns `bin/worker.mjs` with `CONSTELLA_BASE_URL=http://127.0.0.1:<port>` — **loopback**, even though the web server binds `0.0.0.0`. This is a deliberate **SSRF / secret-exfil guard**: the worker attaches the privileged `x-worker-secret` header to every call, so it refuses any non-loopback base URL:
+
+```js
+const isLoopback = ["localhost", "127.0.0.1", "::1", "[::1]"].includes(baseHost);
+if (!isLoopback && !ALLOW_REMOTE) {
+  console.error(`✖ Refusing to send the worker secret to a non-loopback host (${baseHost}). …`);
+  process.exit(1);
+}
+```
+
+A genuinely remote worker must explicitly opt in with `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` (and is warned if the URL is plain `http://`). See [ARCHITECTURE](./ARCHITECTURE.md).
+
+### Secrets are mandatory
+
+`bin/constella.mjs` generates and persists **three** secrets into `/data/.env` on first boot (and reuses them after):
+
+- `BETTER_AUTH_SECRET` — `next start` runs under `NODE_ENV=production`, where better-auth **throws** on its default key; a network mode must have a real one.
+- `CONSTELLA_VAULT_KEY` — AES-256-GCM key for the provider/credential vault. See [SECURITY](./SECURITY.md).
+- `CONSTELLA_WORKER_SECRET` — the worker fails **closed** without it (`x-worker-secret`).
+
+The launcher prints only `• Secrets ready (stored in <HOME>/.env, never printed).` — values are never logged.
+
+---
+
+## Tables 🗃️
+
+### Run-mode comparison
+
+| Property | `start` | `auth` | `vps` | `portable` |
+| --- | --- | --- | --- | --- |
+| `requiresLogin` | `false` | `true` | `true` | `true` |
+| Default bind host | `127.0.0.1` | `127.0.0.1` | **`0.0.0.0`** | `0.0.0.0` |
+| Network exposure | localhost | localhost | **Tailscale tailnet** | LAN (USB host) |
+| Typical runtime | local | local | **Docker** | USB drive |
+| Agent CLI permission | `bypassPermissions` (full) | `acceptEdits` (jailed) | **`acceptEdits` (jailed)** | `acceptEdits` (jailed) |
+| `detectRunContext()` | `dev`/`global`/`npx` | `dev`/`global`/`npx` | **`vps`** | `portable` |
+
+### VPS environment variables
+
+| Variable | Set by | Value | Purpose |
+| --- | --- | --- | --- |
+| `CONSTELLA_RUN_MODE` | launcher / Dockerfile / compose | `vps` | Selects VPS behavior, login enforcement |
+| `CONSTELLA_PUBLIC` | launcher / Dockerfile / compose | `1` | Marks a public runtime; hides the UI mode picker |
+| `CONSTELLA_HOME` | Dockerfile / compose | `/data` | Runtime root (a Docker volume) |
+| `DATABASE_URL` | launcher | `file:/data/constella.db` | SQLite path under the volume |
+| `BETTER_AUTH_SECRET` | launcher (generated) | random base64url | Session signing key |
+| `CONSTELLA_VAULT_KEY` | launcher (generated) | random base64 | Vault encryption key |
+| `CONSTELLA_WORKER_SECRET` | launcher (generated) | random base64url | Worker `x-worker-secret` |
+| `CONSTELLA_BASE_URL` | launcher (worker child) | `http://127.0.0.1:3000` | Loopback only |
+| `NODE_ENV` | Dockerfile | `production` | Production boot |
+| `TS_AUTHKEY` | `.env` / compose | `tskey-auth-…` | Tailscale sidecar join key |
+| `CONSTELLA_AGENT_FULL_ACCESS` | operator (optional) | `1` / `0` | Override jailed/full agent exec |
+| `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL` | operator (optional) | `1` | Allow a non-loopback worker |
+| `CONSTELLA_WEB_HEAP_MB` | operator (optional) | integer | Raise the web V8 heap cap |
+
+### Docker compose services
+
+| Service | Image / build | Network | Volumes | Notable caps |
+| --- | --- | --- | --- | --- |
+| `tailscale` | `tailscale/tailscale:latest` | own namespace | `tailscale-state:/var/lib/tailscale` | `net_admin`, `sys_module`, `/dev/net/tun` |
+| `constella` | `build: .` (Dockerfile) | `service:tailscale` | `constella-data:/data` | runs as unprivileged `node` (uid 1000) |
+
+---
+
+## Topology diagram 🌌
+
+```mermaid
+flowchart LR
+  subgraph TN["Your Tailscale tailnet (private orbit)"]
+    direction LR
+    L["Laptop"]
+    P["Phone"]
+    subgraph VPS["VPS host"]
+      subgraph NS["shared net namespace"]
+        TS["tailscale sidecar\n(net_admin, /dev/net/tun)"]
+        C["constella container\n0.0.0.0:3000\nuid 1000 'node'"]
+      end
+      V1[("/data volume\nconstella.db + .env")]
+      V2[("tailscale-state\nvolume")]
+    end
+  end
+  NET(["public internet"]) -. blocked .-> VPS
+  L -->|"https tailnet"| TS
+  P -->|"https tailnet"| TS
+  TS --> C
+  C --- V1
+  TS --- V2
+
+  subgraph IN["inside the constella container"]
+    W["next start (web)\n0.0.0.0:3000"]
+    K["worker.mjs\n→ 127.0.0.1:3000\nx-worker-secret"]
+    K -->|loopback only| W
+  end
+```
+
+---
+
+## Step-by-step 🚀
+
+### 1. Provision a VPS
+
+A fresh Ubuntu Server is the assumed target (the bootstrap installs Docker via `get.docker.com` and Tailscale via `tailscale.com/install.sh`).
+
+### 2. Run the bootstrap
+
+```bash
+bash scripts/vps-install.sh
+```
+
+`scripts/vps-install.sh` does, in order:
+
+1. **Install Docker** if `docker` is not on `PATH` (`curl -fsSL https://get.docker.com | sh`).
+2. **Install Tailscale** if absent (`curl -fsSL https://tailscale.com/install.sh | sh`).
+3. **Join the tailnet** with `sudo tailscale up` (prints a browser auth URL if needed).
+4. **Ask for a `TS_AUTHKEY`** (so the *container* sidecar can join headlessly) and append it to `.env`.
+5. **Build + start** the stack: `sudo docker compose up -d --build`.
+6. **Print the reach URL**: `http://<tailscale-ip>:3000`.
+
+### 3. Create the Tailscale auth key
+
+When prompted, create a key at <https://login.tailscale.com/admin/settings/keys> and paste the `tskey-auth-…` value. It is written to `.env` as `TS_AUTHKEY=…`, which the compose file passes to the `tailscale` sidecar.
+
+### 4. Reach the dashboard
+
+From **any device on the same tailnet**, open:
+
+```
+http://<this-node's-tailscale-ip>:3000
+```
+
+Find the IP with `tailscale ip -4` on the VPS. First load lands on `/login` (login is enforced); after sign-in, complete [ONBOARDING](./ONBOARDING.md) if it's the first run.
+
+### 5. Manual compose path (no bootstrap)
+
+```bash
+echo "TS_AUTHKEY=tskey-auth-..." > .env
+docker compose up -d --build
+# then: http://<tailscale-ip>:3000
+```
+
+---
+
+## Examples 🪐
+
+**Launch VPS mode directly (without Docker), binding all interfaces:**
+
+```bash
+node bin/constella.mjs --vps --host 0.0.0.0 --port 3000
+```
+
+**The exact container command (from the `Dockerfile`):**
+
+```dockerfile
+CMD ["node", "bin/constella.mjs", "--vps", "--host", "0.0.0.0", "--port", "3000"]
+```
+
+**Confirm the run context the app sees:**
+
+```bash
+# inside the container — /.dockerenv exists, so detectRunContext() → "vps"
+ls /.dockerenv && echo "context: vps"
+```
+
+**Allow agents full shell exec on the VPS (override the jail — use with care):**
+
+```bash
+# set in the compose `environment:` block for the constella service
+CONSTELLA_AGENT_FULL_ACCESS=1
+```
+
+---
+
+## Possible states ✦
+
+| State | What you see | Meaning |
+| --- | --- | --- |
+| Booting | `Mode : vps · 0.0.0.0:3000` in logs | Launcher resolved VPS, binding all interfaces |
+| Secrets ready | `• Secrets ready (stored in /data/.env, never printed).` | Three secrets generated/reused |
+| Migrating | drizzle migrate output | Schema applied to `/data/constella.db` |
+| Web up | `next start` listening on `0.0.0.0:3000` | Dashboard reachable on tailnet |
+| Worker up | `Constella worker → tick … every 60000ms` | 24/7 tick + watcher + Telegram poll running |
+| Worker refused | `✖ Refusing to send the worker secret to a non-loopback host` | `CONSTELLA_BASE_URL` is not loopback and no override |
+| Child crash | `• [web] exited (…) — auto-restarting in 2s` | Supervisor restarting (max 5 / 60s) |
+| Crash-loop | `✖ [web] … crashed 5x … giving up.` | Repeated failure; supervisor stops |
+| Login wall | redirected to `/login` | `requiresLogin` enforced by `src/proxy.ts` |
+
+---
+
+## Related integrations 🛰️
+
+- **Worker / cron** — the worker still drives the 60s tick (`POST /api/cron/tick`), the chokidar watcher (`/api/sync/file`), and the Telegram long-poll, all over loopback. See [ARCHITECTURE](./ARCHITECTURE.md).
+- **Telegram** — remote-control the company from your phone while the VPS runs headless. See [TELEGRAM](./TELEGRAM.md).
+- **Public API / MCP** — a remote AI host can drive the VPS over the tailnet via the v1 REST API or the MCP server. See [PUBLIC_API](./PUBLIC_API.md) and [MCP](./MCP.md).
+- **Update** — on `vps` context, the in-app Update runs `docker compose pull && up -d`. See [UPDATE](./UPDATE.md).
+- **Agent execution** — jailed `acceptEdits` mode on top of the container jail. See [AGENTS](./AGENTS.md) and [AI_ARCHITECTURE](./AI_ARCHITECTURE.md).
+
+---
+
+## Security 🕳️
+
+| Layer | Mechanism |
+| --- | --- |
+| Network privacy | App binds `0.0.0.0` but only the Tailscale sidecar reaches it (`network_mode: service:tailscale`) — never the public internet |
+| Authentication | Login enforced every session (`requiresLogin: true`, `src/proxy.ts` → `/login`); better-auth email+password, optional 2FA/passkeys |
+| Container hardening | Runs as unprivileged `node` (uid 1000), not root, so an app-level RCE can't act as root over `/data` |
+| Secret signing | Real `BETTER_AUTH_SECRET` generated (no default key in production) |
+| Vault | Provider/credential secrets encrypted with `CONSTELLA_VAULT_KEY` (AES-256-GCM) |
+| Worker isolation | Worker talks **loopback only**; refuses non-loopback unless `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` |
+| File `.env` perms | `/data/.env` written `chmod 600` |
+| Agent jail | CLI runs `acceptEdits` (edits-only, no arbitrary exec) + FS jail; container is the hard outer jail |
+
+> 🕳️ **The bind alone is not the boundary.** Binding `0.0.0.0` is safe *only because* the container shares the Tailscale sidecar's namespace and the host does not publish port 3000 to the public internet. If you remove the sidecar and expose 3000 directly, you lose the private orbit — put it behind the tailnet or a VPN/reverse proxy with auth.
+
+> ⚠️ **Agent CLIs are not bundled.** The `Dockerfile` notes the `claude` / `codex` CLIs are **not** in the image. For agents on a VPS, either add a `RUN` step to install a CLI, or configure cloud API providers in the [MODELS](./MODELS.md) module.
+
+---
+
+## Troubleshooting 🌠
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Can't reach `http://<ip>:3000` | Not on the tailnet, or wrong IP | Confirm `tailscale status`; get the IP with `tailscale ip -4` on the VPS |
+| Sidecar won't join | Missing/expired `TS_AUTHKEY` | Re-create the key, update `.env`, `docker compose up -d` |
+| Redirected to `/login` and can't proceed | First run, no account yet | Sign up / complete [ONBOARDING](./ONBOARDING.md); login is mandatory in VPS |
+| `✖ Refusing to send the worker secret to a non-loopback host` | `CONSTELLA_BASE_URL` not loopback | Leave it unset (defaults to loopback) or set `CONSTELLA_ALLOW_REMOTE_WORKER_BASE_URL=1` deliberately |
+| `better-auth` throws on boot | Missing `BETTER_AUTH_SECRET` | Ensure `/data` volume is writable so the launcher can persist `.env` |
+| Agents do nothing | No CLI in image / no provider | Install a CLI in the image or configure a cloud provider ([MODELS](./MODELS.md)) |
+| Web keeps restarting | OS-level OOM (agent RAM) or native crash | Cap concurrent agents, or raise `CONSTELLA_WEB_HEAP_MB` for a JS-heap OOM |
+| `✖ … crashed 5x … giving up` | Genuine crash-loop | Inspect `docker compose logs constella`; fix root cause before restart |
+| Schema migrate fails on fresh DB | Volume permission / corrupt | Ensure `/data` is `node:node`-owned and writable; the launcher aborts on a fresh-DB migrate failure |
+
+---
+
+## Related links ✦
+
+- [INSTALLATION](./INSTALLATION.md) — getting the package + prerequisites
+- [START_MODE](./START_MODE.md) · [AUTH_MODE](./AUTH_MODE.md) · [PORTABLE_MODE](./PORTABLE_MODE.md) — the other run modes
+- [CONFIGURATION](./CONFIGURATION.md) — environment variables and tuning
+- [ARCHITECTURE](./ARCHITECTURE.md) — web + worker, FS jail, sync engine
+- [UPDATE](./UPDATE.md) — context-aware updates (`docker compose` on `vps`)
+- [TELEGRAM](./TELEGRAM.md) — remote control of the headless company
+- [PUBLIC_API](./PUBLIC_API.md) · [MCP](./MCP.md) — drive Constella remotely
+- [SECURITY](./SECURITY.md) — vault, FS jail, secret scrubbing
+- [TROUBLESHOOTING](./TROUBLESHOOTING.md) · [FAQ](./FAQ.md)