Connect Desktop, Web and CLI

All four clients use the same Fabric server and workspaces. Install the server first using Deploy a Remote Server, then choose how you want to work:

Use matching releases. The server owns its workspaces, files, provider accounts, subscription usage and source credentials. Signing into a vendor on your laptop does not sign in the server. Configure each connection once on the server; every authorized client can then use it. A server token grants access to that server's workspaces, so use separate service accounts/profiles for independent users.

Establish a secure endpoint

For SSH, keep a tunnel open in a separate terminal:

ssh -N -o ForwardAgent=no -o StrictHostKeyChecking=yes \
  -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 \
  -L 127.0.0.1:19100:127.0.0.1:9100 SERVICE_USER@SERVER

Verify and enroll a new host key through your normal SSH procedure first. The desktop/CLI URL is ws://127.0.0.1:19100; the browser URL is http://127.0.0.1:19100. The current embedded Web UI derives the WebSocket address from the browser origin, preserving the forwarded port. Older servers, or an explicit FABRIC_WEBUI_WS_URL, require that override to match the browser endpoint. Remove or update a stale override when changing the local port. A successful SSH login alone does not open a tunnel.

For a trusted HTTPS deployment, use wss://YOUR_HOST in native clients and https://YOUR_HOST in a browser. See secure access and startup. Plaintext LAN/tailnet WebSockets and untrusted certificates are refused. Keep tokens out of URLs, shell arguments, screenshots and shared logs.

Desktop app: hybrid mode

1. Open Fabric Agents normally.
2. Open the workspace switcher and choose Add Workspace → Connect to Remote Server.
3. Choose Connect using SSH for a matching managed archive profile with a private endpoint. Enter the SSH alias or user@host; use Advanced profile settings only for a non-default profile root.
4. Choose Check server, select a remote workspace or explicitly create one, then Connect. Fabric retrieves the server token privately and owns/reconnects the tunnel. No token is shown in this flow.
5. Select that workspace in the switcher and choose its server-owned connection.

This shortcut requires a matching release and a profile started with its private FABRIC_RPC_SOCKET endpoint (fresh managed profiles from 0.15.20). It does not install software or restart an existing service. Upgrade an older profile explicitly first. Unknown or changed SSH host keys require your normal terminal verification; Fabric never accepts them automatically.

For Docker, custom profiles and older servers, choose Use server URL and token. Enter the trusted wss:// URL or an explicitly managed loopback tunnel URL, provide the token privately, then Test Connection. That manual tunnel remains your responsibility; the automatic SSH profile lifecycle does not adopt it. Removing an automatically connected SSH workspace closes only its windows, clients and tunnel; it does not remove server data.

Saved SSH connections are checked in the background when the desktop starts. An offline server does not delay local workspaces; Fabric keeps its loopback listener reserved and retries. Open Add Workspace → Connect using SSH to see the saved connection status and retry immediately. A version mismatch names the required server version; an administrator must upgrade that profile explicitly. Reconnecting the same host/profile/workspace reuses its saved entry. Damaged SSH metadata is quarantined in the private configuration directory and requires operator recovery; it does not reset local workspaces or server data.

Local workspaces remain available. Changing a connection or a source in the remote workspace changes the server's configuration. A disconnected remote workspace shows its connection state; reconnect to the same workspace to resume. An uncertain create result should be inspected before creating another workspace.

Hybrid is the simplest choice when you want local and remote work in the same desktop. The Machines/fleet beta is not required for ordinary remote workspaces.

Desktop app: thin client

Thin mode connects the entire desktop to one server. Quit existing Fabric desktop instances before changing this whole-app mode; otherwise a second launch may only focus the already running instance. Use hybrid mode to keep both kinds of workspace open together.

Supply the URL and token through the launch environment. In Bash on Linux or macOS, read the token privately rather than typing it into a command:

export FABRIC_SERVER_URL=ws://127.0.0.1:19100
read -r -s -p 'Fabric server token: ' FABRIC_SERVER_TOKEN
printf '\n'
export FABRIC_SERVER_TOKEN

On Linux, launch fabric-agents from that shell after installing the desktop with the Fabric installer. On macOS, launch the installed executable directly so it receives the environment:

"/Applications/Fabric Agents.app/Contents/MacOS/Fabric Agents"

For a source development checkout with dependencies/builds ready, use bun run electron:start. On Windows, set $env:FABRIC_SERVER_URL, read the token using the PowerShell example below, and launch fabric-agents from the same terminal if you used the Fabric installer, or run your installed desktop executable.

Thin startup discovers workspaces from the server, rather than restoring a local workspace ID. Set FABRIC_WORKSPACE_ID to a remote ID from fabric-cli workspaces if you want a particular workspace. A missing ID opens the server's first workspace; an unknown explicitly selected ID reports an error. An empty server opens its existing onboarding/picker. No default local workspace is created by thin startup. Desktop UI/window state still exists locally; thin mode is not a claim that the computer is stateless.

