heliograph

Remote, captured, auditable execution on a machine you cannot log into

A free, open-source tool by DBHQ

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

you        heliograph send net-probe ────────────────▶ transport
station    picks it up within seconds, runs it
           pushes status, then the log ──────────────▶ transport
you        heliograph logs --last --gaps ◀────────────

The three ways across

heliograph carries a request to a machine you cannot log into, and brings the log back. There are three ways across the gap, and they differ in one thing: what stays held, and for how long.

Beacon. You cannot reach the machine and it cannot reach you - but you can both reach one agreed place. You leave the request there and walk away. Later the machine passes by, picks it up, runs it, and leaves the log for you to collect. Nobody is ever connected; a message waits in the middle. It is the safest of the three, because the code being run is already on the far side and can be read before anything happens - and the slowest, because you wait for the next visit.

Flare. You can reach the machine's door directly. You knock, hand over the request, wait on the step while it runs, and take the log away in the same visit. Nothing waits in the middle and no line stays open. Faster, because there is no pickup to wait for. The trade: you bring the code with you, so the machine trusts the door rather than vetting the code in advance.

Beam. You and the machine bring up a connection and hold it open. Either side can speak at any moment and the other hears it at once, until you hang up. A real session, not a message or a knock - and the most exposed, because while the line is open anything can travel down it. You turn it on deliberately and close it when you are done. It is designed, and not yet a transport you can pick.

In one line: a beacon holds a message, a flare is a single exchange, a beam holds the connection itself.

Does this sound familiar

• You have no SSH access to production, and you are not going to be given any.
• The environment is air-gapped, or behind a bastion, a jump host or a VPN you are not on.
• It is a client-owned or customer-managed estate. Only their staff can log in.
• Access is blocked by policy, not capability: restricted, change-controlled, somebody else's sign-off.
• You are on the fourth round of "can you run this and paste the output", and what came back was a screenshot of half a terminal.
• You are an AI coding agent driving an investigation, and you need the evidence rather than somebody's summary of it.

If you can just SSH in, you do not need this.

Three roles, one boundary

The boundary is the gap, and the layout states it once:

Nothing is ever installed on the far side. The station is plain text you can read before you run - bash 4+, or PowerShell 5.1 for a Windows estate that has no bash and will not be given any - and no Go will ever appear under station/ beyond the one file that lets the CLI carry the payload. CI enforces it. That constraint is the entire proposition on a locked-down box where installing anything is its own change request.

Install

# Linux and macOS, from a release
curl -sSL https://github.com/heliograph-io/heliograph/releases/latest/download/heliograph-linux-amd64 \
  -o /usr/local/bin/heliograph && chmod +x /usr/local/bin/heliograph

# or from source
go install github.com/heliograph-io/heliograph/cmd/heliograph@latest

A single static binary, no runtime. Checksums are published with each release, and the binary carries the station payload it was built with.

The build is reproducible: packaging/reproduce.sh v0.4.3 rebuilds every released artefact from the tag and arrives at the published hashes, so "the binary in the path is the source you read" is something you check rather than something we say. Full account, including what is not yet covered, at docs.heliograph.io/provenance.

The agent skill - the same loop, driven from Claude Code, Codex, Cursor and friends:

/plugin marketplace add dbhq-uk/marketplace
/plugin install heliograph@dbhq         # Claude Code
./install-codex.sh                      # Codex, from a clone
./install.sh                            # Claude Code, from a clone
npx skills add heliograph-io/heliograph       # any agent, via skills.sh

Use

heliograph bootstrap ~/transport/payments             # plant the station payload
heliograph init payments --dir ~/transport/payments   # git, the default
heliograph plant                                      # what to send the operator
heliograph send net-probe HOSTS="sql01 sql02"         # publish a request
heliograph watch                                      # follow it
heliograph logs --last                                # read the whole log
heliograph logs --last --gaps                         # where it stalled
heliograph doctor                                     # will this work from here
heliograph mcp                                        # serve all of the above as tools

The operator's whole job is what plant prints: clone the transport repo, run ./start.sh, walk away. The loop is read-only unless the operator said otherwise: every step declares itself (# heliograph-mode: read-only or action), one that declares neither does not run, and the station refuses an action unless it was started with --allow-actions. It will not run as root either.

For an agent, heliograph mcp is the same CLI as typed MCP tools:

claude mcp add heliograph -- heliograph mcp

The gates do not move. A tool call publishes a request; the station still decides whether to run it.

--gaps is the one worth knowing about. "Scan the timestamp column for gaps before reading the content" is the most valuable instruction in the method, and it is arithmetic:

$ heliograph logs --last --gaps
demo-20260906T183628Z.txt
5 captured lines

1 interval(s) of 10s or more, longest first.
Each is attributed to the line BEFORE it, which is what was running.

   3m12s  after  09:14:02 | Refreshing state...

The gap belongs to the line before it: the stamp on a line is when that line was produced, so a long interval means the operation named on the preceding line is what took the time. A log where every line carries the same timestamp is reported as an error, not as "no gaps".

Status

A transport that works on one side of the gap is not a transport, so this table names both sides. Git and relay are driven end to end by the CLI and proved in CI; what the others still need, and in what order, is the roadmap.