Remote setup requirements

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 on the remote 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 "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).

Requirements

• macOS 14.6+ (Sonoma) for Scarf
• iOS 18.0+ for ScarfGo (the iPhone companion, public TestFlight from v2.5)
• Xcode 16.0+ to build from source
• Hermes agent v0.6.0+ installed at ~/.hermes/ on each target host (v0.14.0+ recommended for full v2.9 feature support — /subgoal / /yolo / /sessions / /codex-runtime slash commands, xAI Grok OAuth + NovitaAI providers, LINE + SimpleX Chat platforms, Brave Search + DuckDuckGo web-search backends, MCP supports_parallel_tool_calls, Hermes Proxy local server, ACP --setup-browser, YOLO mode warning, Alibaba → Qwen Cloud display rename, docker_extra_args, display.timestamps, Cron deliver=all, Discord channel-history backfill, plugin tool_override badge, cross-session 1h Claude prefix cache. v0.13.0 still works for the v2.8 surface — Persistent Goals, ACP /queue, Kanban hallucination gate + diagnostics, Curator archive/prune, Google Chat, MCP SSE, etc.)
• For remote servers: SSH access (key-based), sqlite3 on the remote (for atomic DB snapshots), and the hermes CLI resolvable from the remote user's PATH or at a path you specify per server. ScarfGo requires the same on every Hermes host it connects to.

Dependencies

Everything else uses system frameworks: SQLite3 C API, Foundation JSON, AttributedString markdown, SwiftUI Charts, GCD file watching.

ACP `--setup-browser` + YOLO warning

• "Set up browser tools" button on the Health view header (v0.14+) runs hermes acp --setup-browser --assume-yes to install Chromium and provision Playwright in one shot. Inline status strip + 10-minute timeout (chromium download is slow).
• YOLO mode warning — chat-header amber chip renders when approvals.mode = yolo and the host advertises hasYOLOWarning. Wired through ChatViewModel.approvalMode, refreshed off MainActor with the existing config diagnostics.

Install

Build from Source

git clone https://github.com/awizemann/scarf.git
cd scarf/scarf
open scarf.xcodeproj

Or from the command line:

xcodebuild -project scarf/scarf.xcodeproj -scheme scarf -configuration Release -arch arm64 -arch x86_64 ONLY_ACTIVE_ARCH=NO build

For an unsigned local Debug build without an Apple Developer account (handy for contributors), use ./scripts/local-build.sh — see BUILDING.md for prerequisites.

What You Can Build

• Development dashboards — test coverage, build status, open issues, sprint progress
• Data project trackers — pipeline metrics, data quality scores, processing throughput
• Deployment monitors — deploy history tables, uptime stats, error rate charts
• Research dashboards — experiment results, key findings, paper status checklists
• Agent activity views — cron job results, content generation stats, task completion rates
• Embedded web apps — local dev servers, HTML reports, Grafana dashboards, any web-based tool your agent generates
• Any project status — if your agent can measure it, Scarf can display it

Quick Start

1. Create the dashboard file

Create .scarf/dashboard.json in any project folder:

{
  "version": 1,
  "title": "My Project",
  "description": "Project status at a glance",
  "sections": [
    {
      "title": "Overview",
      "columns": 3,
      "widgets": [
        {
          "type": "stat",
          "title": "Test Coverage",
          "value": "87%",
          "icon": "checkmark.shield",
          "color": "green",
          "subtitle": "+2.1% this week"
        },
        {
          "type": "progress",
          "title": "Sprint Progress",
          "value": 0.73,
          "label": "73% complete",
          "color": "blue"
        },
        {
          "type": "list",
          "title": "Tasks",
          "items": [
            { "text": "Write unit tests", "status": "done" },
            { "text": "Update API docs", "status": "active" },
            { "text": "Deploy to prod", "status": "pending" }
          ]
        }
      ]
    }
  ]
}

2. Register your project

In Scarf, go to Projects in the sidebar and click the + button to add your project folder. Or have your agent add it directly to the registry at ~/.hermes/scarf/projects.json:

{
  "projects": [
    { "name": "my-project", "path": "/Users/you/Developer/my-project" }
  ]
}

3. View in Scarf

Select your project in the Projects sidebar — the dashboard renders immediately. Scarf watches the file for changes and refreshes automatically whenever the JSON is updated.

`/subgoal` and three new chat-config slash commands

