safe-grokbot-bridge로 원격 AI가 PC의 코딩 에이전트를 조작한다

safe-grokbot-bridge는 Grok Bot 같은 원격 AI 에이전트가 허용된 폴더의 파일과 Git 기록을 읽고, PC에서 실행 중인 Claude Code·Codex·Hermes 세션을 확인하거나 새 세션을 시작하도록 돕는 오픈소스 데몬이다. Linux, macOS, Windows에서 사용할 수 있으며, 원격 접근으로 기기에서 명령을 실행하거나 파일을 바꿀 수 있으므로 격리된 환경에서 필요한 권한만 부여해야 한다.

이 브리지는 기기에 원격으로 접근하게 한다. 설정에 따라 원격 에이전트는 공개한 폴더의 파일과 Git 기록을 읽을 수 있고, 시작하거나 메시지를 보낸 코딩 에이전트를 통해 프로그램과 명령을 실행하고 파일을 변경할 수 있다. 에이전트의 권한 확인 절차를 거칠 수도 있고, 허용한 경우 확인 없이 실행할 수도 있다.

제작자는 개인 데이터와 자격 증명이 있는 주 워크스테이션 대신 가상 머신, 전용 WSL 2 배포판 또는 별도 컴퓨터에서 브리지와 이 브리지가 조작하는 에이전트를 실행하라고 권고한다. 실행 위치 안내를 참고할 수 있다.

safe-grokbot-bridge는 기본적으로 127.0.0.1에서만 요청을 받는다. cloudflared가 기기에서 외부로 터널을 열기 때문에 기기에서 포트를 공개하지 않아도 된다. 공개 주소를 사용할 경우 TLS와 공개 키 고정(public-key pinning)을 적용할 수도 있다. Grok Bot은 비밀 저장소에 보관한 토큰을 베어러 토큰으로 보내며, 요청은 인증·속도 제한·허용 폴더 검사를 거친다. 브리지는 에이전트 세션을 나열하고 시작·조작하며, 파일과 Git 기록은 읽기 전용으로 제공한다.

기능과 접근 범위

브리지는 Claude Code, Codex CLI, Hermes Agent 세션이나 tmux에서 실행되는 다른 터미널 프로그램을 나열하고 시작하거나, 메시지를 보내고 중지할 수 있다. tmux 세션은 사용자가 언제든 터미널에 접속할 수 있는 방식이다. tmux가 없거나 요청에 따라 사용하는 헤드리스 방식에서는 메시지마다 비대화형 실행을 한 번 수행하고, 에이전트 세션 ID로 대화를 이어간다. 세션 시작 시 모델, 추론 수준, 권한 확인 우회(허용한 경우에만), 이전 대화 재개, 답변 후 세션을 닫는 keep_alive: false 등을 설정할 수 있다.

세션 상태는 Claude Code 자체 상태, 세션별 턴 완료 훅, 터미널 활동을 바탕으로 확인한다. 브리지는 상태를 추측하는 대신 장기 폴링(long-polling)으로 응답을 기다린다. 파일 기능은 .gitignore를 반영한 디렉터리 목록, 줄 범위를 지정한 텍스트 파일 읽기, git status, log, diff, show를 제공한다. 파일 API는 .env 파일이나 개인 키 같은 비밀 정보를 제공하지 않지만, Git 출력은 필터링하지 않으므로 공개한 저장소에 커밋된 내용은 볼 수 있다.

보안 기능으로는 256비트 베어러 토큰과 토큰 해시 저장, 인증 실패가 반복된 IP의 차단, 토큰별 요청 속도 제한, 폴더별 권한(files, git, sessions, input, start)이 있다. 모든 요청을 감사 로그에 기록하며 범용 셸 API는 제공하지 않는다. 공개 주소에는 TLS가 필요하다. 자체 서명 인증서와 공개 키 고정은 인증 기관(CA) 없이 사용할 수 있다.

