Show HN: Safely connect GrokBot to your PC/VM: chosen folders and Claude/Codex

Let a remote AI agent work on your machines, safely. safe-grokbot-bridge is a small daemon that gives an agent such as a Grok Bot a narrow, authenticated HTTP API to your computers. Through it the agent can read your project folders and git history, see the Claude Code, Codex and Hermes sessions running there, talk to them, and start new ones.

You 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.

Warning

This is remote access to your machine. Depending on your configuration, the remote agent can read files and git history in the folders you expose, and through the coding agents it starts or messages it can make the machine run programs and commands and change files: with the agents' permission prompts, or without them where you allow that. Use the bridge deliberately, only where this is acceptable, and grant as little as the work needs. Run it, together with the agents it drives, in an isolated environment such as a virtual machine, a dedicated WSL 2 distribution or a separate computer, not on your primary workstation with your personal data and credentials. See Where to run it.

flowchart LR
    subgraph cloud["Grok Bot's cloud computer"]
        bot["skill + curl<br/>secrets: URL, token"]
    end
    subgraph cf["Cloudflare"]
        edge["HTTPS edge<br/>optional Access"]
    end
    subgraph machine["Your machine"]
        cfd["cloudflared"]
        bridge["safe-grokbot-bridge<br/>127.0.0.1:4765<br/>token, lockout, rate limit<br/>workspace capabilities"]
        tmux["tmux: Claude Code, Codex,<br/>Hermes you can attach to"]
        headless["headless runs:<br/>claude -p, codex exec"]
        external["sessions outside tmux<br/>(experimental)"]
        files[("allowed folders:<br/>files and git, read-only")]
    end
    bot -- "HTTPS + bearer token" --> edge
    edge -- "tunnel, opened from the machine" --> cfd
    cfd --> bridge
    bridge --> tmux
    bridge --> headless
    bridge --> external
    bridge --> files

1. The bridge listens on 127.0.0.1 only.cloudflared opens an outbound tunnel, so no port is opened on the machine. (A public address with TLS and key pinning works too.)
2. The bot calls the API with curl and a bearer token kept in a Grok secret. Every request is authenticated, rate limited and checked against the folders you allowed.
3. 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.

• Agent sessions. List, start, message and stop Claude Code, Codex CLI and Hermes Agent sessions, or any other terminal program in tmux.
  • tmux: the agent runs in a live terminal you can attach to at any time (tmux attach -t … ).
  • Headless: every message is one non-interactive run, continued by the agent's session id.
  • Start options: model, reasoning effort, permission bypass (only where you allow it), resume of an earlier conversation, andkeep_alive: false to close a session once it has answered.
  • Reliable state: state comes from Claude Code's own status, per-session turn-complete hooks and terminal activity, so the client knows when an agent is working, waiting for an answer or done. It long-polls instead of guessing.
• Read-only project access. Directory listings (respecting.gitignore ), text files by line range,git status ,log ,diff andshow . The file endpoints never serve secrets such as.env files and private keys. Git output is not filtered, so anything committed to a repository you expose is visible.
• Security first. - 256-bit bearer tokens (only their hashes are stored), with per-IP lockout after failed attempts and per-token rate limits.
  • Per-folder capabilities (files ,git ,sessions ,input ,start ).
  • TLS required on any public address. A self-signed certificate with public-key pinning works out of the box, no CA needed.
  • Every request is written to an audit log, and no generic shell endpoint exists.
• Made for LLM clients. A completeOpenAPI 3.1 description. Every response says when it is incomplete and what to do next, and aready-made skill teaches Grok Bot to use it and to connect new machines.
• One binary for Linux, macOS and Windows. Configuration is one TOML file.

Recommended: two skills do it. Follow the quick setup:

1. Install the skills : one into Grok Bot, one into Claude Code, Codex or Hermes on the machine.
2. Tell Grok Bot "Use the safe-grokbot-bridge-client skill to connect a new machine named pc1." It creates the Cloudflare Tunnel and gives you a setup message. Paste that into your coding agent on the machine: it asks which folders to expose and what the bot may do there, then installs and configures everything. You only move two secrets by hand.

Step by step with prompts: Setup with Grok Bot and Cloudflare.

By hand:

cargo install --locked --git https://github.com/janreges/safe-grokbot-bridge

safe-grokbot-bridge init --workspace ~/projects

safe-grokbot-bridge check

safe-grokbot-bridge serve

Then connect Grok Bot, or call the API from anything that speaks HTTP.

Tip: start your agents with safe-grokbot-bridge launch claude (or codex) instead of claude. They then run in tmux with the bridge's turn hooks, so the remote agent can follow and continue your sessions.

The repository holds two skills, and is a plugin marketplace for Claude Code and Codex.

