README
¶
remote-exec
Secure, cross-OS remote execution for Claude Code. A controller — driven by a Claude Code subagent fleet, skills, and commands — discovers a remote machine by id, opens a mutually-authenticated channel, and runs analysis / build / deploy actions on it, with a cryptographically-enforced gate on destructive operations. Security model derived from Talos Linux.
Why
Claude Code runs on one machine but often needs to act on another — build on Linux, notarize on
macOS, test on Windows. remote-exec replaces ad-hoc SSH with a principled channel: mutual TLS,
per-instance identity, short-lived certs, role-based authorization, and human-in-the-loop
approval for anything destructive.
Components
| Binary | Role |
|---|---|
rexec-agentd |
The agent daemon. Runs as an OS service on macOS/Linux/Windows, terminates mTLS, serves the gRPC API, enforces policy. |
rexec |
The controller CLI Claude Code drives: agent enroll, agent identity, agent info, exec run, exec deploy. |
Quick start
On the agent host:
rexec-agentd ca init # mint the agent CA + server cert (prints agent id + fingerprint)
# optional destructive-op policy:
cp docs/policy.example.yaml <data-dir>/policy.yaml
rexec-agentd service install # install as an OS service (launchd/systemd/Windows)
rexec-agentd service start # or run directly: rexec-agentd serve --listen 127.0.0.1:50000
rexec-agentd token new --role rex:operator # issue a single-use join token
On the controller (where Claude Code runs):
rexec agent enroll --endpoint <host:port> --token <token> # pins id+fingerprint, writes ~/.rexec/config.yaml
rexec agent identity # ask the agent for its id, re-assert the pin
rexec agent info # host os/arch/version
rexec exec run go build ./... # non-destructive: streams output live
rexec exec deploy ./release.sh # destructive: goes through the approval gate
Security model (Talos-derived)
- PKI + enrollment (trustd pattern): one Ed25519 CA per agent; a single-use join token lets
the agent sign the controller's client cert only. The controller credential mirrors
talosconfig(CA + client cert/key + endpoints + pinned id/fingerprint). - mTLS + RBAC gate: gRPC over TLS 1.3 with client-cert verification. The caller's role lives
in the cert Subject
O=(rex:reader ⊂ operator ⊂ admin); a per-method interceptor enforces it. A reader cert physically cannot invokeexec run; only an admin cert reachesexec deploy. - Identity + pinning: stable agent id (host UUID) pinned to
sha256(server-cert); every call re-asserts it and errors on mismatch. - Destructive-op gate: admin role → agent
policy.yaml(deny|allow|ask) → single-use, command-bound, 5-minute live approval surfaced to the human viaAskUserQuestion.
See docs/DESIGN.md, docs/research/TALOS-SECURE-COMMS.md, and docs/CLAUDE-INTEGRATION.md.
Build / test
task build # go build ./...
task test # fast tests
task test:full # race + coverage
task proto # regenerate gRPC from proto/ (needs protoc + protoc-gen-go[-grpc])
Status
v1 complete (secure channel, streaming exec, destructive-op gate, cross-OS service, Claude Code surface). See docs/ROADMAP.md. WireGuard/SideroLink overlay is the v2 stretch (docs/BACKLOG.md).
License
BSD-3-Clause — see LICENSE. Copyright (c) 2026 dyammarcano.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
rexec
command
Command rexec is the remote-exec controller CLI that Claude Code drives: enroll with an agent, ask its identity, and run or deploy commands over the secure mTLS channel.
|
Command rexec is the remote-exec controller CLI that Claude Code drives: enroll with an agent, ask its identity, and run or deploy commands over the secure mTLS channel. |
|
rexec-agentd
command
Command rexec-agentd is the remote-exec agent daemon: it manages the agent CA and join tokens, terminates mTLS, serves the rexec.v1.Agent gRPC API, and enforces the destructive-op policy.
|
Command rexec-agentd is the remote-exec agent daemon: it manages the agent CA and join tokens, terminates mTLS, serves the rexec.v1.Agent gRPC API, and enforces the destructive-op policy. |
|
rexec-agentd/internal/app
Package app holds the remote-exec configuration and construction.
|
Package app holds the remote-exec configuration and construction. |
|
rexec-agentd/internal/db
Package db opens the agent's local SQLite store (pure-Go modernc driver).
|
Package db opens the agent's local SQLite store (pure-Go modernc driver). |
|
rexec-agentd/internal/platform
Package platform aggregates the agent's shared infrastructure (currently the SQLite store), constructed at startup and closed on shutdown.
|
Package platform aggregates the agent's shared infrastructure (currently the SQLite store), constructed at startup and closed on shutdown. |
|
rexec/internal/app
Package app holds the rexec configuration and construction.
|
Package app holds the rexec configuration and construction. |
|
internal
|
|
|
agentserver
Package agentserver implements the rexec.v1.Agent gRPC service on top of the enrollment service and the agent's identity.
|
Package agentserver implements the rexec.v1.Agent gRPC service on top of the enrollment service and the agent's identity. |
|
authz
Package authz enforces the destructive-op gate: it reads the caller's role from the client certificate's Subject Organization (O=) and authorizes each gRPC method against a per-method minimum-role table.
|
Package authz enforces the destructive-op gate: it reads the caller's role from the client certificate's Subject Organization (O=) and authorizes each gRPC method against a per-method minimum-role table. |
|
clientconfig
Package clientconfig models the talosconfig-style controller credential — the agent CA, the controller's client cert+key, target endpoints, and the pinned agent identity — persisted to ~/.rexec/config.yaml and turned into an mTLS dialing config.
|
Package clientconfig models the talosconfig-style controller credential — the agent CA, the controller's client cert+key, target endpoints, and the pinned agent identity — persisted to ~/.rexec/config.yaml and turned into an mTLS dialing config. |
|
enroll
Package enroll implements the token-bootstrapped controller enrollment flow.
|
Package enroll implements the token-bootstrapped controller enrollment flow. |
|
execute
Package execute runs a command and streams its stdout/stderr live through an emit callback, returning the process exit code.
|
Package execute runs a command and streams its stdout/stderr live through an emit callback, returning the process exit code. |
|
identity
Package identity derives a stable per-agent identifier.
|
Package identity derives a stable per-agent identifier. |
|
pki
Package pki mints and manages the remote-exec agent certificate authority: an Ed25519 CA that signs short-lived client and server leaf certificates from CSRs, plus helpers to generate CSRs and fingerprint certificates.
|
Package pki mints and manages the remote-exec agent certificate authority: an Ed25519 CA that signs short-lived client and server leaf certificates from CSRs, plus helpers to generate CSRs and fingerprint certificates. |
|
policy
Package policy is the agent-side half of the destructive-op gate.
|
Package policy is the agent-side half of the destructive-op gate. |
|
token
Package token issues and consumes short-lived, single-use join tokens that bootstrap controller enrollment (the Talos trustd pattern).
|
Package token issues and consumes short-lived, single-use join tokens that bootstrap controller enrollment (the Talos trustd pattern). |
|
transport
Package transport wires the Agent gRPC service onto mTLS.
|
Package transport wires the Agent gRPC service onto mTLS. |
Click to show internal directories.
Click to hide internal directories.