LLM 클라이언트를 위해 OpenAPI 3.1 명세를 제공한다. 응답에는 내용이 불완전한지와 다음에 할 작업이 표시되며, Grok Bot이 브리지를 사용하고 새 기기를 연결하도록 안내하는 준비된 스킬도 포함한다. 실행 파일은 플랫폼별로 하나이며 설정은 TOML 파일 하나로 관리한다.

설정과 사용

권장 방식은 두 가지 스킬을 설치하는 것이다. 빠른 설정 안내에 따르면 Grok Bot에 클라이언트 스킬을, 기기의 Claude Code·Codex 또는 Hermes에 브리지 스킬을 설치한다. 그런 다음 Grok Bot에 Use the safe-grokbot-bridge-client skill to connect a new machine named pc1.이라고 요청한다. 봇은 Cloudflare Tunnel을 만들고 설정 메시지를 제공한다. 이를 기기의 코딩 에이전트에 붙여 넣으면 공개할 폴더와 허용할 작업을 확인한 뒤 설치와 설정을 진행한다. 사용자가 직접 옮겨야 하는 비밀 정보는 두 개다. 단계별 설정 안내에는 프롬프트를 포함한 절차가 있다.

직접 설치하고 설정할 때는 다음 명령을 사용한다. 플랫폼에 맞는 압축 파일은 릴리스 페이지에서 받거나, 저장소를 통해 빌드할 수 있다.

# 1. Install: download the archive for your platform from the releases page, or build it
cargo install --locked --git https://github.com/janreges/safe-grokbot-bridge

# 2. Create a config with a fresh token (printed once) and your projects folder as a workspace
safe-grokbot-bridge init --workspace ~/projects

# 3. Allow driving agents there: add "input" and "start" to `allow` in the file `init` wrote
# (Linux: ~/.config/safe-grokbot-bridge/config.toml,
# macOS: ~/Library/Application Support/safe-grokbot-bridge/config.toml), then review everything
safe-grokbot-bridge check

# 4. Run it, and publish it with a Cloudflare Tunnel (see docs/deployment.md)
safe-grokbot-bridge serve

그 뒤 Grok Bot 연결 안내를 따라 연결하거나, HTTP를 지원하는 클라이언트에서 API를 호출한다. 에이전트를 claude 대신 safe-grokbot-bridge launch claude로 시작하면 브리지의 턴 훅이 있는 tmux에서 실행되어 원격 에이전트가 세션을 추적하고 이어서 작업할 수 있다. Codex도 같은 방식으로 실행할 수 있다.

저장소에는 두 가지 에이전트 스킬이 있으며 Claude Code와 Codex의 플러그인 마켓플레이스이기도 하다.

• 기기에서 사용하는 safe-grokbot-bridge 스킬은 브리지를 설치하고 공개 폴더와 봇의 권한을 사용자와 정한다. 설정을 작성·변경하고 서비스로 실행하며 Cloudflare Tunnel을 연결하고, 업그레이드와 문제 해결도 맡는다. 적용 전에 계획을 보여주고 접근 권한을 확대하기 전 허락을 구하며 비밀 정보는 다루지 않는다.
• Grok Bot이나 다른 클라이언트에 쓰는 safe-grokbot-bridge-client 스킬은 API를 사용하고 비밀 정보로 기기를 찾거나 새 기기를 연결한다. 설치 방법은 Grok Bot 연결 안내에 있다.

Claude Code에는 claude plugin install safe-grokbot-bridge --marketplace janreges/safe-grokbot-bridge를 사용한다. Claude Code 2.1.292 이상이 필요하며, 그보다 이전 버전에서는 claude plugin marketplace add janreges/safe-grokbot-bridge를 먼저 실행한 뒤 claude plugin install safe-grokbot-bridge@safe-grokbot-bridge를 실행한다. Codex에서는 codex plugin marketplace add janreges/safe-grokbot-bridge를 실행하고, 이어 codex plugin add safe-grokbot-bridge@safe-grokbot-bridge를 실행한다. Hermes Agent에서는 hermes skills install janreges/safe-grokbot-bridge/skills/safe-grokbot-bridge --force를 사용한다. Hermes는 서비스를 설정하는 커뮤니티 스킬을 차단하므로 먼저 hermes skills inspect로 내용을 읽어야 한다.

