Servers and Remote

Servers & Remote

Scarf 2.0 is multi-server. Each window binds to one Hermes install — your local ~/.hermes/ (synthesized automatically) or any number of remote SSH hosts. Server state lives in ~/Library/Preferences/com.scarf.app.plist via the ServerRegistry.

Adding a remote server

File → Open Server… → Add Server. Fill in:

Field	Required?	Notes
Hostname or alias	yes	Resolved via your ~/.ssh/config. Use whatever you'd type after ssh.
User	optional	Defaults to your local username if absent.
Port	optional	Defaults to 22 (or whatever ~/.ssh/config provides).
Identity file	optional	Specific private key. Otherwise, ssh-agent's loaded keys are tried in order.
Remote home	optional	Override $HOME if Hermes lives outside the SSH user's home.
Hermes binary hint	optional	E.g. /usr/local/bin/hermes if not on the SSH user's PATH.

Test Connection runs a fast probe before saving. If state.db isn't found at ~/.hermes/, it tries /var/lib/hermes/.hermes, /opt/hermes/.hermes, /home/hermes/.hermes, and /root/.hermes (common systemd / Docker layouts) and offers a one-click fill if it finds any.

Remote prerequisites

The remote host must have:

1. SSH access — key-based auth via your local ssh-agent. Scarf never prompts for passphrases; run ssh-add once in Terminal before connecting.
2. sqlite3 on the remote $PATH — needed for the atomic DB snapshots. Install with apt install sqlite3 (Ubuntu/Debian), yum install sqlite (RHEL/Fedora), or apk add sqlite (Alpine).
3. pgrep on the remote $PATH — used by the Dashboard's "is Hermes running" check. Standard on every distro; install procps if missing.
4. ~/.hermes/ readable by the SSH user. When Hermes runs as a separate user (systemd service, Docker container), the SSH user needs read access to config.yaml and state.db. Either (a) SSH as the Hermes user, (b) chmod Hermes's home to be group-readable and add your SSH user to that group, or (c) set the Hermes data directory field when adding the server to point at the right location (e.g. /var/lib/hermes/.hermes).

How remote works under the hood

• Every remote primitive goes through SSHTransport, which multiplexes ssh / scp / sftp through one ControlMaster connection.
• state.db is read from atomic sqlite3 .backup snapshots cached at ~/Library/Caches/scarf/snapshots/<server-id>/state.db.
• File watching uses 3-second mtime polling.
• Chat uses ssh -T host -- hermes acp with JSON-RPC over the tunnel; see ACP Subprocess.

Diagnostics

If the connection pill is green but the Dashboard shows "Stopped", "unknown", or empty values, the SSH user can't read the Hermes state files.

Manage Servers → 🩺 Run Diagnostics (or click the yellow "Can't read Hermes state" pill in the toolbar) runs fourteen checks in one SSH session: connectivity, sqlite3 presence, read access to config.yaml and state.db, the effective non-login $PATH, etc. Each failure explains itself with a remediation hint. Copy Full Report dumps the whole output for bug reports.

Switching the active window

• ⌘1 — local server window.
• ⌘2 … ⌘9 — your saved remote servers in order.
• ⌘⇧S — open the Manage Servers sheet to add / remove / test connections.

See Keyboard Shortcuts.

Related pages

• Transport Layer for the SSH internals (ControlMaster, snapshot mechanics).
• ACP Subprocess for chat over SSH.
• Hermes Paths for what each remote file is.

---

Last updated: 2026-04-20 — Scarf v2.0.1