One line: heliograph's MCP server exposes the CLI loop as tools, letting an agent discover configured estates, publish steps to a remote station it cannot log into, poll run status, and read back timestamped, gap-analysed logs.
Discover estates (heliograph_estates): list configured estates and the transport each uses; call first when you don't know which estate to act on.
Preflight a transport (heliograph_doctor): check read/write access from here and change nothing before committing to a costly round trip.
Publish a step (heliograph_send): fire a registered step (e.g. net-probe or steps/net-probe.sh) with env vars and a note, returning immediately without waiting.
Poll for completion (heliograph_status): track state (starting/running/idle/cancelled/refused/stopped/undelivered) until a terminal one; unknown states mean keep polling, refused points at the permitting flag, undelivered means stop waiting.
Find logs (heliograph_logs): list captured logs newest first; each name carries the request id returned by send.
Read logs (heliograph_read_log): retrieve a whole log, every line UTC-timestamped, including passing probes that act as controls.
Locate stalls (heliograph_gaps): report the longest intervals in the timestamp column first, each attributed to the preceding (running) line; identical timestamps across all lines are reported as an error.
Respect the gates: the station decides whether to run anything; steps declaring no mode are refused, and state-changing steps need CONFIRM=yes plus a station started with --allow-actions.
Allows using a Git repository as the transport for sending commands to a remote machine and receiving timestamped execution logs, including gap analysis for stalls.
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 ◀────────────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.
Related MCP server: mcp-drone-mcp
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.
The boundary is the gap, and the layout states it once:
control | your machine: the |
transport | the channel: git, relay, file share, bundle, object store - all behind one interface, so the read-only gates live in one place and cannot drift per transport |
station | the far side: |
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.
# 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@latestA 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.shheliograph 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 toolsThe 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 mcpThe 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".
control CLI over git | works, tested end to end against a stock station |
| works: the binary plants the station it was built with |
| works |
MCP server ( | works |
bash station | in use over git: the loop, the gates, the capture, Azure hosts, Kubernetes, the Windows launcher |
relay | works end to end. |
file share, bundle, object store | station transports exist for all three in the bash station ( |
Azure Blob | works end to end, through |
PowerShell station | ships. |
documentation site | docs.heliograph.io: the CLI, the transports, and the far side - the station, the runner, steps, hosts, Azure, Windows, containers, services, secrets, security and the capture contract |
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.
This table was wrong for some time, and the reason is worth keeping. Until 21 Sep 2026 it said relay was "half a transport" that "no CLI command can select", that the station had no transport for share, bundle or object store, and that the PowerShell station was "planned". All four were false against the code in this repository. The documentation site did not drift, because
transports_doc_test.gobinds it toinitTransportsand to the station transport directories - and nothing bound this file. It is bound now, byTestReadmeTransportClaimsMatchTheCode.The cost was not confined here:
skills.dbhq.uk/heliographdeliberately published the more conservative claim because this README contradicted the documentation site, and recorded that it would stay understated "until heliograph settles which is true". This is that settlement.
Both sides dial out over ordinary HTTPS, so an estate needs no git host, no storage account and no VNet. Hosted, and self-hostable from the same binary.
Not yet usable end to end. The station side is complete and the server is deployed; no CLI command can select it, so the near side is the missing half.
The relay cannot read your logs, and cannot make a station run anything.
That second half is the one that matters: a relay able to forge a request
would be code execution inside every estate at once. Content is end-to-end
encrypted with keys the relay never holds, and every message is signed.
Nothing bespoke - age primitives plus
Ed25519. The full account, including what DBHQ can and cannot honestly claim,
is in
docs/specs/2026-09-06-relay-encryption-design.md.
The relay server is its own repository,
heliograph-io/heliograph-relay,
because it holds no keys and must be publicly, obviously incapable of reading
anything it carries.
The beam is designed and not yet built; what follows is what it will do when it lands.
Two of the three shapes never hold a connection open. A beacon leaves a message where both sides can reach it, and needs nothing to be reachable, ever - no inbound port, no endpoint, no tunnel. A flare knocks, waits and leaves; what it does not do is hold the line open once the answer is back, and between the two of them an estate that will not have a held-open line at all still gets the whole job done.
The beam does hold a line open, live and two-way, and that is a tunnel. A blue team will read a held-open channel as one, because it is one. So it is off unless it is explicitly enabled on both ends, it is sealed and signed, and the station refuses to establish one unless it was started to allow it. Where an estate forbids a reverse connection, the beacon and the flare are the answer and nothing is lost but latency.
Every command still runs on the far side because someone with legitimate access chose to let it.
cmd/heliograph/ the control CLI, and `heliograph mcp`
cmd/heliograph-seal/ key generation for the relay transport
cmd/heliograph-site/ the static site generator
internal/transport/ git | relay | share | bundle | objstore
internal/bootstrap/ `heliograph bootstrap`: plants the embedded station
internal/wire/ the request and status documents that cross the gap
internal/seal/ sign-then-encrypt, for the relay
internal/logfile/ gap analysis
internal/mcp/ JSON-RPC over stdio, no dependencies
internal/estate/ which transport a name refers to
internal/plant/ what to send the operator
station/bash/ the bash station: everything that runs on the far side
station/bootstrap.sh the no-CLI bootstrap: clone this repo, run it by hand
skills/heliograph/ the agent skill: drives the CLI, and nothing else
tests/ the station's own suite, conformance contract included
site/content/ the documentation, one source, three renderings
infra/ terraform: DNS, Pages, R2 state
docs/specs/ the designs, written before the codeThe two halves used to be separate repositories, split along Go-versus-bash
rather than along the gap, and every reader had to work out which half they
were looking at. dbhq-uk/heliograph-skill was merged in on 2026-09-08 with
its full history; the reasoning is in
docs/specs/2026-09-08-station-and-skill-merge.md.
That repository was deleted on 2026-09-17 and the name is not in use. It stayed public and archived after the merge, and an archived repository is read-only rather than unreachable: it still cloned, its install.sh still ran, and the station in it had no request-env guard at all (heliograph-cloud#274). Its history is kept privately; this repository's own history carries the merge.
ROADMAP.md is where the work stands: what heliograph is for,
what works today, and the epics for now, next and later. Known defects are
issues labelled type: bug.
CONTRIBUTING.md covers working on it and
AGENTS.md is for an AI agent doing so. The skill is
skills/heliograph/SKILL.md;
docs/dev-setup.md sets it up from source with live
edits.
Apache 2.0 (c) 2026 DBHQ Consulting Ltd, and the prose under site/content/ is
CC BY 4.0. Relicensed from MIT on 2026-09-17; every commit
up to and including b689f9c stays available under MIT for ever. NOTICE
says why Apache rather than MIT, and what the change does not take away.
The relay is a separate repository and a separate licence: heliograph-relay is FSL-1.1-ALv2, fair source, converting to Apache 2.0 two years after each release. No shape is ever gated: beacon, flare and beam all work on a relay you host yourself.
Full statement, including the professional-services grant and its honest limit: https://docs.heliograph.io/licence
Check whether the transport works from here, and change nothing. Run this before a long step: read access is not write access, and finding out afterwards costs a whole round trip through somebody who cannot debug the machine.
Inputs: estate.
List the configured estates and the transport each uses. Call this first when you do not know which estate to act on.
Inputs: no named parameters.
Where a run stalled. Returns the intervals in the log's timestamp column, longest first, each attributed to the line BEFORE it, which is what was running. Do this before reading a long log: a hang and slow progress are indistinguishable without it. If every line carries the same timestamp the capture was buffered and the log cannot answer the question at all, which this reports as an error.
Inputs: name, estate, min_seconds.
List the captured logs, newest first. Each name carries the request id that produced it, so the log for a run you sent is the one whose name matches the id heliograph_send returned. Use this to find a log; use heliograph_read_log to read one.
Inputs: estate.
Read a captured log whole. Every line carries a UTC timestamp. Read all of it, including the parts that worked: a passing probe beside a failing one is the control that says what the failure means. A green exit means the probes that ran passed, not that the work happened.
Inputs: name, estate.
Publish a step for the station to run, and return immediately. This does NOT wait for the result: poll heliograph_status until it reports a terminal state, then read the log. The station decides whether to run it at all: a step that declares no mode is refused, and one that changes state needs CONFIRM=yes and a station started with --allow-actions.
Inputs: step (required), env, note, estate.
What the station is doing now. State is one of starting, running, idle, cancelled, refused, stopped or undelivered. Five of those are terminal: idle, cancelled, refused, stopped and undelivered. starting and running mean the run is still going. An empty state means the station has published nothing yet, which usually means it has not been started. A state you do not recognise is neither finished nor alive: a newer station may publish one, so keep polling rather than giving up. refused is not a failure: it means the station would not run the step, and the reason names the flag that would permit it. undelivered means the run finished and the log is complete but the transport would not take it, so waiting for more is exactly wrong.
Inputs: estate.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 7 tools
Each tool targets a distinct aspect of the heliograph system: estates, transport health, log reading, sending steps, status polling, gap analysis, and log listing. No two tools overlap in function, making misselection unlikely.
All tools share the 'heliograph_' prefix, but the suffix varies between bare verbs (send), verb-noun (read_log), and nouns (status, logs, gaps). This mix is readable but lacks a uniform verb_noun pattern, which could reduce predictability.
Seven tools is a well-scoped number for the domain. Each tool serves a clear purpose in the station interaction lifecycle, and there is no bloat or unnecessary duplication.
The tool surface covers the core workflows: test transport, send steps, poll status, list and read logs, and analyze stalls. Minor gaps exist (e.g., no tool to start/stop the station or manage configurations), but these appear to be handled externally.
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Securely control computers you explicitly pair through files, terminals, processes, screenshots, desktop UI/input, clipboard, browser automation, diagnostics, and document tools.
Control your authorized Windows computers via OAuth: files, shell, apps, and task status.
Give your AI hands on every computer you own. Remote control of your Windows, Mac and Linux machines from one ChatGPT, Claude or Cursor chat — even from your phone. Ask it to find out why the office server is crawling, update every PC in the house, sort out your mom's laptop from another city, or ship the site from your work machine while you're on a train. It runs commands, reads files and takes a screenshot when it needs to see the screen. You decide what each computer allows, and you can cut any of them off in a second.