Cursor, Gemini CLI, GitHub Copilot, OpenCode 등에서는 npx skills add janreges/safe-grokbot-bridge --skill safe-grokbot-bridge -g를 쓸 수 있다. 수동 설치는 skills/safe-grokbot-bridge/를 에이전트 스킬 폴더(예: ~/.claude/skills/ 또는 ~/.agents/skills/)에 복사하면 된다. 새 세션을 시작한 뒤 Set up safe-grokbot-bridge on this machine 또는 Let the bot also start agents in ~/projects/app.처럼 요청할 수 있다. 업데이트 명령은 Claude Code에서 claude plugin update safe-grokbot-bridge@safe-grokbot-bridge, Codex에서 codex plugin marketplace upgrade safe-grokbot-bridge 뒤에 codex plugin add 명령을 다시 실행하는 방식이다. Hermes는 hermes skills update, 그 밖의 환경에서는 npx skills update를 사용한다.

API와 세션 동작

GET /healthz를 제외한 모든 요청에는 Authorization: Bearer <token>이 필요하다. 경로는 모두 절대 경로다. 다음은 API 호출 예시다.

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?

# Start Claude Code in tmux with a task, then wait (up to 90 s per call) for the answer
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

# Follow up, or answer a permission prompt with keys
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"]}'

# Read-only access
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"

GET /v1/info는 기기, 버전, 에이전트, 워크스페이스와 권한, 제한 정보를 제공한다. GET /v1/files와 GET /v1/files/content는 디렉터리 목록과 줄 범위별 텍스트 파일을 읽는다. GET /v1/git/{status,log,diff,show}는 읽기 전용 Git 기능이다. GET /v1/sessions는 볼 수 있는 워크스페이스의 세션을 나열한다. POST /v1/sessions는 cwd, agent, runner, prompt, model, effort, bypass_permissions, keep_alive, resume 설정으로 세션을 시작한다. GET /v1/sessions/{id}?wait=&lines=는 상태, 마지막 답변, 터미널 화면을 제공하고 작업 중에는 장기 폴링한다. POST /v1/sessions/{id}/input은 text와 keys를 받는다. DELETE /v1/sessions/{id}는 브리지가 시작한 세션을 중지한다. GET /openapi.json은 OpenAPI 문서를 제공하며 저장소에도 문서가 있다.

세션 실행 방식은 다음과 같다.

세션 상태는 working, waiting(권한 확인이나 질문 대기), idle, finished(답변 후 keep_alive: false로 닫힘), exited, failed, unknown이다. 대기 상태에서는 screen을 읽고 keys로 응답할 수 있다.

브리지는 자신이 시작한 세션이나 프로그램이 에이전트(또는 에이전트로 끝나는 래퍼)인 터미널 창에만 입력한다. tmux 셸에서 사용자가 시작한 에이전트는 목록에는 나오지만, 에이전트가 종료된 뒤 입력이 셸로 전달될 수 있어 브리지가 입력하지 않는다. [experimental] external_sessions를 켜면 해당 환경의 Claude Code와 Codex는 자체 받은 편지함이나 큐를 통해 메시지를 받는다. resume은 대화가 진행된 폴더 안에서만 그 대화를 이어간다.

보안과 지원 환경

