Server Startup and Secure Access

Start with Deploy a Remote Server, then connect Desktop, Web or CLI. The distributed archive and container target Linux x64. macOS/Windows clients can connect to that server. There is no supported macOS/Windows server archive or automatic launchd installer in this distribution; a source development server is a separate advanced setup.

Running at startup

For a managed Linux archive profile, the quick SSH installer checks that the service account has lingering enabled, and enables its existing systemd user service. The administrator enables lingering explicitly, once:

loginctl enable-linger SERVICE_USER

Run service commands as the dedicated service account:

systemctl --user is-active fabric-agent-server.service
systemctl --user is-enabled fabric-agent-server.service

The service must start after logout/reboot. An installation-time health check alone cannot prove that. Use the private launcher for RPC health/version checks; avoid pasting unredacted journal/environment output into support messages.

For Docker, restart: unless-stopped restarts the container when Docker starts. The host administrator must arrange Docker startup. The named /data volume contains the token, server configuration, provider sign-ins and session data. Back it up privately. Recreating the container preserves that volume; deleting the volume destroys its data. Do not re-run init during an upgrade.

Choose secure access

Keep the server on loopback, or publish the container port only on the host's loopback interface. Do not expose unencrypted port 9100 to the LAN, tailnet or Internet. Never disable certificate validation to repair a connection.

SSH tunnel

The client guide uses local port 19100 to avoid colliding with a local Fabric desktop. Configure FABRIC_WEBUI_WS_URL=ws://127.0.0.1:19100 for that browser path. CLI/desktop use the same loopback WebSocket URL; the browser uses HTTP.

The managed SSH installer supports this loopback setting. Do not add arbitrary keys or change its canonical launcher by hand: lifecycle tools validate managed profiles. Use the container configuration for the public HTTPS examples below, or a deliberately administrator-managed profile with its own documented launcher.

Tailscale Serve

On a host already configured for Tailscale, an administrator can proxy the loopback server through tailnet HTTPS:

tailscale serve --bg http://127.0.0.1:9100

Use the actual HTTPS hostname printed by Serve. Configure the container's public WebSocket URL to wss://THAT_HOST and secure cookies as shown below. Serve access is controlled by your tailnet policy; it does not remove Fabric token login. See Tailscale's Serve reference for privileges and persistence on your host. This guide does not install it or change an existing tailnet's settings.

Reverse proxy

A host-local Caddy example for a real DNS name:

agents.example.com {
    reverse_proxy 127.0.0.1:9100
}

Use a trusted certificate and route DNS to the proxy. Caddy handles WebSocket upgrades; see its reverse proxy reference. If the proxy itself is a container, its 127.0.0.1 refers to that container: choose an explicitly private backend network and native TLS where required instead of exposing the Fabric port publicly.

For nginx, use an HTTPS virtual host with a trusted certificate and forward both HTTP and upgrade requests to the loopback server. A location block includes:

location / {
    proxy_pass http://127.0.0.1:9100;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header X-Forwarded-Proto https;
}

This fragment does not configure TLS, DNS or an access policy. Keep HTTP and WebSocket at the same public origin and forward to only the intended server.

Cloudflare Tunnel

Configure a named tunnel on the server using that host's own sign-in. Route its HTTPS hostname to http://127.0.0.1:9100 and configure the matching public WebSocket URL/secure cookies. Do not transfer a laptop's tunnel credentials or use a temporary public hostname as a permanent deployment contract.

Cloudflare Access and Fabric server authentication are separate. A browser Access login may not work for a native WebSocket client. Fabric CLI does not configure Cloudflare service-token headers automatically. Choose a private-network route or a vendor-supported client access path rather than putting access tokens in the URL or disabling policy. See Cloudflare Tunnel documentation.

Configure public Web UI URLs

For the container, add these non-secret settings to its Compose environment:

FABRIC_WEBUI_PUBLIC_ORIGIN: "https://agents.example.com"
FABRIC_WEBUI_WS_URL: "wss://agents.example.com"
FABRIC_WEBUI_SECURE_COOKIE: "true"

Apply the change with docker compose up -d. The volume and token stay the same. Native TLS instead uses FABRIC_RPC_TLS_CERT and FABRIC_RPC_TLS_KEY, with read-only certificate mounts readable by UID 10001; remove the HTTP opt-in when native TLS is configured. Certificate/key paths are container paths. Keep key files private and do not mount a whole credentials/home directory for one key.

HTTP login succeeding while WebSocket setup fails usually warrants checking the public URL, port, scheme, proxy upgrade and running release before changing any provider sign-in. HTTPS pages must use wss://. Do not trust a guessed forwarded host to select a credential destination; set the intended public UI origin explicitly. Cookie-authenticated WebSocket upgrades require that origin; native bearer clients remain supported without a browser Origin header. For split-port deployments, keep the same cookie hostname and configure the trusted UI origin.

Environment reference

The container filters its child environment and supports only its documented settings. The managed archive helper has a stricter schema; arbitrary additions can make lifecycle validation fail. See all environment variables for the general application, rather than assuming every variable is accepted by every launcher.

Troubleshooting

• Container exits: initialize the volume once, keep its UID/modes, and choose trusted TLS or the explicit loopback HTTP configuration. Do not change HOME to a read-only host directory.
• Empty response or CLI not found: check the dedicated writable service HOME, actual executable ownership/path and that host's vendor sign-in. Discovery is not an authentication/quota test.
• Web UI missing: verify the image/archive, version and asset path. Do not mount over /opt/fabric to repair a volume problem.
• Login works, connection setup fails: verify the advertised socket URL and proxy/tunnel. Do not create duplicate connections as a transport workaround.
• Wrong account: inspect connections in the server's workspace and explicitly choose its slug. Desktop credentials and CLI vendor credentials are distinct.
• Disconnected task: inspect the existing session/history before sending again. A failed client request is not proof the server did nothing.
• Certificate failure: fix the certificate chain/hostname or use SSH loopback. The thin desktop no longer accepts an untrusted configured-server certificate.

For updates and rollback, preserve the private profile/volume and token, finish active work first, deploy a matching release, and retain the prior verified runtime. Image rollback does not undo a data migration.

Managed SSH endpoint recovery

FABRIC_RPC_SOCKET is optional. If its private directory ownership or ancestry checks fail, the server logs that the private endpoint is unavailable and keeps its existing TCP/TLS endpoint running. Inspect the dedicated service profile and permissions before restoring the shortcut. Use the explicit URL/token connection in the meantime; keep its tunnel or trusted TLS endpoint under your control. Do not relax private-directory checks or reuse another user's socket.

For a desktop SSH metadata recovery warning, quit that desktop and inspect the private ssh-workspaces.fabric.json.quarantine-* and ssh-workspaces-recovery.fabric.json files in its configuration directory. Preserve a private backup, repair validated descriptors and their matching native workspace entries, then remove the recovery marker only after checking the mapping. The marker deliberately rejects remote loopback connections after a restart. Local workspaces remain usable; deleting server data is unnecessary.

Source Web UI development

The Vite development proxy verifies backend TLS certificates. Supply a trusted certificate (and a configured CA when needed) instead of disabling verification. For split browser/RPC ports, configure FABRIC_WEBUI_PUBLIC_ORIGIN to the exact browser origin and FABRIC_WEBUI_WS_URL to its reachable same-host WebSocket endpoint. Production embedded deployments normally need neither override.