Linespotting AB · [email protected] · +46 480 888 87
Product site: https://grokbuildremote.com/
Build phone · linux · pc · laptop · mac_mini)
so Grok Bot (public beta ) can route without guessing.
Unknown device names return 404. GET /health reports companion remotes:
Amnibro/grok-remote,
daniel-farina/grok-remote,
ChrisP-Builds/grok-remote-hub.
GitHub HTTPS relay stays the core loop.
FAQ · Home · Versions.
open → lock → inject → GET /result?wait_ms= —
plus PTY-first inject. Claude Cowork and a Grok bot can drive the same PC, with a lease
so they do not collide (how).
gbr-agent service install · session health checks.
Feature request source · Grok (xAI) suggested this slice;
Linespotting shipped it independently — Press ·
Versions.
0.3.x paired without saving mailbox_key (401 on poll).
Fixed in v0.4.1. Details: Versions → Josh.
help, status, or git status.
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.
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
The report includes pair state, mailbox, session list, agent status, netcheck (firewall/VPN), and the in-app log ring.
| Field | Value |
|---|---|
| [email protected] | |
| Subject | GBR support |
| Attach | PC file from Downloads + paste of phone support log |
gbr-agent support-log then gbr-agent sessions (look for grok-build-…).gbr-agent run leave running.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.
Full OS downloads: Download agent · current train v0.6.0
· /downloads/v0.6.0/
· GitHub Release v0.6.0
· 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.0+ 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.0+ gbr-agent pair # browser QR — phone camera scans gbr-agent run gbr-agent service install # optional background auto-start gbr-agent support-log
| 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) |
Same answers for humans and AIs. Machine docs: AGENTS.md · TROUBLESHOOTING.md · SESSION-NAMES.md · llms.txt · FAQ.md
Current train is v0.6.0 (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.0+
Windows PowerShell:
# pinned: see https://grokbuildremote.com/PINNED-INSTALL.md gbr-agent version
Binaries: /downloads/latest/ · /downloads/v0.6.0/ · GitHub Release v0.6.0.
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).
gbr-agent version curl -sS https://gbr-relay.ekobrott.workers.dev/health # expect agent v0.6.0+ and health "version":"0.6.0" "bot":true "fleet":true "classes"
Current agent train is v0.6.0 —
/downloads/v0.6.0/ ·
GitHub Release v0.6.0.
Phone roster + Unpair + Bot API need mobile app 1.3.1+
from the App Store (id6791293726) or
Google Play (com.grokbuildremote.app).
No Linespotting account. Pair with the free desktop agent (QR or short code).
The computer. Run gbr-agent pair — browser QR.
Phone: Scan QR from computer. Never reverse that.
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.
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).
Old agent without mailbox key. Upgrade to v0.6.0+, wipe ~/.gbr, re-pair.
Thanks Josh for the original report.
No inbound ports. Only outbound HTTPS (TCP 443) to the relay.
Details: Network · firewalls · ports · PC: gbr-agent netcheck · phone: Settings → Test relay.
$13.00 USD one-time. No subscription. Desktop agent is free (MIT).
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.
gbr-agent run must stay running, and the CLI window should stay open.gbr-agent sessions — empty means the agent sees no terminals.gbr-agent pair and scan again./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.
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.
After the watcher is running, do not paste inbox comments.
Disable: GBR_INBOX_WATCH=0.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
Note also that a session literally named session is the agent’s own
pseudo-session, and injecting into it will hang until timeout.
| 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.
~/.gbr or %USERPROFILE%\.gbr on the PC| Channel | Detail |
|---|---|
| [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 |