Environment Setup

Prism ships almost everything it needs. The exceptions are the things it cannot legally or practically bundle — a container engine, a couple of GPL-licensed or platform-level tools — and those are what this page is about.

Nothing here is required to open Prism, edit files, view geometry, or run the agent. Each item unlocks one specific capability, and Prism tells you when one is missing rather than failing quietly.

You do not have to install them by hand. The Set up local tools screen on your first signed-in launch, and Settings → Local tools after it, install most of them for you. This page is the reference behind that screen: what each tool unlocks, and what to do when you would rather install it yourself.

What needs what

Letting Prism install them

Set up local tools appears on the first launch after you sign in, unless every tool is already on the machine. It appears once: however you leave it — Continue, or by quitting Prism from it — the next launch goes straight to the app, and Settings → Local tools has the same cards from then on, so nothing skipped there is lost. A machine that never saw the screen because nothing was missing still gets it once if a tool later goes missing.

One card per tool: what Prism needs it for, a tick box, and the live state of its install.

Docker carries a Recommended badge and is ticked for you; everything else is Optional and unticked. The three language servers share one card.

Install selected (n) runs the ticked installs, Check again re-detects after you install something yourself, and Continue without installing — Continue, once an install has started — moves on. Cancel installs joins them while an install is running and stops the whole run; the tool under way and every tool still waiting read Failed with Cancelled. underneath.

Each tool reports on its own row and settles on its own, so a running install does not lock the screen: you can tick another tool and press Install selected again while the first one works. Only a detection pass, which reads Checking…, holds the buttons.

A row reads Checking…, Not installed, Waiting, Downloading n% — Downloading n MB where the size is not known in advance — Installing…, Installed, Restart needed, or Failed with the error underneath. On Windows, an installed PowerPoint and Word between them cover every format LibreOffice would convert, so that row reads Using Microsoft Office instead. A ticked tool you have to install yourself reads Install with the command below.

Continuing does not cancel a running install: it keeps going and reports into Settings → Local tools.

What each platform does

• Windows — winget installs Docker, Gmsh, LibreOffice, Typst and Node.js one at a time, raising its own UAC prompts. Docker Desktop needs WSL 2, so Prism turns WSL on as part of that install; when Windows needs a reboot to finish, the row says Restart needed and asks you to restart and reopen Prism. After a failure the screen adds a Get App Installer (winget) link, which is the fix when winget itself is missing.

• macOS — downloads run with a progress bar, and every step that needs root runs from one script under a single administrator prompt. LibreOffice, Gmsh and Node.js are pinned to a version and checked against a SHA-256; Docker is the current DMG, verified by its Developer ID team. Docker is opened afterwards so it can finish its own first-run setup.

• Linux — the package-manager installs need root, so Prism shows the commands instead of running them: one apt / dnf / pacman line for the tools you ticked among Docker and LibreOffice, then the Docker group and service steps where they apply, each with a Copy link. Gmsh is a command only on an architecture upstream publishes no build for — on x86_64 Prism installs it itself.

  sudo systemctl enable --now docker
  sudo usermod -aG docker $USER

  Run them in a terminal, then press Check again. Where Gmsh is left to you, Arch installs it with pipx.

Some installs need no administrator at all: the three language servers on every platform, Typst on macOS and Linux, and Node.js and Gmsh on x86_64 Linux. They go into <config>/prism/tools/, which Prism adds to PATH at startup, so a tool installed mid-session is found without a restart. On Windows, Typst and Node.js come from winget like the rest, and a winget install is found without restarting Prism.

Docker

This is the one that matters. Third-party solvers run as containers under navier-solverd. Without a container engine the Solver Desk can report its own state and nothing else.

Ferro is unaffected — it is compiled into Prism and needs no container.

Podman works too. The daemon talks to the Engine API, which Podman's compatibility socket serves, so a Podman machine on macOS or Windows and rootless Podman on Linux both run the catalog. Docker is what the setup screen installs and what the Solver Desk's Install Docker button points at; Podman is one you install yourself and Prism finds.

macOS

Install Docker Desktop for Apple Silicon from docker.com, or Colima if you prefer a CLI-only engine:

brew install colima docker
colima start --cpu 8 --memory 16 --disk 100

Either way Prism finds the CLI. It searches PATH first, then these known locations:

/usr/local/bin/docker
/opt/homebrew/bin/docker
/Applications/Docker.app/Contents/Resources/bin/docker

Windows

Install Docker Desktop and pick either install mode. Prism resolves the CLI from PATH and from both Docker Desktop install layouts, derived from the environment rather than assuming a drive letter:

