Daemon Lifecycle

What lives on disk

inference-relay touches three locations on the host:

The application:

  • macOS: /Applications/inference-relay.app/
  • Windows: C:\Users\<user>\AppData\Local\inference-relay\

The user state directory (~/.inference-relay/):

  • settings.json — license key (0600 perms), working directory, port override, builtin tools toggle
  • recent-calls.jsonl — append-only call log, capped at 1000 lines, license-key-redacted
  • mcp-state/ — per-session tools-file IPC for the bundled MCP server
  • pty-pids.json — daemon's process-tree registry, used for orphan-cleanup on next launch

Attachment tempfiles ($TMPDIR/subscription-relay-attachments/):

  • Per-call base64-decoded payloads. Unlinked on call return; swept every 15 minutes for leaks.

That's it. Nothing in registries, system services, or /usr/local/lib/.

Install

Download the installer for your platform from /changelog/v1.1, then:

  • macOS arm64: Drag inference-relay.app to /Applications
  • macOS x86_64: Drag inference-relay.app to /Applications
  • Windows x64: Run inference-relay_<version>_x64-setup.exe (NSIS)

The installer is unsigned during the v1.1 launch window — Gatekeeper / SmartScreen warns once on first launch. Right-click → Open on Mac, "More info" → "Run anyway" on Windows. Signed releases are on the roadmap.

First launch + license activation

Launch from /Applications (Mac) or the Start menu (Windows). The Setup Wizard:

  • Checks for claude on PATH, in ~/AppData\npm\ (Windows), ~/.bun/bin/ (cross-platform), and ~/.vscode/extensions/anthropic.claude-code-* (the VSCode extension bundle).
  • If claude is missing, displays platform-specific install commands.
  • Once claude is found, accepts an ir_live_... license key, round-trips RS256-signed validation against api.inference-relay.com, and writes ~/.inference-relay/settings.json.

The daemon binds 127.0.0.1:7421 and is now serving. Closing the shell window leaves the daemon running.

Starting headless

After first-run setup, the daemon binary can be launched directly without the GUI. See Headless for full recipes (launchd plist for macOS, Task Scheduler for Windows). Short form:

# macOS — foreground for debugging
/Applications/inference-relay.app/Contents/MacOS/inference-relay-daemon
# Windows — background, no window
Start-Process `
  -FilePath "C:\Users\$env:USERNAME\AppData\Local\inference-relay\inference-relay-daemon.exe" `
  -WindowStyle Hidden

Stopping

# Find + kill
pgrep -fl inference-relay
kill <pid>
# Windows
Get-Process inference-relay* | Stop-Process

The daemon traps SIGTERM (Unix) / WM_CLOSE (Windows), drains in-flight calls, kills all child PTYs (claude subprocesses), and exits cleanly.

Two daemons on one machine

Don't. The port bind is exclusive; the second daemon will fail to start with Address already in use. If you're running both a dev install and a release install:

  • Run only one at a time, OR
  • Set SR_DAEMON_PORT differently for each (e.g., dev on 7422, release on 7421) and point each SDK at the right port via separate baseURL values.

Upgrading

Manual: download the new installer from /changelog/<version>, run it. The Windows installer detects the prior version and offers to uninstall first. macOS install replaces inference-relay.app.

Auto-update: the Tauri shell polls api.inference-relay.com/v1/desktop/update/<target>/<arch>/<current_version> every 4 hours and on launch. If a newer ed25519-signed bundle is available, the shell downloads it, verifies against the embedded pubkey, then applies — restarting the daemon to the new version.

Manual check via tray menu → "Check for updates."

Auto-update needs the Tauri shell to be runningat least once per polling interval. Headless-only installs receive update notifications via the daemon's /v1/version endpoint but don't self-apply.

Uninstalling

macOS:

# Stop + remove app + clean state
pkill -f inference-relay
rm -rf /Applications/inference-relay.app
rm -rf ~/.inference-relay/
rm -f ~/Library/LaunchAgents/com.inference-relay.daemon.plist  # if you set up launchd

Windows:

  • Settings → Apps → "Inference Relay" → Uninstall (silent: <path>\uninstall.exe /S)
  • Manually: Remove-Item -Recurse $env:USERPROFILE\.inference-relay
  • Remove Task Scheduler entry if set up: schtasks /delete /tn "Inference Relay Daemon" /f

The uninstaller does NOT remove your license from api.inference-relay.com — your subscription persists. Reinstall and paste the key again to resume.

Resetting state

To wipe all local state without uninstalling the binary:

pkill -f inference-relay
rm -rf ~/.inference-relay/
# Relaunch the app → Setup Wizard reappears

Useful when:

  • License key got rotated and you want a clean activation flow
  • recent-calls.jsonl grew too large (>10 MB, rare)
  • pty-pids.json got corrupted across an OS update

Where to go next