> ## 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.
# LAN Install
> Install Prism as a client pointing at an existing Prism backend on your local network — Docker not required on the client.
# 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.
```mermaid theme={null}
flowchart TD
ws["Workstation (Mac or Windows)
Claude Desktop · Claude Code · Cursor · Codex
+ Prism MCP server (pointed at LAN URL)
"]
srv["server1.home.lan
Prism backend (FastAPI :41765)
+ Postgres · Neo4j · Redis (internal)
"]
ws -->|"HTTP verbs + WebSocket data plane
(single authenticated transport)"| srv
classDef client fill:#1e40af,stroke:#1e3a8a,color:#ffffff
classDef server fill:#5b21b6,stroke:#4c1d95,color:#ffffff
class ws client
class srv server
```
For personal-mode install (everything on one machine), see
[Install overview](/INSTALL). For setting up the backend server
itself, see [server-side install](/INSTALL#server-side-install-separate-concern).
***
## 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](/INSTALL#server-side-install-separate-concern)
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):
```bash theme={null}
git clone && cd Prism/cli
npm install && npm run build && npm link
```
Then the LAN install:
```bash theme={null}
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 ` 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):
```bash theme={null}
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:
```bash theme={null}
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](/specs/spec-045-v0-2-unified-session-coordination-stream-single-websocket-data-pl). 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](/signal-mesh) page for the full lifecycle. |
***
## Uninstall
```bash theme={null}
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](/INSTALL#server-side-install-separate-concern).
* **Cloud-hosted Prism.** Not yet available; will use `prism login`
flow when it ships. See [Install overview](/INSTALL#cloud-install-deferred).
* **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.