The installer puts these on the user PATH, which a Prism process started before the install never sees. The fallback lookup covers that case, so you do not have to restart anything.

Linux

Install Docker Engine from your distribution or from docs.docker.com, then add yourself to the docker group so the daemon is usable without sudo:

sudo usermod -aG docker "$USER"
newgrp docker

Prism looks on PATH, then /usr/bin/docker and /usr/local/bin/docker.

Rootless Docker works too, provided the docker CLI on your PATH points at your rootless daemon.

Which engine it talks to

The daemon does not guess at socket paths. It asks each CLI it finds where its engine listens, and takes the first endpoint that answers — so a leftover Docker CLI beside a running Podman does not decide the answer by existing.

DOCKER_HOST is treated as your explicit choice: when it is set, it is the only candidate, and a dead one is reported dead rather than silently swapped for something you did not pick. A DOCKER_HOST that needs TLS is not supported.

Verifying

docker run --rm hello-world

Then open the Solver Desk. It reports the engine's health on its own line — not folded into the daemon's status, because "the daemon is fine, Docker is not" is the most common broken state and deserves to say so. When it is healthy the line names the engine and its version, and hovering it gives the endpoint it reached; when it is not, it says what is wrong, offers a button that fixes it where there is one, and keeps the step-by-step fix — or, for an engine that reported an error, the error itself — behind Details.

Sizing it

Container CPU and memory limits are set in Docker, not in Prism, and they cap everything the daemon can do. Prism's own core budget is computed from the host, so a Docker Desktop VM restricted to 2 CPUs will not deliver the cores the scheduler thinks it reserved.

The daemon's default budget is about three quarters of your physical cores — logical cores halved to account for SMT, except on Apple Silicon, which has none. For OpenFOAM it sizes ranks at roughly 35,000 cells per core, clamped to that budget.

Practical guidance:

• Give the Docker VM at least as many CPUs as Prism's core budget. Settings → Solvers → Core budget override lowers Prism's side if you would rather cap it there.
• Memory is the usual cause of a solver killed mid-run with no useful error. 8 GB is a floor for small cases; 16–32 GB is realistic for meshes worth running.
• Give it disk. Solver images are multi-gigabyte each, and the Solver Desk reports Docker's disk usage so you can see where it went.

File sharing

The daemon bind-mounts your case directory into the container — that is how the solver reads your case and writes results back where you can see them. Only what is mounted is visible inside; nothing else on your disk is.

On macOS and Windows, Docker Desktop only shares configured paths. Keep case directories somewhere shared (your home directory is, by default). A case under a path Docker cannot share fails at mount time, not at solve time.

On Linux, containers run as your uid and gid, so results come back owned by you rather than by root. Docker Desktop already maps ownership on macOS and Windows, so Prism leaves it alone there.

Registries

Installing a runtime pulls a published image. Between them the catalog uses:

• Docker Hub (docker.io) — OpenFOAM, OpenModelica
• GitHub Container Registry (ghcr.io) — the Navier-built images

Both must be reachable. Pulls happen inside the engine rather than in Prism, so a proxy belongs in Docker's own configuration — whatever you set there is what a pull uses.

Optional tools

Every tool in this part of the page is on the Set up local tools screen and in Settings → Local tools, so the commands below are the manual route rather than the only one.

gmsh

Deliberately not bundled: it is GPL-licensed. Prism's own OCCT-backed mesher covers the common path, and gmsh is there when you want it.

brew install gmsh          # macOS
sudo apt install gmsh      # Debian/Ubuntu
pip install gmsh           # any platform, including Windows

On x86_64 Linux, Prism installs gmsh itself rather than leaving it to the package manager: the upstream build goes into <config>/prism/tools/gmsh/, and it keeps working on a machine whose distro packages would refuse to install the distro gmsh. Other Linux architectures keep the command above.

On Windows, use pip install gmsh or the SDK from gmsh.info with its bin folder added to PATH.

Prism resolves gmsh from PRISM_GMSH, then beside its own executable, then PATH — on macOS and Linux the PATH your login shell has, rather than the narrower one a GUI launch inherits, so a Homebrew or pip --user install is found without extra configuration. Prism's own tools folder is on that PATH, so an install it did needs no further setup. When gmsh is missing, the error names what to do on the platform you are on; on Linux it points at Settings → Local tools first.

LibreOffice

Prism previews a .pptx deck or a .docx document by converting it to PDF and handing the result to the bundled PDFium, and LibreOffice is the converter on every platform. Without it those files report the gap instead of rendering; see Documents & Media.

