> ## Documentation Index > Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt > Use this file to discover all available pages before exploring further. # INSTALL # Installing Prism ## Quick install — one command (per ADR-030) **Mac / Linux:** ```bash theme={null} curl -fsSL https://github.com/FrankTewksbury/Prism/raw/main/scripts/install.sh | bash ``` **Windows (PowerShell):** ```powershell theme={null} irm https://github.com/FrankTewksbury/Prism/raw/main/scripts/install.ps1 | iex ``` That's the whole install. The bootstrap script: 1. Detects Node ≥ 18; offers to install via the OS package manager (`brew` on Mac, `winget` on Windows, `apt`/`dnf` on Linux) if missing. 2. Prompts for a Projects root (default: `~/Projects/` on Mac/Linux, `%USERPROFILE%\Projects\` on Windows). The repo lands at `/Prism`. 3. Clones the repo, builds the CLI (`npm install` runs `tsc` via the `prepare` hook). 4. Hands off to `prism install`, which detects and (with one consent prompt) installs remaining prereqs (docker, gh), builds the Node MCP shim, wires every detected editor, registers `prism` and `coder` on PATH, wires the Claude Code statusline, and runs smoke. Python is **not** a prereq — the MCP shim is Node (SPEC-054). After install, both `prism` and `coder` are globally on PATH. To upgrade later, run `prism update` from anywhere — it pulls latest, rebuilds, refreshes editor configs, refreshes container images for the personal stack, and re-runs smoke. The install logs to `~/.prism/install.log` (Mac/Linux) / `%USERPROFILE%\.prism\install.log` (Windows). If anything goes sideways, that file has the full trace. ## Three backend modes | Mode | Backend location | When to use | | --------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------ | | **Local** | Docker on this same machine, loopback `127.0.0.1:8765` | Solo dev, no shared state | | **LAN** | Existing Prism backend on your network (e.g. `http://server1.home.lan:41765`) | Multi-machine single-user, or small team sharing one backend | | **Cloud** | Hosted Prism backend (deferred — not yet available) | Multi-tenant SaaS | All three share the same client-install machinery — the only difference is the `PRISM_API_URL` / `PRISM_API_KEY` pair the editors end up pointing at. `prism install` will prompt for the mode if it isn't supplied via `--mode local|lan|cloud`. *** ## Manual install (advanced) If you don't want to pipe a script from the internet to a shell, do it by hand: ```bash theme={null} # 1. Install Node ≥ 18 (brew install node, winget install OpenJS.NodeJS.LTS, etc.) # 2. Clone the repo to your Projects root: git clone https://github.com/FrankTewksbury/Prism.git ~/Projects/Prism # 3. Build + run the installer: cd ~/Projects/Prism && npm run setup ``` `npm run setup` is defined in the root `package.json` and runs `cd cli && npm install && node dist/index.js install`. Same flow as the bootstrap script's hand-off. ## Prerequisites (auto-installed by `prism install`) You don't need to install these manually — `prism install` detects them and offers a single consent prompt to install whichever are missing, via the OS package manager: * **Node.js 18+** (the only true manual prereq — bootstrap detects+installs it) * **Git** * **Docker / docker-compose** (only required for **Local** mode — LAN and cloud users skip) * **gh** (the GitHub CLI — for `prism login` and remote operations) **No Python.** Per SPEC-054, the MCP shim is now Node (`mcp-node/`). Editor hosts run `node mcp-node/dist/server.js` directly under your Node install — no `mcp/.venv`, no `pip install`, no Python on PATH. You also need at least one supported editor: Claude Desktop, Claude Code, Cursor, or Codex. For **LAN mode**: the backend URL + API key from whoever administers that server. ## Building the CLI by hand `cli/dist/` is **not committed** — `npm install` runs the `prepare` script which builds it via `tsc`. A fresh clone has only `cli/src/`; you must build before `prism` works: ```bash theme={null} cd cli && npm install && npm run build ``` After the bootstrap or `prism install` runs, `prism` is on PATH globally (registered via the user-scope Windows registry on Windows, or via a managed `~/.zshrc` / `~/.bashrc` block on Mac/Linux). ### Windows line-ending note This repo ships a `.gitattributes` that forces LF on shell scripts, Dockerfiles, and other container-executed files. Without it, Windows Git's default `core.autocrlf=true` would convert `backend/docker-entrypoint.sh` to CRLF on checkout, and the Linux container would crash-loop on `env: 'bash\r': No such file or directory`. If you cloned **before** the `.gitattributes` landed, run `git add --renormalize . && git commit` (or just re-clone) to fix the existing checkout's line endings. *** ## Choosing a mode `prism install` takes an explicit mode flag. If neither `--mode` nor `--api-url` is supplied and you're on a TTY, it prompts `1/2/3`: ``` Select install mode: 1. Local — run the Prism stack on this machine via Docker 2. LAN — connect to an existing Prism server on the local network 3. Cloud — connect to Anthropic's hosted Prism (not yet available) ``` Use `--mode` on non-interactive runs (CI, scripts, first-boot machines). ## Local install Personal-mode backend running on your own machine, loopback-only. ```bash theme={null} prism up # start the stack; rebuild image; mint (or # read existing) API key; write mode=local creds prism install --mode local # docker + backend-auth preflight; wire editors ``` What happens: * `prism up` — `docker compose -f docker-compose.personal.yml up -d --build` (always rebuild so `git pull` doesn't leave a stale image — compose layer cache makes this \~instant when nothing changed), waits for healthcheck, syncs credentials from the backend container to `~/.prism/credentials.personal.json` with `mode:"local"` stamped. On first boot the container mints a fresh API key; on re-runs it reads the existing one. After up: scans every container's health and warns about any that aren't running/healthy (catches stale-image crash-loops). * `prism install --mode local` — runs **three preflights** before touching any editor config: (1) docker + compose + daemon + container-health, (2) the actual HTTP backend at `http://127.0.0.1:8765` must answer `/health` AND authenticate the key, (3) the Node MCP shim (`mcp-node/dist/server.js`) is built (auto-builds via `npm install` + `tsc` if dist/ is missing or stale). Refuses with "run `prism up` first" if the stack isn't up, with "api key rejected" if creds are stale, and with a build-error pointer if mcp-node fails to compile. Then writes the `prism` MCP block (`command: node`, `args: [/mcp-node/dist/server.js]`) into every editor and installs the `coder` launcher (see "What `prism install` does" below). Teardown: `prism down` stops the stack; `prism uninstall` removes editor blocks and the launcher. *** ## LAN install Client points at an existing Prism backend on your network. Docker is **not** required on the client — the backend stack lives elsewhere. ```bash theme={null} prism install --mode lan --host server1.home.lan --api-key prk_... ``` Full walkthrough — prereqs, what the installer does step-by-step, retrieving the API key from the server, verifying, troubleshooting — in **[LAN Install](/install-lan)**. *** ## Cloud install (deferred) Hosted multi-tenant Prism — not yet available. When it lands, the flow will be: ```bash theme={null} prism login # opens browser for GitHub OAuth; stores credentials prism install # auto-detects the hosted endpoint ``` `prism login` and `prism whoami` are implemented today against the dev API; the hosted cloud endpoint is still in design. Until then, use Local or LAN. *** ## What `prism install` does (all modes) Regardless of which backend the client ends up pointing at: 1. **Resolve backend** — priority: `--api-url` flag → credentials file `api_url` → `PRISM_API_URL` env var → existing editor-config value → running personal stack → default `http://127.0.0.1:8010`. 2. **Write MCP block per editor** with canonical env (`PRISM_API_URL`, `PRISM_API_KEY`, `LOG_DIR`, `PROJECT_ROOT`, `PRISM_GITHUB_USER`) plus per-editor identity (`PRISM_AGENT_IDENTITY` / `PRISM_AGENT_SURFACE`): | Editor | Identity | Surface | | -------------- | -------- | ---------------- | | claude-desktop | `Donna` | `claude_desktop` | | claude-code | `Donna` | `claude_code` | | cursor | `Cursor` | `cursor` | | codex | `Codex` | `codex` | 3. **Modify, don't replace** — any env key you've added manually (`PRISM_DEBUG`, custom feature flags) is preserved across re-installs. `--force` opts into wholesale replacement. 4. **Install the `coder` launcher** — cross-platform: * macOS/Linux: `chmod +x bin/coder.{sh,ps1}`, symlink `bin/coder → coder.sh`, append a sentinel-delimited managed block to `~/.zshrc` (or `~/.bashrc` / `~/.bash_profile`) prepending `$PRISM_ROOT/bin` to `PATH`. * Windows: write `bin/coder.cmd` shim invoking `pwsh -NoLogo -NoProfile -File coder.ps1`, append `$PRISM_ROOT\bin` to User `PATH` via `[Environment]::SetEnvironmentVariable(..., 'User')`. 5. **Atomic writes + backups** — every config change produces `.bak.`; writes use temp + rename. 6. **Repo conventions** (when run inside the Prism repo) — sets `core.hooksPath=.githooks` so the pre-commit branch guard activates. The guard refuses commits on `main` or detached HEAD; emergency override is `GIT_BRANCH_GUARD_ALLOW=1`. Closes the recurring branch-confusion postmortem class. The launcher scripts are **self-sufficient** — they derive `PRISM_ROOT` from their own location and read `PRISM_API_URL` / `PRISM_API_KEY` / `PROJECT_ROOT` from `~/.prism/credentials.personal.json`. Env vars still override; only `PRISM_API_KEY` hard-fails when absent from every source. ## The `coder` launcher — agent-aware sessions `coder` is a thin wrapper that exports the right Prism env vars (`PRISM_AGENT_IDENTITY`, `PRISM_AGENT_SURFACE`, `PROJECT_ROOT`, etc.) into a child editor process so the editor's MCP block + Prism's runtime identity resolution agree on who's at the keyboard. Surface mapping is fixed by the `-agent` flag: | `-agent` | `PRISM_AGENT_SURFACE` | Editor invoked | | ------------------ | --------------------- | -------------- | | `claude` (default) | `claude_code` | `claude` | | `codex` | `codex` | `codex` | | `cursor` | `cursor` | `cursor` | Common shape: ```bash theme={null} coder -agent -as [-mode ] [-autonomy ] [-god] ``` ### Identity (`-as `) Names the persona the session should run as. With Prism's auto-declare flow (ADR-26 v2), an unrecognised identity is added to the persona registry on first launch — no pre-registration needed. Omit `-as` to register as `Bot` (the SPEC-038 Bot sentinel; multiple Bot sessions may coexist on the same project without identity-conflict 409s). ### `-mode` and `-autonomy` — what they actually do, per agent For **Claude Code**, `-mode` and `-autonomy` are **Prism env metadata only** — they're recorded on the controller registration but do not alter Claude Code's permission model. `-god` is the only flag with runtime effect on Claude Code: it adds `--dangerously-skip-permissions`. For **Codex**, the same flags are **real CLI controls** mapped onto the Codex CLI 0.125+ flags: | Prism flag | Codex flag | Notes | | ---------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `-mode interactive` | `--ask-for-approval on-request` | Default. | | `-mode autonomous` | `--ask-for-approval never` | Codex acts without per-step prompts. | | `-autonomy read` | `--sandbox read-only` | Read-only filesystem. | | `-autonomy safe-write` | `--sandbox workspace-write` | Workspace writes only. | | `-autonomy full-local` | `--sandbox workspace-write` | Same sandbox; Codex 0.125 has no broader local tier. | | `-god` | `--dangerously-bypass-approvals-and-sandbox` | Overrides the normal mode/autonomy mapping. Use only when the launcher is already running in an externally controlled environment. | The launcher always passes `-C ` so Codex resolves relative paths against the Prism project root, and exports `PRISM_AGENT_SURFACE=codex` so the controller registration shows `codex` instead of falling back to `other`. `bin/smoke_coder_codex.sh` exercises the dry-run mapping for `interactive/read`, `autonomous/safe-write`, `autonomous/full-local`, and `-god`. PowerShell parity (`bin/coder.ps1`) is line-for-line with the bash script. `prism install` / `prism update` run this launcher smoke after wiring editor configs and launchers so flag regressions, including the `-god` approval bypass contract, fail during install refresh. ### Deprecated flags — `-install-deps` and `-activate-venv` Both flags are accepted by the parser for operator-script compatibility but are **no-ops** as of 2026-05-02. Project-bootstrap concerns (deps install, venv activation) migrated out of the launcher and into per-persona daemon attach-time behavior under SPEC-070 §Attach-to-project (ADR #42). When invoked, each emits a one-line stderr deprecation note pointing at the SPEC. Behavior moves to the daemon when the daemon binary ships; until then, run `pip install` / `npm install` and `source .venv/bin/activate` (Unix) or `.\.venv\Scripts\Activate.ps1` (Windows) manually before launching `coder`, the same way you would for any other tool. `-autonomy` continues to function as a declarative input — it exports `PRISM_AUTONOMY_LEVEL` and (for Codex) maps to `--sandbox`, but its forward role is as a hint to the per-persona daemon's tool-permission filter (SPEC-070); the daemon-side gate is not yet wired. ### Codex prerequisites `coder -agent codex` requires the Codex CLI on PATH. Install via: ```bash theme={null} brew install codex # macOS / Linux via Homebrew # OR npm install -g @openai/codex # cross-platform npm path ``` The launcher does not auto-install Codex — `coder -agent codex` simply invokes whatever `codex` is on `PATH`. Codex's own configuration (`~/.codex/config.toml`, login, model selection) is independent of Prism; the launcher only injects environment, never edits Codex config. > Today's signal delivery posture differs across surfaces. Claude > Code receives signals via channel-push doorbell; Codex falls back > to piggyback delivery on the next verb response. See > [Agent Surfaces](/agent-surfaces) for the full per-surface table. ## Flags ``` --mode Install mode. Prompts 1/2/3 when absent on a TTY. `lan` requires --api-key (and optionally --host/--port). `cloud` is deferred and exits 2. --host LAN server hostname. Default: server1.home.lan --port LAN server port. Default: 41765 --api-url Backend URL. Overrides --mode; skips preflight. Env: PRISM_API_URL (legacy PRISMGR_API_URL honored) --api-key Backend API key. Required for --mode lan. Env: PRISM_API_KEY (legacy PRISMGR_API_KEY honored) --force Wholesale-replace the MCP block instead of merging env keys. Drops any user-added env entries. --dry-run Print the plan without writing anything. ``` ## Re-running / idempotency Safe to re-run `prism install` anytime. Every step checks state first; no-op when nothing changed. `.bak.` files are created only when a write would actually change the target. ## Uninstall ```bash theme={null} prism uninstall ``` Strips the `prism` (and legacy `prismgr`) MCP block from every editor, removes the managed block from the shell rc / User PATH, removes the `coder` symlink / `coder.cmd` shim. Backups are kept; credentials file is left in place. ## Troubleshooting | Symptom | Fix | | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prism: command not found` | Run `cd cli && npm link` (once per machine) | | Editor still not seeing Prism | Restart the editor — GUI apps re-read config on launch | | `coder: command not found` in new shell | Confirm `~/.zshrc` has the managed block; open a fresh shell tab (PATH changes don't apply to existing shells) | | `coder` preflight error: `no PRISM_API_KEY` | Local: run `prism up`. LAN: seed `~/.prism/credentials.personal.json` or re-run `prism install` with `--api-key` | | Windows PATH change not reflected | `SetEnvironmentVariable('User')` only applies to new shells; close + reopen | | Wrong backend URL after install | `cat ~/.claude.json \| grep PRISM_API_URL`. If wrong, re-run with explicit `--mode lan --host --api-key ` | | `prism up` errors "configured for LAN mode" | Your credentials file says this machine is a LAN client. That's working as intended — `up/down/logs` are Local-only. Use `prism status` for remote backend health, or `prism install --mode local --force` to reconfigure. | | LAN preflight: "api key rejected (HTTP 401)" | Your key is wrong or the server's `credentials.json` is stale. Verify against a known-good client or re-read with `sudo docker exec prism-server-backend cat /root/.prism/credentials.json`. | | Backend container crash-loops with `env: 'bash\r': No such file or directory` (Windows) | CRLF line endings landed in `docker-entrypoint.sh`. Your clone predates the `.gitattributes` fix. Run `git add --renormalize . && git commit -m "renormalize line endings"` then `prism up` again. Or re-clone. | | `node cli\dist\index.js` or `prism` fails with "cannot find module" on a fresh clone | `cli/dist/` isn't committed. Run `cd cli && npm install` — the `prepare` script builds it. | | Claude Desktop shows "Server disconnected" launching the MCP shim | The Node shim isn't built. Run `cd mcp-node && npm install && npm run build`, or just re-run `prism install` (it auto-builds). Verify `mcp-node/dist/server.js` exists. | | `prism install`: "mcp-node build did not produce dist/server.js" | The TypeScript build failed. `cd mcp-node && npm run build` and read the tsc output. | ## Updating Prism ```bash theme={null} prism update ``` `prism update` runs from anywhere on PATH. It pulls latest, rebuilds the CLI, re-runs `prism install` idempotently (refreshing editor configs and the launcher), and — when this machine is in **local** mode — refreshes the personal-stack container images. Pass `--dry-run` to preview, `--yes` to skip prompts, or `--force` to override drift checks. If you'd rather drive each step by hand, the equivalent fallback is: ```bash theme={null} cd Prism && git pull --ff-only origin cd cli && npm install && npm run build prism install # idempotent; auto-detects existing backend ``` *** ## Server-side install (separate concern) This doc is **client-only**. If you're setting up the machine that runs the Prism backend + databases, don't use `prism install` — it targets editor configs only. See instead: * **`DEPLOY.md`** — production runbook. * **`bin/prism-server-install.sh`** — one-shot Ubuntu installer (docker + ufw hardening, tuned for LAN deployments like server1). * **`bootstrap.sh` / `bootstrap.ps1`** — retained at repo root for backend-host system-prereq installation (git, docker, node). Not used by client install anymore.