Build Remote Agent

Support

Linespotting AB · [email protected] · +46 480 888 87
Product site: https://grokbuildremote.com/

Logs — how diagnostics work

When something fails (empty sessions, pair OK but no Grok Build, inject silent), send us two logs: one from the PC agent, one from the phone app.

1 · PC agent → Downloads folder

Requires free agent 0.6.0+ (install below).

gbr-agent version          # must show 0.6.0+
gbr-agent support-log      # writes ~/Downloads/gbr-agent-support-….txt
gbr-agent support-log -open  # same + open Downloads
gbr-agent service install  # optional: auto-start at login

The file lists: device/mailbox, relay health, every window the agent can see (Grok Build vs PowerShell), session store, and recent agent events. Also: gbr-agent logs -export copies the raw JSONL trace into Downloads.

Paths: %USERPROFILE%\Downloads\gbr-agent-support-*.txt (Windows) · ~/Downloads/gbr-agent-support-*.txt (Mac/Linux) · plus gbr-agent-support-latest.txt

2 · Phone app → Copy support log

1. Open Build Remote Agent on iOS or Android.
2. Settings (gear).
3. Tap Copy support log (and share sheet on Android if offered).
4. Paste into email or a notes app.

The report includes pair state, mailbox, session list, agent status, netcheck (firewall/VPN), and the in-app log ring.

3 · Send to us

Field	Value
Email	[email protected]
Subject	GBR support
Attach	PC file from Downloads + paste of phone support log

Paired but no Grok Build session?

1. Open Grok Build on the PC (window visible).
2. Agent 0.6.0+: gbr-agent support-log then gbr-agent sessions (look for grok-build-…).
3. gbr-agent run leave running.
4. Phone: Settings → Copy support log · email both logs.

Agent 0.5.1+ (and 0.4.4+) fixes a Windows bug where many open terminals collapsed into one session and hid Grok Build (thanks Shawn). 0.5.1 also publishes a live roster so names stay correct past six windows.

Install free agent

Full OS downloads: Download agent · current train v0.6.2 · /downloads/latest/ · GitHub Release v0.6.2 · apps: App Store (id6791293726) · Google Play (com.grokbuildremote.app)

AI / install / debug on GitHub: AGENTS.md · TROUBLESHOOTING.md · SESSION-NAMES.md

# pinned: see https://grokbuildremote.com/PINNED-INSTALL.md
gbr-agent version   # must print v0.6.2
gbr-agent pair
gbr-agent run
gbr-agent support-log

# pinned: see https://grokbuildremote.com/PINNED-INSTALL.md
gbr-agent version   # must print v0.6.2
gbr-agent pair      # browser QR — phone camera scans
gbr-agent run
gbr-agent service install   # optional background auto-start
gbr-agent support-log

Command cheat sheet

Command	Purpose
gbr-agent pair	PC opens QR — phone camera scans
gbr-agent run	Keep agent online (registers sessions)
gbr-agent sessions	List terminals (live roster — same titles the phone should show)
gbr-agent rename -session ID -name NAME	Pin a session title; phone updates on the next roster push
gbr-agent support-log	Support file → Downloads
gbr-agent logs	Recent hop events
gbr-agent logs -export	Copy JSONL log → Downloads
gbr-agent netcheck	Firewall / VPN / outbound HTTPS test
gbr-agent doctor	Platform + network checks
gbr-agent status	Device / mailbox health
gbr-agent version	Version string
gbr-agent service install	Auto-start at login (background)

FAQ

Same answers for humans and AIs. Machine docs: AGENTS.md · TROUBLESHOOTING.md · SESSION-NAMES.md · SESSION-ISOLATION.md · llms.txt · FAQ.md

How do I install the desktop agent?

Current train is v0.6.2 (device classes · companion watchdog · Grok Bot). Mobile apps: App Store (id6791293726) · Google Play (com.grokbuildremote.app).

# pinned: see https://grokbuildremote.com/PINNED-INSTALL.md
gbr-agent version    # must print v0.6.2

Windows PowerShell:

# pinned: see https://grokbuildremote.com/PINNED-INSTALL.md
gbr-agent version

Binaries: /downloads/latest/ · historical /downloads/v0.6.0/ · GitHub Release v0.6.2.

I am an AI — where do I start?

Read AGENTS.md first, then TROUBLESHOOTING.md. Do not invent a second code root. Official agent source is LinespottingOrg/GrokBuildRemote-Agents. Mobile apps are a separate paid product (not in that MIT repo).

How do I check agent and relay versions?

gbr-agent version
curl -sS https://gbr-relay.ekobrott.workers.dev/health
# expect agent v0.6.2 and health "version":"0.6.0" "bot":true "fleet":true "classes"