brew install --cask libreoffice                            # macOS
sudo apt install libreoffice                               # Debian/Ubuntu
winget install -e --id TheDocumentFoundation.LibreOffice   # Windows

On Windows, an installed Microsoft PowerPoint or Word is used first — the application that authored the format renders it exactly where LibreOffice re-implements it — with LibreOffice as the fallback. Everywhere else LibreOffice is the only engine.

Prism looks for soffice in the usual install locations (/Applications/LibreOffice.app, /opt/homebrew/bin, /usr/local/bin, /usr/bin, C:\Program Files\LibreOffice). PRISM_SOFFICE points at an install those miss.

Conversions are cached per file, so only the first open of a deck pays the few seconds it takes.

typst

Prism has no built-in Typst report compiler. Install Typst to compile authored .typ files — yours from the command line, or the agent's through the shell.

brew install typst

Node.js

Atlassian, GitHub, Linear, Notion and Sentry are hosted servers that authenticate through your browser, so none of them need Node.js. An MCP server you add yourself may run as a local child process via npx, and that one does.

3DxWare

For a 3Dconnexion SpaceMouse. Prism talks to the 3DxWare driver rather than the device directly, so without the driver there is nothing to talk to. Install it from 3Dconnexion, then check Settings → Input → 3D mouse is on.

git

Used for the editor's gutter markers, the git commands in the command palette, and per-thread worktrees. Prism shells out to your system git binary rather than a bundled one — git's own worktree command handles the corner cases that a library leaves to the caller.

Any recent git will do.

Language servers

Editor diagnostics, hover, completion, and rename come from the Language Server Protocol, so a language gets them when a server for it is installed on your machine. No server, no diagnostics — the editor still works.

Pyright, the TypeScript language server, and rust-analyzer are the three Prism installs for you. Pyright and the TypeScript server are npm packages that run on Node.js, and nothing ticks Node.js for you — tick it alongside them, or their install fails saying Node.js has to be installed first. The npm packages are installed last in a pass, after Node.js, so both can go in one — and in one npm install, so ticking either server installs both. The one you left unticked reads Not installed until the next Check again.

The managed CAD environment

prism_cad_run executes build123d scripts in a hermetic, pinned Python environment that Prism manages for you. You do not install build123d yourself.

• The environment is synced to <config>/prism/cad-env/ the first time it is needed, using the bundled uv.
• That first sync downloads wheels, so it needs a network connection and a minute. Later runs reuse it and re-sync only when the pinned lock changes.
• uv ships beside the Prism executable in packaged installs. In a hand-assembled install, brew install uv (or any uv on PATH) works.
• PRISM_CAD_PYTHON bypasses the managed environment entirely and uses an interpreter you point at — at which point its dependencies are yours to keep working.

Network access

Sign-in uses a PKCE flow that returns to a loopback callback on port 19275. A local firewall that blocks loopback listeners will break sign-in; nothing outside your machine needs to reach that port.

The solver daemon binds port 8420 by default, falling back to any free port if it is taken. It listens locally — Settings → Solvers → Port override changes it.

Environment variables

Mostly for development and unusual installs. None are needed for a normal setup.

Solver daemon tuning — cores, idle shutdown, catalog, port — is exposed in Settings → Solvers rather than through environment variables. All four take effect on the daemon's next start.

Keep the install directory intact

Prism resolves navier-solverd, mesher, PDFium, and the bundled rg/fd/uv relative to its own executable:

macOS    Prism.app/Contents/MacOS/Prism  → ../Resources/bin/…
Linux    <install>/Prism                 → <install>/bin/…
Windows  <install>\Prism.exe             → <install>\bin\…

Copying the Prism binary somewhere on your PATH silently loses all of it. Launch it from where it was installed, or symlink to it — do not move it out.

The bundled bin directory is appended to PATH, not prepended, so a brew-installed rg of your own still wins. Prism only contributes a floor.

Checklist

Before your first real session:

1. Prism launches and you are signed in — Settings → Account.
2. Settings → About shows the bundled tools resolved.
3. docker run --rm hello-world works, if you intend to use third-party solvers.
4. The Solver Desk reports Docker healthy.
5. The Docker VM has CPU, memory, and disk matching the size of case you actually plan to run.
6. gmsh and LibreOffice installed, if you want alternative meshing or .pptx / .docx preview — from Settings → Local tools, or by hand. Typst only if .typ files get compiled; Prism does not generate report PDFs on its own.

If something on that list fails, Troubleshooting takes each case in turn.