Installing Prism

Quick install — one command (per ADR-030)

Mac / Linux:

curl -fsSL https://github.com/FrankTewksbury/Prism/raw/main/scripts/install.sh | bash

Windows (PowerShell):

irm https://github.com/FrankTewksbury/Prism/raw/main/scripts/install.ps1 | iex

That’s the whole install. The bootstrap script:

Detects Node ≥ 18; offers to install via the OS package manager (brew on Mac, winget on Windows, apt/dnf on Linux) if missing.
Prompts for a Projects root (default: ~/Projects/ on Mac/Linux, %USERPROFILE%\Projects\ on Windows). The repo lands at <projects-root>/Prism.
Clones the repo, builds the CLI (npm install runs tsc via the prepare hook).
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:

# 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:

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:
Local   — run the Prism stack on this machine via Docker
LAN     — connect to an existing Prism server on the local network
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.

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: [<repo>/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.

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.

Cloud install (deferred)

Hosted multi-tenant Prism — not yet available. When it lands, the flow will be:

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:

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.
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
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.
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').
Atomic writes + backups — every config change produces <file>.bak.<timestamp>; writes use temp + rename.
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.

Editor	Identity	Surface
claude-desktop	`Donna`	`claude_desktop`
claude-code	`Donna`	`claude_code`
cursor	`Cursor`	`cursor`
codex	`Codex`	`codex`

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:

coder -agent <name> -as <Identity> [-mode <m>] [-autonomy <a>] [-god]

Identity (`-as <Identity>`)

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 <project_dir> 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:

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 for the full per-surface table.

Flags

--mode <local|lan|cloud>
                      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 <name>         LAN server hostname. Default: server1.home.lan
--port <n>            LAN server port.     Default: 41765
--api-url <url>       Backend URL. Overrides --mode; skips preflight.
                      Env: PRISM_API_URL (legacy PRISMGR_API_URL honored)
--api-key <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.<timestamp> files are created only when a write would actually change the target.

Uninstall

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 <host> --api-key <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

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:

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.

Introduction

Thesis

Architecture

Prism-Vault

Skills

Method Fragments

Operations

Releases

Changelog

Prism History

Case Studies

Legal

INSTALL

Installing Prism

Quick install — one command (per ADR-030)

Three backend modes

Manual install (advanced)

Prerequisites (auto-installed by `prism install`)

Building the CLI by hand

Windows line-ending note

Choosing a mode

Local install

LAN install

Cloud install (deferred)

What `prism install` does (all modes)

The `coder` launcher — agent-aware sessions

Identity (`-as <Identity>`)

`-mode` and `-autonomy` — what they actually do, per agent

Deprecated flags — `-install-deps` and `-activate-venv`

Codex prerequisites

Flags

Re-running / idempotency

Uninstall

Troubleshooting

Updating Prism

Server-side install (separate concern)

​Installing Prism

​Quick install — one command (per ADR-030)

​Three backend modes

​Manual install (advanced)

​Prerequisites (auto-installed by prism install)

​Building the CLI by hand

​Windows line-ending note

​Choosing a mode

​Local install

​LAN install

​Cloud install (deferred)

​What prism install does (all modes)

​The coder launcher — agent-aware sessions

​Identity (-as <Identity>)

​-mode and -autonomy — what they actually do, per agent

​Deprecated flags — -install-deps and -activate-venv

​Codex prerequisites

​Flags

​Re-running / idempotency

​Uninstall

​Troubleshooting

​Updating Prism

​Server-side install (separate concern)

Installing Prism

Quick install — one command (per ADR-030)

Three backend modes

Manual install (advanced)

Prerequisites (auto-installed by `prism install`)

Building the CLI by hand

Windows line-ending note

Choosing a mode

Local install

LAN install

Cloud install (deferred)

What `prism install` does (all modes)

The `coder` launcher — agent-aware sessions

Identity (`-as <Identity>`)

`-mode` and `-autonomy` — what they actually do, per agent

Deprecated flags — `-install-deps` and `-activate-venv`

Codex prerequisites

Flags

Re-running / idempotency

Uninstall

Troubleshooting

Updating Prism

Server-side install (separate concern)