Installation

What Jarvis needs to start

• Node 24 or newer and pnpm 10. The repository pins pnpm in package.json; corepack enable is enough to get the right one. Node 22 is not enough: node:sqlite is what the session store is built on, and it is not in Node 22 at all.
• macOS (Apple Silicon), Linux (x64) or Windows (x64). All three are built and run; none is a port of the others. What differs is named where it differs: the Terminal tab's shell (zsh, bash, PowerShell), the voice that speaks (say, Piper, System.Speech), the microphone ffmpeg records from (avfoundation, PulseAudio, DirectShow) and the spelling of every chord.
• On Linux, a C++ toolchain and Python — build-essential and python3 on Debian and Ubuntu, gcc-c++ make python3 on Fedora, base-devel python on Arch. node-pty ships prebuilt binaries for macOS and Windows only, so on Linux — and only there — its native binding is compiled once, by pnpm bootstrap. Every agent session and every Terminal tab is a pty; without it nothing runs.

pnpm install
pnpm bootstrap
pnpm --filter @jarvis/desktop start

pnpm bootstrap is a required step, not a convenience. This workspace runs with install scripts disabled deliberately (see the comment in pnpm-workspace.yaml), which leaves the Electron binary undownloaded and node-pty unbuilt. It performs exactly those two steps, is idempotent, and should be re-run after every pnpm install.

The first run reads ~/.config/jarvis/jarvis.yaml. There must be one: with no config file Jarvis shows "Jarvis failed to start" and quits, because a sensible default for "which agent runs your code" does not exist. The smallest file that works declares one agent and an empty brain — see SETUP.md for it, and configuration for everything else.

Jarvis installs these for you

On its first run — and on any launch where the agent CLI is missing — Jarvis shows a setup screen listing every tool below, what each one unlocks, and whether this machine has it. Tick what you want and press install.

Two things it will not do. It never installs anything until you press the button, and it never runs a command that needs root: those rows show the exact line for the package manager you actually have, with a copy button. Jarvis does not ask for your password.

From a clone, the same thing without the window:

pnpm prereqs              # report only
pnpm prereqs --all        # install everything that needs no root
pnpm prereqs --only=piper,voice-en

