Skip to main content

​
LAN Install

LAN mode is for the common team or multi-machine setup: a single Prism backend runs on a home server or internal host, and any number of workstations connect to it as clients. The client does not need Docker — the backend stack lives elsewhere. For personal-mode install (everything on one machine), see Install overview. For setting up the backend server itself, see server-side install.

​
Prerequisites

On the client machine:
  • Node.js 18+ (for the Prism CLI)
  • Git
  • At least one supported editor: Claude Desktop, Claude Code, Cursor, or Codex
  • PowerShell 7+ on Windows (the launcher requires it)
On the LAN:
  • A reachable Prism backend (see server-side install or DEPLOY.md). Default LAN URL on a fresh bin/prism-server-install.sh deployment is http://server1.home.lan:41765.
  • A valid API key for that backend.

​
What you’ll need from the server admin

Two values:
WhatExample
Backend URLhttp://server1.home.lan:41765
API keyprk_...
The URL defaults to http://<--host>:<--port> — so if the server uses the server1.home.lan:41765 convention, you don’t need to pass either flag; just --api-key.

​
Install

One-time CLI build (same for every mode): 
git clone <repo> && cd Prism/cli
npm install && npm run build && npm link
Then the LAN install: 
prism install \
    --mode lan \
    --host server1.home.lan \
    --api-key prk_...
On a TTY with no --mode, you’ll get an interactive 1/2/3 picker — choose 2 for LAN. Override --port <n> if the server runs on a non-default port.

​
What the installer does

prism install --mode lan runs these steps in order:
  1. LAN preflight — verifies /health is reachable on the target URL and that the API key authenticates against /api/v1/projects. Fails loudly with one message per issue, before touching any config files. Common causes of failure here: wrong URL, wrong key, firewall blocking the port, backend down.
  2. MCP Node-shim build — runs npm install and tsc in mcp-node/ so mcp-node/dist/server.js exists and is fresh. Idempotent: skips the build when dist is newer than every src file. Per SPEC-054 the MCP shim is Node, not Python — there is no mcp/.venv, no pip install, and no Python prereq.
  3. Credentials file — writes ~/.prism/credentials.personal.json with mode:"lan", the resolved URL, and the API key. The coder launcher and prism status both read this file.
  4. Editor MCP blocks — writes the mcpServers.prism block into each detected editor’s config (Claude Desktop, Claude Code, Cursor, Codex), pointing command at node, args at the absolute path to cli/dist/mcp-launcher.js, and env at the LAN URL + key + per-editor identity vars (e.g. PRISM_AGENT_SURFACE). The launcher is a thin indirection: on every editor restart it stats mcp-node/src/ against mcp-node/dist/, rebuilds when stale, then spawns the real Node shim with stdio inherited — keeping running editors current even when restarts bypass prism install and prism update.
  5. Launcher setup — chmod + symlink bin/coder → coder.sh on Unix; bin/coder.cmd shim invoking pwsh on Windows. Managed block appended to ~/.zshrc / ~/.bashrc (Unix) or User PATH updated via [Environment]::SetEnvironmentVariable (Windows).

​
Retrieving the server API key

On the backend machine (requires SSH access): 
sudo docker exec prism-server-backend cat /root/.prism/credentials.json
# → {"tenant_slug":"personal","api_key":"prk_...","label":"personal-bootstrap"}
If the key in this file returns HTTP 401 against the live backend, it’s stale — the bootstrap key was regenerated and the credentials file was not re-synced. Workaround: borrow the current working key from any already-connected LAN client’s ~/.prism/credentials.personal.json, which carries the key the server actually accepts right now.

​
Verifying the install

After prism install --mode lan completes: 
prism status
Should print the backend health + mode + project count. Example: 
Prism — personal install status
  Backend: ok v0.1.0 mode=personal
  Projects: 5
(Counter-intuitively the backend reports mode=personal even in LAN deployments — mode on the backend side describes backend provisioning, not install mode. The client-side mode is lan and lives in the credentials file.) Then restart your editor(s) to pick up the new MCP configuration. Claude Desktop / Cursor / Codex re-read MCP config on launch. Claude Code picks it up on the next claude invocation.

​
Troubleshooting

SymptomFix
preflight: backend unreachable at …Backend down, or client can’t route to it. Verify from the client: curl http://server1.home.lan:41765/health. If that fails, check DNS / firewall / Docker health on server1.
preflight: api key authenticates → 401Stale key (see Warning above) or tenant isolation mismatch. Get the current key from a working client’s credentials file.
Editor shows Prism connected but verbs failCheck PRISM_API_URL in the editor’s MCP config — it should be the LAN URL, not http://127.0.0.1:.... If wrong, re-run prism install --mode lan.
coder: command not found in new shell$PRISM_ROOT/bin not on PATH. Re-run prism install; it appends the managed block to ~/.zshrc (Mac/Linux) or User PATH (Windows). Open a fresh shell.
Signals don’t deliver in real-time between agentsThe signal mesh runs over the FastAPI WebSocket data plane (/api/v1/session/ws); Redis stays internal to the backend per SPEC-045. If push isn’t landing, check that the LAN client can reach :41765 and that prism status shows mode=lan. Signals also drain on the next prism_start and ride along on every verb response, so nothing is lost while you debug. See the Signal Mesh page for the full lifecycle.

​
Uninstall

prism uninstall
Removes the prism MCP block from each editor, strips the managed PATH block from the shell rc / User PATH, removes the coder symlink or coder.cmd shim. Credentials file is left in place (keys are sensitive but cheap to regenerate; easier to keep them than re-copy after a re-install).

​
What LAN install does NOT cover

  • Running the backend itself. If you need to stand up server1 or equivalent, see server-side install.
  • Cloud-hosted Prism. Not yet available; will use prism login flow when it ships. See Install overview.
  • Per-persona daemon (SPEC-070). The always-on listener daemon ratified by SPEC-070 v0.2 / ADR #42 is forthcoming. When it ships, it’ll run as a user-level launcher unit (LaunchAgent / systemd-user with linger / Task Scheduler logon-trigger) on each LAN client, own WS continuity across editor idle/suspend, and absorb project-bootstrap responsibilities (deps install, venv activation) currently parked as no-op deprecations on bin/coder. See INSTALL.md §“Deprecated flags” for the launcher-flag migration status.
Last modified on May 22, 2026