Docs

Everything you need to connect your Mac to ChatGPT or Claude.

On this page

Getting started

Quick start

Five steps to run your first plan from ChatGPT or Claude.

  1. 1

    Download Bruce Desktop

    Download and install Bruce Desktop on your Mac. Download here →

  2. 2

    Pair your Mac

    In your dashboard, go to Devices → Add device. You'll get a pairing code. Click Open in Bruce Desktop — it fills in automatically and connects.

  3. 3

    Set a policy

    Go to Policies and add at least one allowed path (e.g. ~/Downloads) and any terminal commands you want to allow (e.g. mv, ls).

  4. 4

    Add Bruce to your AI app

    Copy the MCP URL and Bearer token from the device card in your dashboard. Add them to ChatGPT (Settings → Connectors) or Claude (Settings → Integrations).

  5. 5

    Run a plan

    Ask ChatGPT or Claude to do something on your Mac — e.g. "move all PDFs from my Downloads to Documents". It will call Bruce, you approve in the dashboard, and it runs.

AI Integration

Add Bruce to ChatGPT

  1. In ChatGPT, go to Settings → Connectors → + Add.
  2. Choose MCP Server.
  3. Set the URL to your MCP Server URL (shown on the device card in the dashboard, e.g. https://bruce-gateway.fly.dev/mcp).
  4. Set Authentication to Bearer token and paste your device's MCP token.
  5. Save. ChatGPT will now show Bruce tools (bruce_submit_plan, etc.) when you chat.

Each device has its own token — add multiple devices as separate connectors. The MCP URL is the same for all devices; the token identifies which device to use.

AI Integration

Add Bruce to Claude

  1. In Claude, go to Settings → Integrations → Add integration.
  2. Paste your MCP Server URL (e.g. https://bruce-gateway.fly.dev/mcp) from the device card.
  3. When prompted for auth, enter your Bearer token.
  4. Save. Bruce tools appear in the tool list for new conversations.

For Claude Code (CLI): add the server to ~/.claude/settings.json under mcpServers with the URL and auth header.

Setup

Bruce Desktop app

The recommended way to keep your Mac connected. Bruce Desktop runs in the menu bar, manages the agent process, and reconnects automatically after sleep or network drops.

Download Bruce Desktop (macOS)

Installation

  1. Open the .dmg and drag Bruce to Applications.
  2. Launch Bruce. On first run, macOS may show a security prompt — go to System Settings → Privacy & Security and click Open Anyway.
  3. A pairing screen appears. Enter the code from your dashboard (or use the deep link from the pairing flow).
  4. Bruce appears in your menu bar. Done.

Menu bar

  • Status / Settings — view connection status, copy MCP token.
  • Re-pair — connect to a different account or gateway.
  • Quit — stops the agent and exits.

Auto-start

Bruce sets itself to open at login after pairing. The agent reconnects automatically after Mac sleep/wake or network changes.

CLI

Terminal pairing

Pair without the desktop app using npx.

Step 1 — Get a pairing code

In the dashboard: Devices → Add device → copy the code.

Step 2 — Run the pair command

CODE=your-code GATEWAY_URL=https://bruce-gateway.fly.dev npx @bruceengine/agent pair

Prints DEVICE_ID and DEVICE_SECRET — save these.

Step 3 — Start the agent

RELAY_URL=https://bruce-gateway.fly.dev DEVICE_ID=dev_xxx DEVICE_SECRET=your_secret npx @bruceengine/agent
macOS

Always-on with launchd

Keep the agent running in the background, starting at login and restarting if it exits.

1 — Create env file

Save your credentials to ~/.bruce-agent.env:

RELAY_URL=https://bruce-gateway.fly.dev DEVICE_ID=dev_xxx DEVICE_SECRET=your_secret

2 — Install LaunchAgent

npx @bruceengine/agent setup-launchd

3 — Load it

launchctl load ~/Library/LaunchAgents/com.bruce.agent.plist

Logs: /tmp/bruce-agent.log and /tmp/bruce-agent.err. Stop: launchctl unload ~/Library/LaunchAgents/com.bruce.agent.plist.

Security

Policies & permissions

Policies define what AI can access on your device. Set them in Policies.

Allowed paths

Directories Bruce can read, write, and move files within. Use ~/Downloads, ~/Documents, ~/Desktop, ~/.Trash etc. Plans that touch files outside these paths are blocked.

Terminal allowlist

Commands terminal.run is allowed to execute. Add only what you need — common ones: mv, cp, ls, mkdir, rm. If the list is empty, terminal.run is disabled entirely.

Risk thresholds

Plans are rated low, medium, or high. You can require manual dashboard approval for plans above a threshold. Default: all plans auto-approve after ChatGPT/Claude calls bruce_approve_plan.

Reference

Using terminal.run

terminal.run runs a single command with shell: false — no shell is involved. This means:

✓ Correct — literal absolute paths

mv /Users/mac/Downloads/file.pdf /Users/mac/Documents/

✗ Wrong — shell features are blocked

mv "$HOME/Downloads/file.pdf" ~/Documents/ ← $ and ~ are blocked
ls Downloads | grep pdf ← pipes are blocked
mkdir -p dir1 && cd dir1 ← && is blocked

Tip: Use fs.move, fs.copy, and fs.search for file operations when possible — they work without terminal policy and handle paths safely.

Help

Troubleshooting

Device shows Offline

Open Bruce Desktop — it reconnects automatically. Or check that the agent is running: look in the menu bar. If it crashed, re-open the app.

"Terminal access is disabled for this device"

Your terminal allowlist is empty. Go to Policies, add the commands you need (e.g. mv, ls), and save.

step_results is empty and status is failed

The plan failed before reaching your Mac — usually a policy violation (path outside allowed roots) or the device was offline at the time of approval. Check the run's error message and verify your allowed paths cover the files in the plan.

"Path is outside allowed roots"

The file path in the plan isn't covered by your policy. Go to Policies and add the parent directory.

macOS shows "Bruce is damaged" or blocks launch

macOS Gatekeeper blocked the unsigned app. Go to System Settings → Privacy & Security and click Open Anyway. You only need to do this once.

ChatGPT lost the MCP session

Sessions last 8 hours of idle time. If ChatGPT shows a session error, reinitialize the connector (remove and re-add, or refresh the page) — your device stays paired.

Re-pairing a device

Open Bruce Desktop → menu bar → Re-pair. Get a new pairing code from the dashboard and enter it. Your old device record is replaced.

Agent logs: /tmp/bruce-agent.log and /tmp/bruce-agent.err.