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:

What	Example
Backend URL	`http://server1.home.lan:41765`
API key	`prk_...`

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:

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.
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.
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.
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.
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 v4.2.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

Symptom	Fix
`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 → 401`	Stale 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 fail	Check `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 agents	The 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.

Introduction

Thesis

Architecture

Prism-Vault

Skills

Method Fragments

Operations

Releases

Changelog

Prism History

Case Studies

Legal

LAN Install

LAN Install

Prerequisites

What you’ll need from the server admin

Install

What the installer does

Retrieving the server API key

Verifying the install

Troubleshooting

Uninstall

What LAN install does NOT cover

​LAN Install

​Prerequisites

​What you’ll need from the server admin

​Install

​What the installer does

​Retrieving the server API key

​Verifying the install

​Troubleshooting

​Uninstall

​What LAN install does NOT cover

LAN Install

Prerequisites

What you’ll need from the server admin

Install

What the installer does

Retrieving the server API key

Verifying the install

Troubleshooting

Uninstall

What LAN install does NOT cover