Current agent train is v0.6.2 — GitHub Release v0.6.2 · historical /downloads/v0.6.0/. Phone roster + Unpair + Bot API need mobile app 1.4.4+. From 1.4.5, a code stays disconnected until the desktop agent answers (Not connected). from the App Store (id6791293726) or Google Play (com.grokbuildremote.app).

Do I need a login?

No Linespotting account. Pair with the free desktop agent (QR or short code).

Why does the phone stay “Not connected”?

From mobile 1.4.5, a relay reply is not a pair. The phone stays disconnected until the desktop agent answers with a register, a heartbeat, or output. A wrong, expired, or offline code stays on “Not connected. No desktop agent answered.” Type the code shown on the computer, or scan its QR, while gbr-agent run is running. On iPhone, paste uses the system paste control. Desktop agent pin stays v0.6.2. Versions · 1.4.5.

Who shows the QR — phone or computer?

The computer. Run gbr-agent pair — browser QR. Phone: Scan QR from computer. Never reverse that.

How do support logs work?

The agent writes a text file under Downloads listing windows it can see and recent events. The app copies a report to the clipboard (Settings → Copy support log). Together they show whether pair, relay, and Grok Build discovery are healthy.

What if I inject while offline?

Commands stay in an offline queue with a stable command_id. When you are paired again and the session is online, the app flushes (or Settings → Flush queue).

Poll / heartbeat returns 401 unauthorized missing

Old agent without mailbox key. Upgrade to v0.6.2, wipe ~/.gbr, re-pair. Thanks Josh for the original report.

Which ports / firewalls / VPN?

No inbound ports. Only outbound HTTPS (TCP 443) to the relay. Details: Network · firewalls · ports · PC: gbr-agent netcheck · phone: Settings → Test relay.

How much do the mobile apps cost?

The App Store and Google Play show the price. It is a one-time purchase. The desktop agent is free (MIT).

Session names stuck after six windows?

Older agent 0.5.0 only advertised the first six sessions, so extra windows stole those slots and titles stayed stale after a rename. Upgrade to 0.6.0+, leave gbr-agent run running, and reopen the app. The list is scrollable (in theory 255). Titles update after /rename in the CLI, gbr-agent rename -session ID -name …, or when windows open and close. Details: Versions · session names · issue #3.

Phone stuck on “Waiting for sessions”?

1. On the PC, gbr-agent run must stay running, and the CLI window should stay open.
2. gbr-agent sessions — empty means the agent sees no terminals.
3. In the app: Settings → Unpair / Forget this PC, then gbr-agent pair and scan again.
4. Force-close is not enough.

How do I rename a session?

/rename must be its own submitted TUI line. Do not bury it inside a pasted prompt. Alias /title. Natural language alone does not pin summary.json.

In the Grok Build TUI (slash command, not an agent flag) — submit this line alone: /rename Phone Grok.

On the PC:

gbr-agent sessions
gbr-agent rename -session grok-build-40a22 -name "Phone Grok"

Inbox watcher uses two submits: (1) /rename TITLE (2) the job body with no slash.

Does inbox watch replace pasting boss-steer comments?

Yes. With gbr-agent run and gh on PATH, the agent polls GitHub LinespottingOrg/grok-build-inbox label boss-steer. A matching Grok Build window title gets the newest comment injected and submitted. No window → two submits: /rename TITLE, then the issue body. Spawned grok cwd is the machine clone root (GBR_OPEN_CWD): Mac Mini ~/Developer (logs ~/Developer/gbr-agent-out), PC C:\pc-build. Never Dropbox. Never ~/pc-build on the Mac. After the watcher is running, do not paste inbox comments. Disable: GBR_INBOX_WATCH=0.

Where do Mac Mini builds and inbox-spawned Grok sessions live?

Mac Mini: /Users/user/Developer/<slug> only — not Dropbox, not ~/pc-build (PlanCalc leftover). Inbox spawn and gbr_open default cwd is ~/Developer. Logs: ~/Developer/gbr-agent-out. PC1: C:\pc-build\<slug>.

Is NemoClaw a fourth pair protocol?

No. Pair is still QR or printed 8-char, then gbr-agent run. NemoClaw is a sandbox, not a GBR pair. GBR stays the host tool on the Mac/PC. Point NemoClaw at loopback :8788 or gbr-mcp on the host. Do not copy gbr-agent into the sandbox. OpenClaw mobile nodes are not a GBR pair.

Can Claude Cowork and Grok Bot both control Grok Build?

Yes (agent/relay 0.6.0+). Same JSON for both. Grok bot talks HTTP (127.0.0.1:8788 or the hub Bot URL). Claude Cowork talks gbr-mcp from the agent repo clone. Loop: open → lock → inject → GET /result?wait_ms=. A lease returns 409 if the other client already holds that window. The phone is spectator (status lines), not orchestrator. See home · Versions.

