Remote, captured, auditable execution on a machine you cannot log into.
A CLI, and a Claude Code skill. Someone can reach the machine. You cannot, and you are the one who knows what to ask it. heliograph runs that gap as a loop rather than a relay: you push a step, it runs on the far side, and the whole run comes back as a log with every line timestamped in UTC, whether it passed or failed.
If you can SSH in yourself, do that instead. This is for when you cannot.
Does this sound familiar
- No SSH access to production, and you are not going to be given any
- Air-gapped, or behind a bastion, a jump host or a VPN you are not on
- A client-owned estate where only their staff can log in
- Blocked by policy rather than capability: restricted, change-controlled, somebody else's sign-off
- The fourth round of "can you run this and paste the output", and what came back was a screenshot of half a terminal
For an AI agent that cannot reach the machine
Claude Code is excellent on a box it can run commands on. On a production machine behind a bastion, in a client-owned estate, or behind a change-control policy, it cannot run anything at all.
heliograph gives it a way to ask: publish a step, and read back a log with every line timestamped, whether the run passed or failed. The operator runs one command, once, and stops being anybody's terminal.
How it works with Claude Code, or drive it as typed tools from any agent through the MCP server.
The three components
| control | your machine: the heliograph CLI, the skill that drives it, and you |
| transport | the channel: git, relay, file share, bundle, object store |
| station | the far side: plain bash - or plain PowerShell, for an estate with no bash - planted by heliograph bootstrap, and the loop running on it |
One repository carries all three, and the boundary is the gap: everything under station/ runs on the far side and depends on nothing - bash 4+, git, GNU coreutils. No Go will ever cross it, and CI enforces that.
Two properties that make a log-only loop workable
Every line carries a UTC timestamp, so a hang shows up as a gap. After the fact, in an untimed log, a hang and slow progress are indistinguishable. This is the single most useful property of these logs, and heliograph logs --gaps turns reading it from a discipline into arithmetic.
The exit code survives and the log ships even on failure, so a failed run reads as clearly as a successful one and a round trip is never wasted.
What it will not do
Give you access you do not have. Two of its three shapes, the beacon and the flare, never tunnel, proxy or hold a connection open to a host you control, and there is nothing in either to punch through a firewall with. A raw TCP transport was considered and dropped for exactly that reason: an unauthenticated, always-on reverse connection is a C2 channel by any blue team's definition, and that sentence is a large part of why this class of tool is permitted in the estates it targets.
The third shape, the beam, is a live connection and does hold a line open - deliberately, off by default, and under its own controls. Where an estate forbids a reverse connection outright, the beacon and the flare still do the whole job without one.
Every command runs on the far side because someone with legitimate access chose to run it.