Installation

Fabric Agents ships as a desktop app for macOS, Linux, and Windows. Install takes under a minute on most machines.

One-line install (recommended)

macOS and Linux

curl -fsSL https://agents.fabric.pro/install-app.sh | bash

Windows (PowerShell)

irm https://agents.fabric.pro/install-app.ps1 | iex

The installer fetches the latest release manifest from https://agents.fabric.pro/electron/latest/latest.json, downloads the binary for your platform and architecture, verifies the SHA-512 checksum, and installs. It will not run if the checksum doesn't match.

Where it lands

Your data lives separately at ~/.fabric-agent/ (macOS/Linux) or %APPDATA%\Fabric Agents\ (Windows). Reinstalling keeps your workspaces, sessions, credentials, and settings intact.

Supported platforms

Electron 39 — macOS 12+, Windows 10+, and modern x86_64 Linux distributions with FUSE 2 (most distros).

Auto-update

The app checks for updates on launch against https://agents.fabric.pro/electron/latest. When one is available, you'll see an in-app prompt. Updates verify checksums the same way the first-install does.

If you'd rather control updates yourself, disable auto-update in Settings → App → About, or pick a specific version using the Pre-release channel (see below).

Update channels

Pick an update channel under Settings → App → Updates:

In Pre-release mode the app fetches versions.json (the manifest of pre-release builds) and presents a dropdown — pick a version, click Install to switch to it, or Refresh to re-pull the manifest. Downgrades are supported, so you can pin to a known-good build if a recent pre-release misbehaves.

Switching back to Stable on a machine currently on a pre-release will not roll back to the last stable automatically — install the version you want from the picker first, or wait for the next stable release to ship a higher version.

Build from source

git clone https://github.com/Fabric-Pro/fabric-agents.git
cd fabric-agents
bun install
bun run electron:start

You need Bun 1.3.9+. To build signed distributable artifacts locally see Building for macOS. Linux and Windows build scripts live at apps/electron/scripts/build-linux.sh and apps/electron/scripts/build-win.ps1.

Uninstall

macOS

rm -rf "/Applications/Fabric Agents.app"
rm -rf ~/.fabric-agent        # also removes your data

Linux

rm -f ~/.local/bin/fabric-agents
rm -rf ~/.fabric-agent         # also removes your data

Windows

Settings → Apps → Fabric Agents → Uninstall, or run %LOCALAPPDATA%\FA\Uninstall Fabric Agents.exe. To wipe data, also delete %APPDATA%\Fabric Agents\ and %LOCALAPPDATA%\Fabric Agents\.

Troubleshooting

macOS: "App is damaged and can't be opened" Gatekeeper quarantined the download. The installer normally strips the attribute; if it slips through:

sudo xattr -rd com.apple.quarantine "/Applications/Fabric Agents.app"

Windows: SmartScreen warning Unsigned builds trigger SmartScreen. Click "More info" → "Run anyway". Signed production builds bypass this.

Linux: AppImage won't run (missing FUSE) The wrapper script at ~/.local/bin/fabric-agents falls back to --appimage-extract-and-run automatically on Hyprland, WSL, and systems without FUSE. If you hit problems:

# Verify the wrapper handles your environment
fabric-agents --debug

Logs land in ~/.config/fabric-agents/logs/ (Linux) or ~/Library/Logs/Fabric Agents/ (macOS).

Safe mode (any platform) Launch with fabric-agents-safe or set FABRIC_AGENT_SAFE_MODE=1 to skip loading workspace configs — useful for recovering from a corrupt source config.

Remote install (headless server)

If you want the Fabric Agents server running on a remote machine with the desktop app as a thin client, see the Server section (coming in Phase 2). In short:

# On the server
FABRIC_SERVER_TOKEN=$(openssl rand -hex 32) bun run packages/server/src/index.ts

# On your laptop
FABRIC_SERVER_URL=wss://server.example.com:9100 \
FABRIC_SERVER_TOKEN=<token> \
bun run electron:start

This lets you keep long-running sessions alive between laptop sleeps and run compute-heavy work on a powerful box.