Can one Grok bot drive several PCs?

Yes (agent/relay 0.5.3+). Pair the hub PC (the phone stays here). Pair each extra Mac/Linux PC, then on the hub: gbr-agent fleet add -name studio-linux -mailbox gbr-XXXX -key KEY. The bot calls http://127.0.0.1:8788 or the hub Bot URL and sets "device":"local" or "device":"studio-linux". The phone shows short lines like bot · studio-linux · inject queued.

How does a Grok bot talk to the agent?

Agent + relay 0.5.2+. Two HTTP APIs, same JSON.

Where	URL	Auth
Same PC	http://127.0.0.1:8788 while gbr-agent run	Loopback only (not reachable from the phone)
Remote	https://gbr-relay.ekobrott.workers.dev/v1/mb/{mailbox_id}/bot	X-GBR-Key from phone Settings → Bot API

gbr-agent bot
curl -sS http://127.0.0.1:8788/v1/sessions
curl -sS -X POST http://127.0.0.1:8788/v1/inject \
  -H 'Content-Type: application/json' \
  -d '{"session_id":"SESSION","text":"hello","submit":true}'

Relay: copy Bot URL + mailbox key in the app, then GET …/sessions, POST …/inject, GET …/output. Treat the key like a password. Spec: docs/BOT-API.md.

Is there an MCP server?

Yes — gbr-mcp wraps the Bot API so Claude Cowork / Claude Code, Grok CLI, Cursor, Hermes, OpenClaw (ClawHub skill, not a core PR) and any other MCP client can open, lock, inject and harvest results. Thirteen tools including gbr_open, gbr_lock, gbr_result, gbr_tasks. claude mcp add gbr -- node ABS · grok mcp add gbr -- node ABS · Cursor ~/.cursor/mcp.json · hermes mcp add gbr -- stdio -- node ABS. Pair stays QR or 8-char. NemoClaw is not a fourth pair.

git clone https://github.com/LinespottingOrg/GrokBuildRemote-Agents.git
cd GrokBuildRemote-Agents/mcp/gbr-mcp && npm install && node bin/gbr-mcp.js --diagnose

Requires Node 20+ and a running agent 0.6.0+. No npm package — run from the clone. Source: mcp/gbr-mcp.

One MCP config for both Claude and Grok?

Yes. Grok CLI reads ~/.claude.json in addition to ~/.grok/config.toml, so one entry serves both. Caveat: grok mcp doctor dedupes — a server declared in both files is reported as “0 servers” from ~/.claude.json. That is deduplication, not a parse failure. What matters is that the server shows ✓ handshake OK.

Inject returned HTTP 200 but nothing happened

The Bot API returns HTTP 200 on logical errors. An empty session_id responds 200 with {"ok":false,"error":"inject: empty session_id refused"}. Clients must check the ok field in the body, not the HTTP status. gbr-mcp converts these into a GBR_AGENT_REFUSED error with a hint.

I targeted a remote machine but it ran locally

On agent 0.5.x, unknown names silently fell back to local. Agent 0.6.0+ returns HTTP 404 {"ok":false,"error":"unknown_device"} instead. Register remotes with gbr-agent fleet add -name studio-linux -class linux (or -class mac_mini / laptop / pc). Grok Bot may also send {"device":"mac-mini"} when that class is unique. Two laptops → 409 ambiguous_device — use the id. The phone class is the app (spectator); injects return 400 cannot_inject_phone.

How does this app work with Amnibro, Farina, and ChrisP remotes?

Build Remote Agent is the unified control layer: store apps, QR pair, GitHub HTTPS relay, Grok Bot fleet, device classes. It is designed to coexist with the three community remotes, not replace them.

Remote	Strength	Port	With this app
Amnibro/grok-remote	Grok Build plugin /remote, LAN live UI, history, Skills	:2421 (agent serve :2419)	GET /health lists impl=amnibro when the plugin hub is up
daniel-farina/grok-remote	TypeScript PWA, Tailscale, PM2, SSE, MCP registry, UI cleanup	:7910 (/api/health)	Keep Tailscale for the dashboard; use this app through firewalls
ChrisP-Builds/grok-remote-hub	Python always-on hub, session lifecycle, ACP watchdog, multi-browser stream	:8787 (/health)	Same ok/stale/zombie words. GBR Bot API stays on :8788

The GitHub relay remains the feedback loop and documentation layer (GrokBuildRemote-Agents · llms.txt · this FAQ). We do not switch the product to Tailscale. Home: #ecosystem.

“command not found: gbr-agent” right after a successful install