• safe-grokbot-bridge , for the coding agent on the machine: it installs the bridge, agrees with you on the folders it exposes and what the bot may do there, writes and later changes the config, runs it as a service, connects the Cloudflare Tunnel, upgrades and troubleshoots it. It shows you every plan before it applies it, asks before it widens access, and never handles your secrets.
• safe-grokbot-bridge-client , for Grok Bot or another client: it uses the API, finds your machines by their secrets, and connects new machines.Connecting Grok Bot shows how to install it.

Then start a new session and say, for example, "Set up safe-grokbot-bridge on this machine" or "Let the bot also start agents in ~/projects/app."

To update the skill later: claude plugin update safe-grokbot-bridge@safe-grokbot-bridge in Claude Code; codex plugin marketplace upgrade safe-grokbot-bridge, then the codex plugin add command again in Codex; hermes skills update in Hermes; npx skills update elsewhere.

Every request except GET /healthz needs Authorization: Bearer <token>. All paths are absolute.

B=https://bridge.example.com; H="Authorization: Bearer $SGB_TOKEN"

curl -sH "$H" $B/v1/info                                  # machine, agents, workspaces, limits
curl -sH "$H" "$B/v1/sessions?path=/home/me/projects/app"  # who is already working there?

curl -sH "$H" -H 'content-type: application/json' $B/v1/sessions -d @- <<'EOF'
{"cwd": "/home/me/projects/app", "agent": "claude", "prompt": "Run the tests and fix failures."}
EOF
curl -sH "$H" "$B/v1/sessions/sgb-app-claude-3f9a1c?wait=60"   # state, last_message, screen

curl -sH "$H" -H 'content-type: application/json' $B/v1/sessions/sgb-app-claude-3f9a1c/input \
     -d '{"text": "Also update the changelog."}'
curl -sH "$H" -H 'content-type: application/json' $B/v1/sessions/sgb-app-claude-3f9a1c/input \
     -d '{"keys": ["Enter"]}'

curl -sH "$H" "$B/v1/files?path=/home/me/projects/app&depth=2"
curl -sH "$H" "$B/v1/files/content?path=/home/me/projects/app/README.md"
curl -sH "$H" "$B/v1/git/log?dir=/home/me/projects/app&limit=10"

Session states: working, waiting (a permission prompt or question; read screen and answer with keys), idle, finished (closed after its answer with keep_alive: false), exited, failed, unknown.

The bridge types only into panes where nothing but the agent can receive the text: sessions it started, and panes whose program is the agent (or a wrapper that ends with it). An agent you started from a shell inside tmux is listed but not typed into, because text sent after the agent exits would reach the shell; with [experimental] external_sessions, Claude Code and Codex there take messages through their own inbox or queue instead. resume continues a conversation only in the folder where it was held.

A 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:

• Isolation: the agents the bridge drives run with your user's rights. Give them a virtual machine, a dedicated WSL 2 distribution or a separate computer that holds only the projects and credentials the work needs; seeWhere to run it .
• Tokens: 256-bit, stored as SHA-256 hashes, compared in constant time. A client IP is blocked after repeated failures, and each token has a request rate limit.
• Network: plain HTTP only on loopback. Publish it through a Cloudflare Tunnel, optionally with an Access service token as a second factor, or enable TLS with key pinning.
• Folders: capabilities per folder; access is read-only by default. Paths are canonicalized, so.. and symlinks cannot escape.
• No shell endpoint: the bridge itself never runs arbitrary commands, and git runs with options that keep a repository's own config from executing programs. The coding agents it starts do run commands, under their own permission systems.

Read the threat model and SECURITY.md.

• Setup with Grok Bot and Cloudflare : the guided setup, with prompts to paste

• Configuration reference

• Deployment: Cloudflare Tunnel, VPS, running as a service

• Connecting Grok Bot, with a ready-made skill

• Agent skill for Claude Code and Codex : how a coding agent sets up and maintains the bridge

• Design and security model

• OpenAPI document

• agent_exited when starting a session. Run the agent once by hand in that folder. It may need a login, or the agent'sargs in the config contain a flag it does not know.

• A new session waits on a "trust this folder" dialog. That is normal on the first start in a folder. Answer with{"keys": ["Enter"]} .

• The bridge runs as a service and cannot find claude or codex. Services get a minimal PATH . Set absolutecommand paths in[agents.*] , or setPATH in the service definition, and runsafe-grokbot-bridge check in the same environment.

• A Claude Code session outside tmux does not react to messages (experimental). A session that runs without permission prompts may hold a message from another process for local approval, and drops it after a few minutes. Approve it in that session. For unattended use, set"crossSessionInbound": "accept" on purpose, in~/.claude/settings.json (all your sessions) or with--settings for one session you start; a project or local settings file cannot grant it. It applies to every cross-session message the session receives. Thedesign has the details.

Issues and pull requests are welcome. See CONTRIBUTING.md.

safe-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.