The desktop does not accept an untrusted certificate just because the server was configured explicitly. Use a trusted certificate or the loopback SSH path.

Web UI

Open the browser endpoint and log in. Usually its password is the Fabric server token; an administrator can configure a separate FABRIC_WEBUI_PASSWORD. The server issues an HTTP-only, server-scoped session cookie. Updating from the old shared cookie requires signing in again. Cookies are host-scoped, not port-scoped: use distinct trusted HTTPS names for stronger separation between independent servers. Do not put the token in a URL or browser storage yourself.

Use Add Connection in this server's UI for provider setup. A Claude Account browser authorization page may open on your computer, but the connection is stored on the server. For vendor CLI connections, install and sign in to the CLI under the server/container's dedicated HOME/XDG profile. Account setup shows Runs on and Service profile, offers the profile-specific sign-in command and Check again. On a managed SSH workspace, Sign in on server can open a terminal; if it does not open, copy the displayed command. CLI availability is reported separately from sign-in/remaining allowance, which can remain unknown. See server CLI providers.

The Web UI shares the session interface but cannot host native desktop windows, file reveal dialogs or the local browser automation capability. If login works but provider setup says WebSocket connection failed, first verify the tunnel, running version and advertised WebSocket URL. That error does not prove that a provider rejected your account. Reconnect explicitly; do not repeatedly create new provider connections to repair a transport error.

Fabric CLI

The standalone installer is delivered with the next matching CLI release. After publication, Linux/macOS users can run:

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

Windows users can download the PowerShell installer and run it explicitly:

Invoke-WebRequest https://agents.fabric.pro/install-cli.ps1 -OutFile install-cli.ps1
./install-cli.ps1

The installers verify the archive checksum/version and preserve an unrelated existing command. Open a new terminal or add the printed directory to PATH. Run fabric-cli --version and fabric-cli --help before connecting. The desktop installer and CLI installer are separate; installing the desktop alone does not prove a global CLI exists. No Bun installation is needed for remote CLI commands.

In Bash, set the URL and use the hidden token prompt shown above. For PowerShell:

$env:FABRIC_SERVER_URL = 'ws://127.0.0.1:19100'
$secret = Read-Host 'Fabric server token' -AsSecureString
$pointer = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($secret)
try { $env:FABRIC_SERVER_TOKEN = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($pointer) }
finally { [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($pointer) }

Then inspect the selected server without making model calls:

fabric-cli --json ping
fabric-cli --json workspaces
fabric-cli --json connections

Choose the returned workspace ID and connection slug deliberately. For example:

fabric-cli --workspace REMOTE_WORKSPACE_ID --json session create \
  --name 'Remote work' --mode ask --connection CONNECTION_SLUG --model MODEL_ID

Retain the returned session ID, then send the task:

fabric-cli --workspace REMOTE_WORKSPACE_ID send SESSION_ID 'Inspect this project'
fabric-cli --workspace REMOTE_WORKSPACE_ID session messages SESSION_ID
fabric-cli --workspace REMOTE_WORKSPACE_ID cancel SESSION_ID

Sending a task uses the server's selected account and may consume its allowance. An account/model listing is not evidence of authentication or remaining quota. Approval checkpoints must be resolved in a capable connected Fabric UI; the CLI does not provide an interactive approval/TUI replacement. Choose unattended permissions only deliberately. A lost connection is an error, not an instruction to create or send a second task automatically.

fabric-cli run is a different, local one-shot workflow. It needs a local server runtime/Bun and defaults to unattended execution; it does not become a remote run because a URL is set. A configured remote URL is now rejected for run to prevent accidental local execution. Use session/create/send for remote work and subscription connections. See CLI reference, including the Fabric Code migration and installer update/uninstall instructions.

Browser tools and client capabilities

The server can bridge browser tools to a connected desktop in the same workspace. The browser runs on that computer with its local browser state. Web/CLI clients do not host those windows. Keep a capable desktop connected if a task needs them; otherwise the server reports that no browser host is available.

Remote upload is unavailable and remote JavaScript evaluation remains disabled by default. See remote browser ownership. Native dialogs, desktop settings and voice are client capabilities, not a claim that every desktop-only action is available in a Web or CLI client.

Version and connection failures

Deploy matching client/server releases and check both versions. Protocol incompatibility fails the handshake; an ordinary compatible connection is not a guarantee that every feature in a newer client exists on an older server. Machines beta checks are stricter and require the matching installed runtime.

Check the server URL/profile/version before changing credentials. A browser cookie, the server bearer token, a provider account, a CLI's host-local sign-in and subscription quota are distinct states. Never repair one by copying another machine's credential directories.