• /subgoal <text> — layers extra success criteria onto an active /goal loop. Forms: <text> (add), remove N (drop the Nth), clear (empty the list). Optimistic local mirror on RichChatViewModel.activeSubgoals; the goal pill in the chat header gains a +N count badge with the full list in the hover tooltip.
• /yolo — toggles dangerous-command auto-approval (approvals.mode = yolo) without leaving chat. Pairs with a new amber YOLO warning badge in the chat header so the state is always visible.
• /sessions — browse and resume prior sessions inline.
• /codex-runtime [auto|codex_app_server] — toggle the Codex app-server runtime for OpenAI/Codex models.
• /handoff intentionally NOT in the ACP menu — verified against Hermes's command catalog: v0.14's /handoff <platform> is cli_only and hands a session to a messaging platform (Telegram/Discord/etc.), not to a different model. Mid-chat model switching keeps using the existing session/set_model RPC via the chat-header model badge.

MCP, settings, plugin additions

• MCP supports_parallel_tool_calls — new optional flag on MCP server entries. Tri-state picker in the editor ("Default (Hermes decides)" / "Enabled" / "Disabled") writes supports_parallel_tool_calls: <bool> or drops the key entirely.
• terminal.docker_extra_args — extra flags forwarded verbatim to docker run for the docker terminal backend. Comma-separated input; setter splits and serializes to YAML.
• display.timestamps — per-message timestamp toggle for TUI output. (ACP-relayed chat in Scarf shows turn-duration chips independently, so this only affects the CLI.) Also fixed a pre-existing v0.13 oversight: display.language was in the model but the YAML parser wasn't reading it back at load.
• Cron deliver=all — fan-out routing intent for cron jobs. Field placeholder + helper text updated on v0.14.
• Discord channel-history backfill — default-on toggle for the v0.14 channel-history-read-on-join behavior; lets users opt out for noisy channels.
• Plugin tool_override badge — plugins that declare tool_override: true in their manifest now render a visible badge in PluginsView so overridden built-in tools aren't a surprise.

Configure *(new in 1.6)*

• Platforms — Native GUI setup for all 13 messaging platforms (Telegram, Discord, Slack, WhatsApp, Signal, Email, Matrix, Mattermost, Feishu, iMessage, Home Assistant, Webhook, CLI). Per-platform forms write credentials to ~/.hermes/.env and behavior toggles to ~/.hermes/config.yaml. WhatsApp and Signal pairing use an inline SwiftTerm terminal for QR scan and signal-cli daemon management
• Personalities — List defined personalities, pick the active one, and edit SOUL.md inline with markdown preview
• Quick Commands — Editor for custom /command_name shell shortcuts with dangerous-pattern detection (rm -rf, mkfs, etc.)
• Credential Pools — Per-provider credential rotation with a fixed OAuth flow (URL extraction + browser open + code paste) and proper --type api-key handling. API keys never stored in UI state — only last-4 preview. Strategy picker (fill_first / round_robin / least_used / random)
• Plugins — Install via Git URL or owner/repo, update, remove, enable/disable. Reads ~/.hermes/plugins/ directly for reliable state
• Webhooks — Create, list, test-fire, and remove webhook subscriptions. Detects the "platform not enabled" state and links to gateway setup
• Profiles — Switch between multiple isolated Hermes instances. Create, rename, delete, export (zip), import. Safe-switch warning reminds users to restart Scarf after activating a different profile
• Hermes Proxy (new in 2.9, Hermes v0.14+) — Launch the OpenAI-compatible local proxy that forwards requests to your OAuth-authenticated upstream provider (Nous Portal in v0.14; more adapters as Hermes adds them). Status card with running/stopped badge, endpoint URL with copy button (http://127.0.0.1:8645/v1), provider picker, live log tail, and a usage-help card. Point Codex CLI / Aider / Cline / VS Code Continue at the endpoint and any bearer token works — the proxy attaches your real credential

Dashboard Schema Reference

{
  "version": 1,
  "title": "Required — dashboard title",
  "description": "Optional — subtitle text",
  "updatedAt": "Optional — ISO 8601 timestamp",
  "sections": [
    {
      "title": "Section Name",
      "columns": 3,
      "widgets": [{ "type": "...", "title": "..." }]
    }
  ]
}

Each section defines a grid with 1–4 columns. Widgets flow left-to-right, wrapping to new rows. See DASHBOARD_SCHEMA.md for the full schema reference with examples of every widget type.

Troubleshooting remote connections

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. Open Manage Servers → 🩺 Run Diagnostics (or click the yellow "Can't read Hermes state" pill in the toolbar). The diagnostics sheet runs fourteen checks in one SSH session — connectivity, sqlite3 presence, read access to config.yaml and state.db, the effective non-login $PATH — and tells you exactly which one fails and why, with remediation hints for each. Use the Copy Full Report button to paste the full output into a bug report.

For the common "Hermes isn't at the default path" case (systemd services, Docker), Test Connection in the Add Server sheet now probes /var/lib/hermes/.hermes, /opt/hermes/.hermes, /home/hermes/.hermes, and /root/.hermes when it can't find state.db at ~/.hermes/, and offers a one-click fill if it finds any of them.