Bruce Agent

PC-side agent for the Bruce AI command layer.

Features

• WebSocket server for mobile app communication
• Device pairing with QR codes
• Ed25519 signed request verification
• Per-device permissions
• File transfer (send/receive with SHA-256 integrity)
• Clipboard access (read/write)

Setup

# Install dependencies
npm install

# Build shared package first
cd ../../packages/shared && npm run build && cd ../../apps/agent

# Build agent
npm run build

Running

Production Mode (Authentication Required)

npm start
# or
npm run dev

On startup, the agent will:

1. Display a pairing QR payload in the console
2. Wait for mobile app to scan and request pairing
3. Prompt for approval (type y to approve)

Development Mode (Skip Authentication)

For testing without pairing:

ALLOW_UNAUTH=true npm run dev

⚠️ Never use development mode in production!

Always-on with LaunchAgent (macOS)

To keep the agent connected so the dashboard shows the device as Online whenever the Mac is on:

1. Create ~/.bruce-agent.env with RELAY_URL, DEVICE_ID, and DEVICE_SECRET (from pairing).

2. Copy the LaunchAgent plist and load it:

   cp apps/agent/scripts/launchd/com.bruce.agent.plist ~/Library/LaunchAgents/
   launchctl load ~/Library/LaunchAgents/com.bruce.agent.plist

The agent will start at login and restart if it exits. See docs/MVP/launchd-macos.md for the full steps (env example, optional wrapper script, logs, and commands).

Pairing Flow

1. Start the agent - a QR payload will be printed to the console
2. Copy the JSON and convert to a QR code (use any QR generator)
3. Open Bruce mobile app and scan the QR code
4. Approve the pairing request in the agent console (type y)
5. The mobile app will be paired and can now send signed commands

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | BRUCE_AGENT_PORT | 8787 | WebSocket server port | | ALLOW_UNAUTH | false | Skip authentication (dev only!) | | BRUCE_PERMISSIONS_PATH | ./permissions.json | Global permissions config | | BRUCE_ENABLE_DEV_UNLOCK | 0 | Enable local-only terminal dev unlock via short-lived grant | | OPENROUTER_API_KEY | (unset) | API key for planner/chat models | | OPENROUTER_PLANNER_MODEL | OPENROUTER_MODEL fallback | Planner model for plan JSON generation | | OPENROUTER_CHAT_MODEL | OPENROUTER_MODEL fallback | Chat model for conversational responses | | BRUCE_DEBUG_PLAN | 0 | Enable verbose planner/routing debug logs | | BRUCE_FS_SCOPE | (from config) | Override file-search scope: downloads, standard, or full (see below) |

Finding and sending any file on your PC

By default, search and send are limited to Downloads only. To allow the app to find and send any file on your PC:

Option A – Environment variable (easiest)

BRUCE_FS_SCOPE=full npm run dev
# or
BRUCE_FS_SCOPE=full npm start

Option B – Config file (persists across restarts)

Create (or edit) the agent config file and set scope to "full":

• macOS: ~/Library/Application Support/Bruce/agent.config.json
• Windows: %APPDATA%\Bruce\agent.config.json
• Linux: ~/.config/bruce/agent.config.json

{
  "scope": "full"
}

Restart the agent. The policy watcher will pick up changes to this file without restart if you edit it later.

Scopes

| Scope | What’s searchable / sendable | |-------|-----------------------------| | downloads | Only ~/Downloads (default) | | standard | ~/Downloads, ~/Desktop, ~/Documents | | full | Windows: all drives (C:, D:, …). macOS/Linux: entire filesystem (e.g. / or drive roots) |

After switching to full, reconnect from the mobile app (or re-pair once). The agent applies this policy when sending permissions to the device, so the app will then be able to search and send within the new roots. Sends are still limited by maxSendMb (e.g. 50 MB) and blocked file types (e.g. .exe, .bat) for safety.

permissions.json

Default permissions template for new devices:

{
  "fs": {
    "roots": ["~/Downloads"],
    "maxSendMb": 50
  },
  "clipboard": {
    "enabled": true
  },
  "app": { "enabled": true },
  "window": { "enabled": true },
  "terminal": { "enabled": false, "allowlist": [] },
  "terminalInteractive": { "enabled": false },
  "system": { "enabled": false },
  "screen": { "enabled": false },
  "input": { "enabled": false }
}

Data Storage

Device data is stored in data/devices.json:

{
  "devices": {
    "dev_abc123": {
      "deviceId": "dev_abc123",
      "name": "My iPhone",
      "platform": "ios",
      "appVersion": "0.1.0",
      "publicKey": "base64...",
      "pairedAt": 1706000000000,
      "lastSeenAt": 1706000000000,
      "permissions": {
        "clipboard": { "enabled": true },
        "fs": { "enabled": true, "roots": ["~/Downloads"], "maxSendMb": 50 },
        "app": { "enabled": true },
        "window": { "enabled": true },
        "terminal": { "enabled": false, "allowlist": [] },
        "terminalInteractive": { "enabled": false },
        "system": { "enabled": false },
        "screen": { "enabled": false },
        "input": { "enabled": false }
      }
    }
  }
}

Security Model

Pairing

• 2-minute pairing session with 32-byte secret
• HMAC proof to verify mobile scanned the correct QR
• Local approval required (console prompt)
• 6-digit verification code displayed

Signed Requests

• Ed25519 signatures on all post-pairing messages
• Timestamp validation (±60 seconds)
• Nonce replay protection (last 1000 per device)
• Canonical JSON for deterministic signing

Permissions

• Per-device permission storage
• Enforced at tool level
• File paths restricted to allowed roots
• Terminal disabled by default
• Terminal allowlist enforcement by default (terminal.run)
• Optional dev unlock for terminal.run requires all of:
  • BRUCE_ENABLE_DEV_UNLOCK=1
  • active grant scope { "mode": "dev-unrestricted" }
  • non-relay/local connection only

Conversation Context

• Context is scoped by deviceId + sessionId (chat thread scoped).
• sessionId is optional on chat.generate, plan.generate, and context.reset.
• Missing sessionId falls back to "default".

fs.search Fail-safe

• If planner emits mode: "content" or "both" without contentQuery, agent downgrades to mode: "name" instead of failing execution.

CLI Commands (Future)

# Revoke a device
bruce revoke dev_abc123

# List devices
bruce devices

# Create new pairing session
bruce pair

Troubleshooting

"Unknown device" error

• Device was revoked or never paired
• Re-pair by scanning a new QR code

"Timestamp out of range" error

• Phone and PC clocks are too far apart
• Sync device time and try again

"Invalid signature" error

• Keypair mismatch (device was re-paired elsewhere)
• Clear mobile app data and re-pair

Pairing QR expired

• QR codes expire after 2 minutes
• Restart agent to generate new QR