Optimal

Appearance

Install (Fabric) ​

Fabric v0.10.0 installation and setup.

Prerequisites ​

  • Bun runtime (v1.3.11+) — the project uses Bun for development and production
  • Node.js 20+ (alternative if Bun unavailable)
  • Linux/macOS (Windows via WSL2)

Quick install ​

bash
npm install -g fabric

Local development ​

bash
git clone https://github.com/your-org/fabric.git
cd fabric
bun install
bun run build

Setup ​

Initialize config ​

bash
fabric init

This creates:

  • ~/.optimalos/config.json - Main configuration
  • ~/.optimalos/sessions.json - Session persistence

Edit config ​

bash
nano ~/.optimalos/config.json

Config options:

json
{
  "port": 3000,
  "authPassphrase": null,
  "agents": []
}

Environment variables ​

VariablePurpose
PORTServer port (default: 3000)
AUTH_PASSPHRASERequire login passphrase
OPTIMALOS_DATA_DIRData directory (default: ~/.optimalos)
OPTIMALOS_CONFIG_DIRDevice identity dir (default: ~/.config/optimalos)

Agent daemon (Linux only) ​

Install service ​

bash
bash scripts/install-agent.sh install

This:

  1. Creates ~/.config/optimalos/agent.env
  2. Installs optimalos-agent.service to user systemd
  3. Enables and starts the service

Service management ​

bash
# Status
systemctl --user status optimalos-agent

# Logs
journalctl --user -u optimalos-agent -f

# Stop
systemctl --user stop optimalos-agent

# Uninstall
bash scripts/install-agent.sh uninstall

Persistence across logout ​

bash
sudo loginctl enable-linger $USER

Commands ​

bash
fabric              # Start the server (default)
fabric init         # Create default config
fabric start        # Start the server
fabric start -p N   # Start on port N
fabric pair <token> # Pair this device with cloud
fabric hooks ...    # Manage Claude Code hooks
fabric --help       # Show help
fabric --version    # Show version

Verification ​

bash
# Check version
fabric --version

# Start server in background
fabric start &

# Test health endpoint
curl -s http://localhost:3000/healthz

# Should return 200

Uninstall ​

bash
# Remove global package
npm uninstall -g fabric

# Remove config
rm -rf ~/.optimalos

# Remove device identity
rm -rf ~/.config/optimalos

# Remove agent service (if installed)
bash scripts/install-agent.sh uninstall

Troubleshooting ​

Bun not found ​

bash
curl -fsSL https://bun.sh/install | bash

Permission issues with agent service ​

bash
systemctl --user daemon-reload
systemctl --user restart optimalos-agent

Port already in use ​

bash
fabric start -p 3001

Built by Carlos Lenis in Miami