Fabric Quickstart

Get started with Fabric in under 5 minutes.

What is Fabric?

Fabric is an agent session manager and terminal multiplexer. It lets you:

• Start and manage AI coding agent sessions (Claude Code, Codex, etc.)
• Pair devices for distributed session execution
• Install hooks to integrate with IDE tools

Install

npm install -g fabric

Verify:

fabric --version
# fabric v0.10.0

Quick setup

1. Initialize config

fabric init

This creates ~/.optimalos/config.json.

2. Start the server

fabric start

The server runs on http://localhost:3000.

3. Use the CLI

fabric --help

You can start agent sessions, pair devices, and manage hooks.

Device pairing (cloud mode)

If using Fabric with a cloud controller:

1. On the host: Mint a pairing token from the web interface
2. On the device:

   fabric pair <token>

3. Verify: Check ~/.config/optimalos/device.jwt exists

Claude Code hooks

Fabric can install hooks for Claude Code:

# Install hooks
fabric hooks install

# Check status
fabric hooks status

# Uninstall
fabric hooks uninstall

This wires Claude Code's lifecycle hooks to the local fabric-agent.

Agent daemon (Linux)

On Linux, you can run fabric-agent as a background service:

# Install as user service
bash scripts/install-agent.sh install

# Check status
systemctl --user status optimalos-agent

Config options

Edit ~/.optimalos/config.json:

{
  "port": 3000,
  "authPassphrase": null,
  "agents": [
    {
      "name": "claude",
      "command": "claude",
      "enabled": true
    }
  ]
}

Next steps

• Read the Runbook for operational guidance
• Check the Install page for advanced setup