토큰을 가진 사람은 기기에서 코딩 에이전트를 작동시킬 수 있고, 허용한 경우 권한 확인 없이 실행할 수도 있다. 제작자는 토큰을 SSH 키처럼 취급하라고 안내한다. 브리지가 제어하는 에이전트는 사용자의 권한으로 실행되므로, 필요한 프로젝트와 자격 증명만 둔 가상 머신·전용 WSL 2 배포판·별도 컴퓨터에서 사용해야 한다. 자세한 내용은 실행 위치 안내를 참고할 수 있다.

토큰은 256비트이며 SHA-256 해시로 저장하고 상수 시간 방식으로 비교한다. 인증 실패가 반복되면 클라이언트 IP를 차단하고 토큰마다 요청 속도를 제한한다. 루프백에서는 일반 HTTP만 허용한다. 외부 공개는 Cloudflare Tunnel로 할 수 있고, 선택적으로 Access 서비스 토큰을 두 번째 인증 단계로 설정하거나 키 고정을 적용한 TLS를 사용할 수 있다. 폴더 권한은 폴더별로 설정하며 기본값은 읽기 전용이다. 경로를 정규화해 ..이나 심볼릭 링크로 허용 범위를 벗어날 수 없도록 한다.

브리지 자체에는 임의 명령을 실행하는 셸 API가 없다. Git도 저장소 설정이 프로그램을 실행하지 못하도록 하는 옵션으로 실행한다. 다만 브리지가 시작하는 코딩 에이전트는 각자 권한 시스템에 따라 명령을 실행할 수 있다. 자세한 내용은 위협 모델과 SECURITY.md에 있다.

문서와 문제 해결

문서에는 Cloudflare Tunnel을 사용하는 Grok Bot 설정 안내, 설정 참조, Cloudflare Tunnel·VPS·서비스 실행을 다루는 배포 안내, 준비된 스킬을 포함한 Grok Bot 연결 안내, Claude Code와 Codex용 에이전트 스킬 안내, 설계 및 보안 모델, OpenAPI 문서가 있다.

세션 시작 때 agent_exited가 나오면 해당 폴더에서 에이전트를 직접 한 번 실행해 본다. 로그인이 필요하거나 설정의 에이전트 args에 알 수 없는 옵션이 있을 수 있다. 새 세션이 “이 폴더를 신뢰하겠습니까” 대화 상자에서 기다리는 것은 폴더에서 처음 실행할 때 정상이며, {"keys": ["Enter"]}로 응답할 수 있다.

브리지를 서비스로 실행했을 때 claude나 codex를 찾지 못하면 서비스의 PATH가 최소 구성일 수 있다. [agents.*]에 명령의 절대 경로를 지정하거나 서비스 정의에서 PATH를 설정한 뒤, 같은 환경에서 safe-grokbot-bridge check를 실행한다.

실험 기능을 켠 상태에서 tmux 밖의 Claude Code 세션이 메시지에 응답하지 않을 수도 있다. 권한 확인 없이 실행되는 세션은 다른 프로세스에서 온 메시지를 로컬 승인 대기 상태로 두었다가 몇 분 뒤 버릴 수 있다. 해당 세션에서 승인해야 한다. 무인 실행을 원한다면 ~/.claude/settings.json에서 모든 세션에 적용하거나 시작하는 한 세션에 --settings로 "crossSessionInbound": "accept"를 명시적으로 설정한다. 프로젝트 설정이나 로컬 설정 파일로는 이 권한을 부여할 수 없다. 설정은 세션이 받는 모든 교차 세션 메시지에 적용된다. 자세한 내용은 설계 문서의 외부 세션 설명을 참고할 수 있다.

이슈와 풀 리퀘스트를 받으며, 기여 방법은 CONTRIBUTING.md에 있다. 라이선스는 MIT다.

safe-grokbot-bridge는 독립 프로젝트이며 xAI, Cursor, Anthropic, OpenAI, Nous Research 또는 Cloudflare와 제휴하거나 이들의 승인·후원을 받은 프로젝트가 아니다. Grok, Cursor, Claude, Claude Code, Codex, Hermes, Cloudflare는 각 소유자의 상표다.