(pnpm prereqs, not pnpm setup — that name is a pnpm builtin which configures pnpm's own home directory and would shadow the script.)

Detection asks the login shell's PATH, which is the same PATH Jarvis resolves its sidecars against. A tool installed under nvm is visible to an interactive shell and not to a GUI process, so a check against anything else would tick a box for a tool the app then could not find.

On Windows

Everything above holds. What is specific to Windows:

The agent command. command: claude works when the CLI is on PATH, which is how npm installs it. The native installer puts claude.exe in %USERPROFILE%\.local\bin and does not always add that directory to PATH — if claude is not found, either write the full path in jarvis.yaml or add the directory to your PATH and open a new terminal. An .exe or an npm .cmd shim are both fine: Jarvis resolves a bare name the way a shell does, and starts a .cmd through cmd.exe because Node refuses to run one directly.

The Terminal tab runs PowerShell — PowerShell 7 when pwsh is on PATH, else the Windows PowerShell every machine has. Your own $PROFILE loads first and is never modified; a Jarvis script is dot-sourced after it, which is what draws the blocks, the chip row and autocomplete. It is passed as an encoded command rather than as a .ps1 to execute, so a machine left on the default ExecutionPolicy needs no change to it. Autocomplete ranks against PSReadLine's history rather than a shell's history file.

Chords are Ctrl+Shift, as on Linux — ⌘ does not exist and plain Ctrl belongs to the shell. Ctrl+Shift+P for the palette, Ctrl+Shift+D to split.

Voice. Replies speak through Windows' own System.Speech voices with nothing installed; Piper is better and the setup screen installs it. An Arabic voice is a language pack: Settings → Time & language → Speech. Recording needs ffmpeg, and records from the first DirectShow capture device ffmpeg lists.

The Editor tab is unavailable: code-server has no Windows build. Every other tab works.

What each optional tool unlocks

Jarvis works without all of these; each one is missing only the feature it belongs to, and the feature says so rather than failing quietly.

Tool	Unlocks	macOS	Linux
A coding agent CLI (claude, copilot, …)	Sessions — the point of the app	per that tool	per that tool
code-server	The Editor tab	brew install code-server	curl -fsSL https://code-server.dev/install.sh | sh — not npm i -g
dbgate-serve	The Database tab	npm i -g dbgate-serve	npm i -g dbgate-serve
headlamp-server	The Cluster tab	brew install --cask headlamp	the .deb/.rpm from headlamp.dev
docker	The Docker tab	Docker Desktop or OrbStack	your distribution's docker.io / docker-ce
whisper-cli + a model	Voice input	whisper.cpp	whisper.cpp
ffmpeg	Voice input	brew install ffmpeg	apt install ffmpeg
piper + a voice model	Speech out	piper	the release tarball — see below
An audio player	Speech out	built in (afplay)	pipewire-utils, pulseaudio-utils or alsa-utils

The Terminal and API tabs need nothing installed: the terminal is a pty Jarvis spawns itself, and the API client issues its requests from the main process.

headlamp-server is not distributed on its own — it ships inside the Headlamp desktop app bundle, at resources/headlamp-server relative to the install root on every platform. Jarvis looks for it at the default location for the OS it is running on:

Platform	Default path
macOS	/Applications/Headlamp.app/Contents/Resources/headlamp-server
Windows	%LOCALAPPDATA%\Programs\Headlamp\resources\headlamp-server.exe
Linux	/opt/Headlamp/resources/headlamp-server

headlamp.binary in jarvis.yaml (see configuration) overrides this when Headlamp is installed somewhere else.

Voice

Voice is off unless whisper.binaryPath and whisper.modelPath both point at files that exist. The default model is large-v3-turbo rather than base, and that is deliberate: base mis-transcribes Arabic project names badly enough to break routing, which decides which agent hears an instruction.

Recording goes through ffmpeg, from avfoundation on macOS and from PulseAudio on Linux. PipeWire ships a PulseAudio shim, so -f pulse covers both sound servers and there is nothing to choose.

Piper is a single static binary plus one .onnx model per language. On Linux the release tarball is the least troublesome route, and it wants to land where voice.piperBinary already looks:

curl -fsSL https://github.com/rhasspy/piper/releases/download/2023.11.14-2/piper_linux_x86_64.tar.gz \
  | tar xz -C /tmp
mkdir -p ~/.local/lib/piper ~/.local/bin
cp -r /tmp/piper/* ~/.local/lib/piper/
ln -sf ~/.local/lib/piper/piper ~/.local/bin/piper

Voices come from rhasspy/piper-voices; each is an .onnx and a .json that must sit beside each other. The defaults Jarvis looks for are ~/.config/jarvis/voices/en-gb-alan-low.onnx and ~/.config/jarvis/voices/ar_JO-kareem-low.onnx.

Speaking differs by platform, because macOS has system voices and Linux does not.

On macOS, Arabic is a say voice and English is either a say voice or Piper, whichever the voice picker in Settings is set to.

On Linux there is no say, so both languages go through Piper — and a Piper model speaks one language, so bilingual speech means two models. English is voice.piperModel, Arabic is voice.piperArabicModel. With neither installed, replies are shown and not spoken, and Jarvis says so rather than appearing mute. See configuration.

The hotkey. ⌥Space on macOS, Alt+Space on Linux — but under Wayland no application can register a system-wide shortcut at all, and Jarvis says so at startup. The microphone button and the composer still work; so does binding the shortcut in your desktop's own keyboard settings. An X11 (or XWayland) session has the hotkey as normal.

Why not npm i -g code-server on Linux

It pulls kerberos, a native module, and building it against Node 22+ fails. The install script above ships a standalone build with its own Node and needs no compiler. --method standalone --prefix "$HOME/.local" keeps it entirely inside your home directory, which is enough — Jarvis resolves it on the login shell's PATH.

Putting Jarvis in your application launcher

An AppImage is a single file and does not register itself, so until you tell your desktop about it there is no launcher entry and no icon — which is also why a window started from a terminal shows a generic one.

AppImageLauncher does this for every AppImage you run. By hand it is two files:

./Jarvis-*.AppImage --appimage-extract > /dev/null
mkdir -p ~/.local/share/applications ~/.local/share/icons/hicolor/512x512/apps
cp squashfs-root/usr/share/icons/hicolor/512x512/apps/jarvis.png \
   ~/.local/share/icons/hicolor/512x512/apps/
sed "s|^Exec=.*|Exec=$PWD/$(ls Jarvis-*.AppImage) --no-sandbox %U|" \
   squashfs-root/jarvis.desktop > ~/.local/share/applications/jarvis.desktop
update-desktop-database ~/.local/share/applications

The bundle sets StartupWMClass=jarvis and the window reports WM_CLASSjarvis, so once that entry exists the running window is matched to it and picks up the icon.

Verifying the install

pnpm test        # the whole suite, no network required
pnpm typecheck

A green suite says the code is sound; it says nothing about whether the external tools above are present. Those show up the first time you click the tab that needs one.