{"slug": "show-hn-safely-connect-grokbot-to-your-pc-vm-chosen-folders-and-claude-codex", "title": "Show HN: Safely connect GrokBot to your PC/VM: chosen folders and Claude/Codex", "summary": "A developer released safe-grokbot-bridge, an open-source daemon that gives a remote AI agent such as xAI's Grok Bot an authenticated HTTP API to a user's machine, limited to chosen folders and to driving Claude Code, Codex CLI and Hermes Agent sessions. The bridge listens only on 127.0.0.1:4765 and reaches the cloud through an outbound cloudflared tunnel, using 256-bit bearer tokens with only hashes stored, per-IP lockout after failed attempts and per-token rate limits. Its author warns the bridge is remote access to a machine and recommends running it and the agents it drives in an isolated environment such as a virtual machine or dedicated WSL 2 distribution rather than a primary workstation.", "body_md": "**Let a remote AI agent work on your machines, safely.** `safe-grokbot-bridge` is a small daemon\nthat gives an agent such as a [Grok Bot](https://x.ai) a narrow, authenticated HTTP API to your\ncomputers. Through it the agent can read your project folders and git history, see the Claude\nCode, Codex and Hermes sessions running there, talk to them, and start new ones.\n\nYou keep using your agents as before. The remote agent becomes a coordinator that can hand work to them and follow up while you are away from the keyboard, for example from your phone.\n\nWarning\n\n**This is remote access to your machine.** Depending on your configuration, the remote agent\ncan read files and git history in the folders you expose, and through the coding agents it\nstarts or messages it can make the machine run programs and commands and change files: with\nthe agents' permission prompts, or without them where you allow that. Use the bridge\ndeliberately, only where this is acceptable, and grant as little as the work needs. Run it,\ntogether with the agents it drives, in an isolated environment such as a virtual machine, a\ndedicated WSL 2 distribution or a separate computer, not on your primary workstation with your\npersonal data and credentials. See [Where to run it](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/deployment.md#where-to-run-it).\n\n```\nflowchart LR\n    subgraph cloud[\"Grok Bot's cloud computer\"]\n        bot[\"skill + curl<br/>secrets: URL, token\"]\n    end\n    subgraph cf[\"Cloudflare\"]\n        edge[\"HTTPS edge<br/>optional Access\"]\n    end\n    subgraph machine[\"Your machine\"]\n        cfd[\"cloudflared\"]\n        bridge[\"safe-grokbot-bridge<br/>127.0.0.1:4765<br/>token, lockout, rate limit<br/>workspace capabilities\"]\n        tmux[\"tmux: Claude Code, Codex,<br/>Hermes you can attach to\"]\n        headless[\"headless runs:<br/>claude -p, codex exec\"]\n        external[\"sessions outside tmux<br/>(experimental)\"]\n        files[(\"allowed folders:<br/>files and git, read-only\")]\n    end\n    bot -- \"HTTPS + bearer token\" --> edge\n    edge -- \"tunnel, opened from the machine\" --> cfd\n    cfd --> bridge\n    bridge --> tmux\n    bridge --> headless\n    bridge --> external\n    bridge --> files\n```\n\n1. The bridge listens on `127.0.0.1` only.`cloudflared` opens an outbound tunnel, so no port is\nopened on the machine. (A public address with TLS and key pinning works too.)\n2. The bot calls the API with `curl` and a bearer token kept in a Grok secret. Every request is\nauthenticated, rate limited and checked against the folders you allowed.\n3. The bridge lists, starts and drives agent sessions there, and serves files and git history read-only. The bot long-polls a session until the agent has answered.\n\n- **Agent sessions.** List, start, message and stop Claude Code, Codex CLI and Hermes Agent\nsessions, or any other terminal program in tmux.\n  - **tmux:** the agent runs in a live terminal you can attach to at any time\n(`tmux attach -t …` ).\n  - **Headless:** every message is one non-interactive run, continued by the agent's session id.\n  - **Start options:** model, reasoning effort, permission bypass (only where you allow it),\nresume of an earlier conversation, and`keep_alive: false` to close a session once it has\nanswered.\n  - **Reliable state:** state comes from Claude Code's own status, per-session turn-complete hooks\nand terminal activity, so the client knows when an agent is working, waiting for an answer or\ndone. It long-polls instead of guessing.\n- **Read-only project access.** Directory listings (respecting`.gitignore` ), text files by line\nrange,`git status` ,`log` ,`diff` and`show` . The file endpoints never serve secrets such as`.env` files and private keys. Git output is not filtered, so anything committed to a\nrepository you expose is visible.\n- **Security first.**  - 256-bit bearer tokens (only their hashes are stored), with per-IP lockout after failed attempts and per-token rate limits.\n  - Per-folder capabilities (`files` ,`git` ,`sessions` ,`input` ,`start` ).\n  - TLS required on any public address. A self-signed certificate with public-key pinning works out of the box, no CA needed.\n  - Every request is written to an audit log, and no generic shell endpoint exists.\n- **Made for LLM clients.** A complete[OpenAPI 3.1](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/openapi.json) description. Every\nresponse says when it is incomplete and what to do next, and a[ready-made skill](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/grok-bot.md) teaches Grok Bot to use it and to connect new machines.\n- **One binary** for Linux, macOS and Windows. Configuration is one TOML file.\n\n**Recommended: two skills do it.** Follow the [quick setup](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/setup.md#quick-setup-recommended):\n\n1. Install the [skills](#agent-skills) : one into Grok Bot, one into Claude Code, Codex or Hermes\non the machine.\n2. Tell Grok Bot *\"Use the safe-grokbot-bridge-client skill to connect a new machine named\npc1.\"* It creates the Cloudflare Tunnel and gives you a setup message. Paste that into your\ncoding agent on the machine: it asks which folders to expose and what the bot may do there,\nthen installs and configures everything. You only move two secrets by hand.\n\n**Step by step with prompts:** [Setup with Grok Bot and Cloudflare](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/setup.md#setup-step-by-step).\n\n**By hand:**\n\n```\n# 1. Install: download the archive for your platform from the releases page, or build it\ncargo install --locked --git https://github.com/janreges/safe-grokbot-bridge\n\n# 2. Create a config with a fresh token (printed once) and your projects folder as a workspace\nsafe-grokbot-bridge init --workspace ~/projects\n\n# 3. Allow driving agents there: add \"input\" and \"start\" to `allow` in the file `init` wrote\n#    (Linux: ~/.config/safe-grokbot-bridge/config.toml,\n#     macOS: ~/Library/Application Support/safe-grokbot-bridge/config.toml), then review everything\nsafe-grokbot-bridge check\n\n# 4. Run it, and publish it with a Cloudflare Tunnel (see docs/deployment.md)\nsafe-grokbot-bridge serve\n```\n\nThen [connect Grok Bot](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/grok-bot.md), or call the API from anything that speaks HTTP.\n\nTip: start your agents with `safe-grokbot-bridge launch claude` (or `codex`) instead of `claude`.\nThey then run in tmux with the bridge's turn hooks, so the remote agent can follow and continue\nyour sessions.\n\nThe repository holds two skills, and is a plugin marketplace for Claude Code and Codex.\n\n- [`safe-grokbot-bridge`](https://github.com/janreges/safe-grokbot-bridge/blob/main/skills/safe-grokbot-bridge/SKILL.md) , for the coding agent on the\nmachine: it installs the bridge, agrees with you on the folders it exposes and what the bot may\ndo there, writes and later changes the config, runs it as a service, connects the Cloudflare\nTunnel, upgrades and troubleshoots it. It shows you every plan before it applies it, asks\nbefore it widens access, and never handles your secrets.\n- [`safe-grokbot-bridge-client`](https://github.com/janreges/safe-grokbot-bridge/blob/main/skills/safe-grokbot-bridge-client/SKILL.md) , for Grok Bot or\nanother client: it uses the API, finds your machines by their secrets, and connects new\nmachines.[Connecting Grok Bot](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/grok-bot.md#the-skill) shows how to install it.\n\n| Agent on the machine | Install `safe-grokbot-bridge` | \n|---|---|\n| Claude Code | `claude plugin install safe-grokbot-bridge --marketplace janreges/safe-grokbot-bridge` (2.1.292 or newer; before that,`claude plugin marketplace add janreges/safe-grokbot-bridge` and`claude plugin install safe-grokbot-bridge@safe-grokbot-bridge` ) | \n| Codex | `codex plugin marketplace add janreges/safe-grokbot-bridge` , then`codex plugin add safe-grokbot-bridge@safe-grokbot-bridge` | \n| Hermes Agent | `hermes skills install janreges/safe-grokbot-bridge/skills/safe-grokbot-bridge --force` (Hermes blocks community skills that set up services; read it first with`hermes skills inspect` ) | \n| Cursor, Gemini CLI, GitHub Copilot, OpenCode and others | `npx skills add janreges/safe-grokbot-bridge --skill safe-grokbot-bridge -g` | \n| Any agent, by hand | Copy `skills/safe-grokbot-bridge/` into the agent's skills folder, such as`~/.claude/skills/` or`~/.agents/skills/` | \n\nThen start a new session and say, for example, *\"Set up safe-grokbot-bridge on this machine\"* or\n*\"Let the bot also start agents in ~/projects/app.\"*\n\nTo update the skill later: `claude plugin update safe-grokbot-bridge@safe-grokbot-bridge` in\nClaude Code; `codex plugin marketplace upgrade safe-grokbot-bridge`, then the `codex plugin add`\ncommand again in Codex; `hermes skills update` in Hermes; `npx skills update` elsewhere.\n\nEvery request except `GET /healthz` needs `Authorization: Bearer <token>`. All paths are absolute.\n\n```\nB=https://bridge.example.com; H=\"Authorization: Bearer $SGB_TOKEN\"\n\ncurl -sH \"$H\" $B/v1/info                                  # machine, agents, workspaces, limits\ncurl -sH \"$H\" \"$B/v1/sessions?path=/home/me/projects/app\"  # who is already working there?\n\n# Start Claude Code in tmux with a task, then wait (up to 90 s per call) for the answer\ncurl -sH \"$H\" -H 'content-type: application/json' $B/v1/sessions -d @- <<'EOF'\n{\"cwd\": \"/home/me/projects/app\", \"agent\": \"claude\", \"prompt\": \"Run the tests and fix failures.\"}\nEOF\ncurl -sH \"$H\" \"$B/v1/sessions/sgb-app-claude-3f9a1c?wait=60\"   # state, last_message, screen\n\n# Follow up, or answer a permission prompt with keys\ncurl -sH \"$H\" -H 'content-type: application/json' $B/v1/sessions/sgb-app-claude-3f9a1c/input \\\n     -d '{\"text\": \"Also update the changelog.\"}'\ncurl -sH \"$H\" -H 'content-type: application/json' $B/v1/sessions/sgb-app-claude-3f9a1c/input \\\n     -d '{\"keys\": [\"Enter\"]}'\n\n# Read-only access\ncurl -sH \"$H\" \"$B/v1/files?path=/home/me/projects/app&depth=2\"\ncurl -sH \"$H\" \"$B/v1/files/content?path=/home/me/projects/app/README.md\"\ncurl -sH \"$H\" \"$B/v1/git/log?dir=/home/me/projects/app&limit=10\"\n```\n\n| Endpoint | Purpose | \n|---|---|\n| `GET /v1/info` | Machine, version, agents, workspaces and their capabilities, limits | \n| `GET /v1/files` ,`GET /v1/files/content` | Directory listing, text file by line range | \n| `GET /v1/git/{status,log,diff,show}` | Read-only git | \n| `GET /v1/sessions` | Sessions in the workspaces you may see | \n| `POST /v1/sessions` | Start a session ( `cwd` ,`agent` ,`runner` ,`prompt` ,`model` ,`effort` ,`bypass_permissions` ,`keep_alive` ,`resume` ) | \n| `GET /v1/sessions/{id}?wait=&lines=` | State, last answer, terminal screen; long-poll while working | \n| `POST /v1/sessions/{id}/input` | `text` and/or`keys` | \n| `DELETE /v1/sessions/{id}` | Stop a session the bridge started | \n| `GET /openapi.json` | The OpenAPI document ( [also in the repo](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/openapi.json) ) | \n\n| Runner | When | How you get answers | \n|---|---|---|\n| `tmux` | Default when tmux is installed. A live terminal UI; a person can attach. | `last_message` from the turn hook (Claude Code, Codex), plus the terminal`screen` | \n| `headless` | Without tmux (e.g. native Windows), or on request. One non-interactive run per message. | `last_message` ; progress while the turn runs | \n| `external` | Sessions started outside tmux, e.g. in a terminal tab. | Claude Code: state always; with `[experimental] external_sessions` also messaging and answers. Codex: experimental. | \n\nSession states: `working`, `waiting` (a permission prompt or question; read `screen` and answer\nwith `keys`), `idle`, `finished` (closed after its answer with `keep_alive: false`), `exited`,\n`failed`, `unknown`.\n\nThe bridge types only into panes where nothing but the agent can receive the text: sessions it\nstarted, and panes whose program is the agent (or a wrapper that ends with it). An agent you\nstarted from a shell inside tmux is listed but not typed into, because text sent after the agent\nexits would reach the shell; with `[experimental] external_sessions`, Claude Code and Codex there\ntake messages through their own inbox or queue instead. `resume` continues a conversation only in\nthe folder where it was held.\n\nA token lets its holder make coding agents work on your machine, possibly without permission prompts if you allow that. Treat it like an SSH key. In short:\n\n- **Isolation:** the agents the bridge drives run with your user's rights. Give them a virtual\nmachine, a dedicated WSL 2 distribution or a separate computer that holds only the projects and\ncredentials the work needs; see[Where to run it](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/deployment.md#where-to-run-it) .\n- **Tokens:** 256-bit, stored as SHA-256 hashes, compared in constant time. A client IP is\nblocked after repeated failures, and each token has a request rate limit.\n- **Network:** plain HTTP only on loopback. Publish it through a Cloudflare Tunnel, optionally\nwith an Access service token as a second factor, or enable TLS with key pinning.\n- **Folders:** capabilities per folder; access is read-only by default. Paths are canonicalized,\nso`..` and symlinks cannot escape.\n- **No shell endpoint:** the bridge itself never runs arbitrary commands, and git runs with\noptions that keep a repository's own config from executing programs. The coding agents it\nstarts do run commands, under their own permission systems.\n\nRead the [threat model](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/design.md#6-security-model) and [SECURITY.md](https://github.com/janreges/safe-grokbot-bridge/blob/main/SECURITY.md).\n\n|  | Linux / WSL 2 | macOS | Windows | \n|---|---|---|---|\n| API, TLS, files, git, headless sessions | ✓ | ✓ | ✓ | \n| tmux sessions | ✓ | ✓ | best effort with [psmux](https://github.com/psmux/psmux) (sessions the bridge started, one pane each) | \n| External Claude Code sessions | ✓ | ✓ | ✓ | \n\n- [Setup with Grok Bot and Cloudflare](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/setup.md) : the guided setup, with prompts to paste\n- [Configuration reference](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/configuration.md)\n- [Deployment: Cloudflare Tunnel, VPS, running as a service](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/deployment.md)\n- [Connecting Grok Bot, with a ready-made skill](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/grok-bot.md)\n- [Agent skill for Claude Code and Codex](https://github.com/janreges/safe-grokbot-bridge/blob/main/skills/safe-grokbot-bridge/SKILL.md) : how a coding agent\nsets up and maintains the bridge\n- [Design and security model](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/design.md)\n- [OpenAPI document](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/openapi.json)\n\n- **`agent_exited` when starting a session.** Run the agent once by hand in that folder. It may\nneed a login, or the agent's`args` in the config contain a flag it does not know.\n- **A new session waits on a \"trust this folder\" dialog.** That is normal on the first start in a\nfolder. Answer with`{\"keys\": [\"Enter\"]}` .\n- **The bridge runs as a service and cannot find `claude` or `codex`.** Services get a minimal` PATH` . Set absolute`command` paths in`[agents.*]` , or set`PATH` in the service definition,\nand run`safe-grokbot-bridge check` in the same environment.\n- **A Claude Code session outside tmux does not react to messages (experimental).** A session\nthat runs without permission prompts may hold a message from another process for local\napproval, and drops it after a few minutes. Approve it in that session. For unattended use,\nset`\"crossSessionInbound\": \"accept\"` on purpose, in`~/.claude/settings.json` (all your\nsessions) or with`--settings` for one session you start; a project or local settings file\ncannot grant it. It applies to every cross-session message the session receives. The[design](https://github.com/janreges/safe-grokbot-bridge/blob/main/docs/design.md#84-external-sessions-experimental) has the details.\n\nIssues and pull requests are welcome. See [CONTRIBUTING.md](https://github.com/janreges/safe-grokbot-bridge/blob/main/CONTRIBUTING.md).\n\nsafe-grokbot-bridge is an independent project. It is not affiliated with, endorsed by or sponsored by xAI, Cursor, Anthropic, OpenAI, Nous Research or Cloudflare. Grok, Cursor, Claude, Claude Code, Codex, Hermes and Cloudflare are trademarks of their respective owners.", "url": "https://wpnews.pro/news/show-hn-safely-connect-grokbot-to-your-pc-vm-chosen-folders-and-claude-codex", "canonical_source": "https://github.com/janreges/safe-grokbot-bridge", "published_at": "2026-11-01 09:47:36+00:00", "updated_at": "2026-11-01 10:23:51.306003+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-safety"], "entities": ["safe-grokbot-bridge", "Grok Bot", "xAI", "Claude Code", "Codex CLI", "Hermes Agent", "Cloudflare", "tmux"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/show-hn-safely-connect-grokbot-to-your-pc-vm-chosen-folders-and-claude-codex", "markdown": "https://wpnews.pro/news/show-hn-safely-connect-grokbot-to-your-pc-vm-chosen-folders-and-claude-codex.md", "text": "https://wpnews.pro/news/show-hn-safely-connect-grokbot-to-your-pc-vm-chosen-folders-and-claude-codex.txt", "jsonld": "https://wpnews.pro/news/show-hn-safely-connect-grokbot-to-your-pc-vm-chosen-folders-and-claude-codex.jsonld"}}