The installer writes to ~/.local/bin and appends that directory to ~/.zshrc — but it cannot reload the shell you are already sitting in. Open a new terminal, or:

export PATH="$HOME/.local/bin:$PATH"
gbr-agent version

This is the single most common install report. Nothing is broken.

How do I point Claude / Grok at gbr-mcp?

Clone the agent repo, run npm install once in mcp/gbr-mcp, then point your client at the absolute path of bin/gbr-mcp.js:

[mcp_servers.gbr]
command = "node"
args = ["/absolute/path/to/GrokBuildRemote-Agents/mcp/gbr-mcp/bin/gbr-mcp.js"]

Or from a clone of the agent repo: …/GrokBuildRemote-Agents/mcp/gbr-mcp/bin/gbr-mcp.js.

“Refusing to load formula from untrusted tap”

Homebrew 6 added tap trust. Third-party taps must be trusted before their formulae will load — no install guide written before Homebrew 6 mentions this.

brew trust getsentry/xcodebuildmcp
brew trust facebook/fb
brew trust grafana/grafana

Are secrets ever written to the MCP logs?

No. Mailbox keys, bearer tokens and any bare 48+ character hex string are redacted before reaching stderr or the JSONL file, at every level including trace. Three layered defences run in order: exact-value scrubbing, key-name matching (including camelCase such as authToken), and a hex fallback. Truncation chops on a token boundary so a split secret cannot slip under the length floor. Tests assert all of it.

Inject does nothing?

Confirm gbr-agent sessions lists the target window. Run gbr-agent netcheck. Only one agent per mailbox. On Windows, focus the target terminal.

If pairing is fine and sessions still do not appear, it is not a pairing problem. Check whether the agent is enumerating windows but classifying none of them:

grep '"hop":"agent.discover"' ~/.gbr/logs/agent-$(date +%F).jsonl | tail -3

A line reading windows=12 grok_build=0 means discovery is working but the classifier is not matching your Grok Build windows — re-pairing cannot fix that. A line reading windows=0 grok_build=0 on Windows while Grok is open is usually session isolation (agent in session 0). Note also that a session literally named session is the agent’s own pseudo-session, and injecting into it will hang until timeout.

Why does discover show grok_build=0 / windows=0 on Windows even though Grok Build is open?

The desktop agent was running in Windows session 0 (background scheduled task / S4U) while Grok Build CLI windows live on the interactive desktop (session 1). Session 0 cannot see those windows, so discovery stays at zero.

Fix: run gbr-agent in the interactive user session (same SessionId as grok.exe). Keep session-0 tasks like \GrokBuildRemoteAgentService Disabled. Auto-start at logon with a Startup shortcut or schtasks /IT (“Run only when user is logged on”).

Get-Process gbr-agent,grok | Format-Table Id,ProcessName,SessionId
# grep today's agent jsonl:
# session_ok / session_mismatch / SESSION-ISOLATION / agent.session_watch / grok_build=0

Log keys: session_mismatch · session_ok · agent.session_watch · grok_build=0 · SESSION-ISOLATION. Helpers in the agent repo: scripts/windows/session-watch.ps1 and scripts/windows/apply-session-isolation-pc1.ps1. Full guide: docs/SESSION-ISOLATION.md · TROUBLESHOOTING section Windows: discover grok_build=0.

Unpair vs Disconnect vs Clear data

Control	What it does
Disconnect	Pause live updates only. The PC stays paired. Mailbox and session names stay.
Settings → Unpair / Forget this PC	Drop mailbox id, mailbox key, and cached sessions. Keeps the Relay URL. Returns to Scan QR. Use this after an agent upgrade, mailbox change, or to pair a different PC.
Android / iOS system Clear data	Nuclear — also wipes Relay URL and all local prefs. Not required when Unpair is in the app.

Force-closing the app is not enough to leave a PC. Tracked as issue #2.

How do I wipe local data?

• In-app: Settings → Unpair / Forget this PC (preferred)
• Uninstall the app / clear app storage (also wipes Relay URL)
• Delete ~/.gbr or %USERPROFILE%\.gbr on the PC
• Email us — Privacy → deletion

Contact

Channel	Detail
Email	[email protected]
Phone	+46 480 888 87
Data deletion	Email subject GBR data deletion
Privacy	Privacy Policy
Terms	Terms of Service
Network	Firewalls & ports
Versions	Versions & security

Direct binaries (latest)

• Windows x64
• macOS Apple Silicon
• macOS Intel
• Linux amd64
• Linux arm64
• Current: GitHub Release v0.6.2 · latest · historical v0.6.0
• Older: v0.5.4 · v0.5.3 · v0.5.1 · v0.5.0
• GitHub: Release v0.6.2 · FAQ.md · SESSION-ISOLATION.md