SI FabrikDocs
/
sifabrik.com ↗
Server (harnessd)

Server architecture

How harnessd runs the SI Fabrik engine headless on a Linux VM, and how the Mac app talks to it.

harnessd is SI Fabrik's Remote-mode server. It runs the same engine as the Mac app (HarnessCore: orchestrators, trackers, runners, sandboxes, managed git, links and guardrails) without a UI, on a Linux VM inside your network. Team members connect from the Mac app through an SSH tunnel. Secrets, repositories, workspaces and agents all live on the server; clients never hold model or tracker credentials.

Components#

TEXT
  Mac app (Remote mode)                            Linux VM
 ┌──────────────────────┐   HTTPS, TLS 1.3,     ┌──────────────────────────────────────────────┐
 │ Servers → projects   │   pinned certificate  │ harnessd                                     │
 │ Board · Agents · Runs│ ───────────────────▶  │  listen 127.0.0.1:8443   (API, auth, audit)  │
 │ Workflow · Workspaces│   Bearer hs_… token   │  tools_listen 172.17.0.1:7879 (/mcp only)    │
 │ Server Settings      │   via SSH tunnel      │  orchestrators per project (HarnessCore)     │
 │ Sandboxes            │                       │  data_dir: users, audit, repos, logs, history│
 └──────────────────────┘                       └───────────┬───────────────┬──────────────────┘
                                                            │ docker        │ HTTPS + WebSocket
                                                   ┌────────▼──────┐  ┌─────▼─────────────────┐
                                                   │ Agent sandboxes│  │ Cloudflare bridge     │
                                                   │ + egress proxy │  │ (optional)            │
                                                   └────────────────┘  └───────────────────────┘
  • The API listener (listen) serves the authenticated, role-checked and audited HTTP API on loopback, with TLS 1.3. The app reaches it through an SSH tunnel; see Connect the app to a server.
  • The tools listener (tools_listen) serves only /mcp/<session-token>, the agents' tracker tools. It should listen on the Docker bridge address so only containers can reach it. It's the server's equivalent of port 7878 on a Mac.
  • Orchestrators, one per project, exactly as in the Mac app.
  • Docker runs agent sandboxes, as on the Mac: the same images, isolation and egress proxy. Cloudflare sandboxes work through the bridge.
  • The data directory holds accounts, the audit log, cloned repositories, run history, logs and the secrets overlay.

How the app uses it#

  • Projects and board: the app long-polls each project's live state (up to 25 seconds per request) and shows it with the same screens as a local project.
  • Running agents: live transcripts are long-polled too, redacted on the server.
  • Actions: create, move, comment, dispatch, stop, resume; start, stop and pause projects; save the workflow; change settings and secrets. Each is checked against the user's role and recorded in the audit log.
  • Settings: the app's Settings tabs, for the server. Changes are stored in an overlay; harnessd.yaml and secrets.env are never rewritten.

What runs where#

Where
Tracker polling and toolsThe server, with the server's tracker tokens
AgentsThe server's Docker, or Cloudflare via the server's bridge token
Git push and pull requestsThe server, with HARNESS_GITHUB_TOKEN / HARNESS_GITLAB_TOKEN
Model trafficFrom the server's sandboxes, or the gateway the server is configured with
The UIThe Mac app
Coming later

App previews through harnessd; per-device keys with Touch ID / Face ID step-up for dangerous actions; gVisor and short-lived git tokens; iPhone and web clients.

See also#