Skip to main content

​
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:
  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 <projects-root>/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

ModeBackend locationWhen to use
LocalDocker on this same machine, loopback 127.0.0.1:8765Solo dev, no shared state
LANExisting Prism backend on your network (e.g. http://server1.home.lan:41765)Multi-machine single-user, or small team sharing one backend
CloudHosted 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:
  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. 
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:
  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):
    EditorIdentitySurface
    claude-desktopDonnaclaude_desktop
    claude-codeDonnaclaude_code
    cursorCursorcursor
    codexCodexcodex
  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 <file>.bak.<timestamp>; 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:
-agentPRISM_AGENT_SURFACEEditor invoked
claude (default)claude_codeclaude
codexcodexcodex
cursorcursorcursor
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 flagCodex flagNotes
-mode interactive--ask-for-approval on-requestDefault.
-mode autonomous--ask-for-approval neverCodex acts without per-step prompts.
-autonomy read--sandbox read-onlyRead-only filesystem.
-autonomy safe-write--sandbox workspace-writeWorkspace writes only.
-autonomy full-local--sandbox workspace-writeSame sandbox; Codex 0.125 has no broader local tier.
-god--dangerously-bypass-approvals-and-sandboxOverrides 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

SymptomFix
prism: command not foundRun cd cli && npm link (once per machine)
Editor still not seeing PrismRestart the editor — GUI apps re-read config on launch
coder: command not found in new shellConfirm ~/.zshrc has the managed block; open a fresh shell tab (PATH changes don’t apply to existing shells)
coder preflight error: no PRISM_API_KEYLocal: run prism up. LAN: seed ~/.prism/credentials.personal.json or re-run prism install with --api-key
Windows PATH change not reflectedSetEnvironmentVariable('User') only applies to new shells; close + reopen
Wrong backend URL after installcat ~/.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 clonecli/dist/ isn’t committed. Run cd cli && npm install — the prepare script builds it.
Claude Desktop shows “Server disconnected” launching the MCP shimThe 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.
Last modified on June 11, 2026