# heliograph

> Remote, captured, auditable execution on a machine you cannot log into. 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.

## Docs

- [heliograph](https://heliograph.dbhq.uk/index.md): Remote, captured, auditable execution on a machine you cannot log into.
- [Install](https://heliograph.dbhq.uk/install.md): A single static binary, no runtime.
- [Quick start](https://heliograph.dbhq.uk/quickstart.md): From nothing to a captured log, in five steps. It assumes somebody on the far side can run one command once, and nothing else.
- [heliograph compared with AWS SSM Run Command and Azure Run Command](https://heliograph.dbhq.uk/compared.md): If you can use Run Command, use it. This page is for the estate where you cannot, and for the engineer who wants to know what the difference actually is before adopting a tool nobody has heard of.
- [Claude Code](https://heliograph.dbhq.uk/claude-code.md): heliograph ships as a Claude Code skill and plugin. Install it, and Claude can set up the transport, write the steps, drive the run and read the log back, on a machine it has no way to reach itself.
- [Codex](https://heliograph.dbhq.uk/codex.md): heliograph ships as a Codex skill, and as an MCP server. Install either and Codex can set up the transport, write the steps, drive the run and read the log back, on a machine it has no way to reach itself.
- [MCP server](https://heliograph.dbhq.uk/mcp.md): heliograph mcp turns the CLI into a set of tools any MCP-capable agent can call. Claude Code, Codex CLI, Claude Desktop, Cursor, Windsurf, Cline, Zed - anything that speaks the Model Context Protocol.
- [The station](https://heliograph.dbhq.uk/station.md): The far side. A directory of plain text, planted into a private transport repo, that watches for a request, runs one step, and sends the log back.
- [Planting a station](https://heliograph.dbhq.uk/bootstrap.md): Getting the far side onto the machine. Three routes, and the operator's job is the same whichever you take: clone, run one command, walk away.
- [Writing a step](https://heliograph.dbhq.uk/steps.md): A step is one file that answers one question. It prints to stdout and knows nothing about logging, timestamps or delivery - the runner owns all of that. That is what makes a step runnable on its own, and it is the whole contract.
- [The runner](https://heliograph.dbhq.uk/runner.md): start.sh, station.sh, run.sh and caprun.sh, and every knob each one honours. This is the reference for the far side's own scripts. Their PowerShell twins - start.ps1, station.ps1, run.ps1 and caplib.psm1, for an estate with no bash - are at the bottom of this page.
- [The capture contract](https://heliograph.dbhq.uk/conformance.md): There is one specification of the capture pattern, and this is it. Not a description of it - an executable one, in tests/conformance/.
- [Where a station can run](https://heliograph.dbhq.uk/hosts.md): Sometimes there is no willing human to start ./start.sh and leave it running. A station needs very little, so it can run almost anywhere - and this page publishes the contract first, then says honestly which hosts have actually been proven.
- [Docker and Kubernetes](https://heliograph.dbhq.uk/containers.md): Two hosts that need no OS to own. Both are proven: CI builds the image and runs a real loop in it, and applies the shipped manifest to a real cluster.
- [Making the loop outlive the session](https://heliograph.dbhq.uk/service.md): The operator starts the station and walks away. If it dies when they log out, they have not walked away - they have to come back, which is the relaying this tool exists to remove.
- [Running a station in Azure](https://heliograph.dbhq.uk/azure.md): Five templates, when there is no willing human to start ./start.sh and leave it running. Each ships as Terraform; four also ship as bicep, because estates are split on which they accept. The Function App is Terraform only - it deploys a Python function package rather than only compute, and that step has no bicep equivalent worth maintaining twice.
- [Running a station in a pipeline](https://heliograph.dbhq.uk/pipelines.md): A build agent is a host too, and often the only compute in an estate that can already reach both the git host and the target. station/bash/pipelines/ ships a GitHub Actions workflow and an Azure Pipelines definition.
- [Windows](https://heliograph.dbhq.uk/windows.md): Two different questions get confused here, so this page separates them.
- [Air-gapped](https://heliograph.dbhq.uk/air-gapped.md): Running heliograph on a machine with no network path at all, or nearly none. What works today, what is designed and not finished, and how to tell which kind of air gap you actually have.
- [Transports](https://heliograph.dbhq.uk/transports.md): A transport is the channel a request goes out on and a log comes back through. The loop is identical whichever you pick: same request format, same gates, same log. That is deliberate, and it is what lets you change transport without relearning the method.
- [What works with what](https://heliograph.dbhq.uk/matrix.md): Three things have to line up before a single command runs: a transport to carry it, a station to run it, and a controller to publish it from. This page is all three, and which combinations actually work.
- [The relay](https://heliograph.dbhq.uk/relay.md): The only transport that needs no estate infrastructure at all. No git host, no storage account, no VNet, no inbound rule. Both sides dial out over ordinary HTTPS and meet at a server neither of them trusts.
- [Intercom - when you can reach the station](https://heliograph.dbhq.uk/intercom.md): Every other transport exists because you cannot reach the far side. This one is for the narrower case where you can: the station sits behind a public HTTPS endpoint, and storage or git in the middle is indirection with no purpose.
- [CLI reference](https://heliograph.dbhq.uk/cli.md): Every command the control side has, and the reasoning behind the ones that are not obvious.
- [Secrets](https://heliograph.dbhq.uk/secrets.md): Captured logs are committed and delivered, so anything a command prints lands in history permanently and cannot be unpublished. Every rule here follows from that one sentence.
- [Security](https://heliograph.dbhq.uk/security.md): What heliograph refuses to do, what it gates, and what it cannot promise. This page is written to be read by somebody deciding whether to permit it in a regulated estate.
- [The method](https://heliograph.dbhq.uk/method.md): The tooling exists to serve this, not the other way round. Every rule here was paid for by an investigation that went wrong first.
- [What might come next, and what never will](https://heliograph.dbhq.uk/roadmap.md): Three questions arrive constantly: "could it go over X", "could it run on Y" and "could I drive it from Z". This page answers all three for every candidate anyone has raised, with a verdict and the reason, so that an estate can tell in one read whether it is waiting for something or whether the answer is no.
- [Other things DBHQ makes](https://heliograph.dbhq.uk/dbhq.md): heliograph is one of several. The rest are here so you do not have to go looking, and because a tool is easier to trust when you can see what else the people who wrote it have shipped.

## Source

- [heliograph](https://github.com/dbhq-uk/heliograph): the control CLI and transports
- [station/bash](https://github.com/dbhq-uk/heliograph/tree/main/station/bash): the far-side station, plain bash, in this repository