heliograph

---

Alguém consegue alcançar a máquina. Você não consegue, e é você quem sabe o que perguntar a ela. O heliograph percorre essa lacuna como um loop, não como um retransmissor: você publica uma etapa, ela é executada no lado distante, e toda a execução volta como um log com cada linha carimbada com horário em UTC, independentemente de ter passado ou falhado.

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 ◀────────────

Isso parece familiar?

• Você não tem acesso SSH à produção, e não vai receber nenhum.
• O ambiente é isolado (air-gapped), ou está atrás de um bastion, um jump host ou uma VPN na qual você não está.
• É um ambiente de propriedade do cliente ou gerenciado pelo cliente. Somente a equipe deles pode fazer login.
• O acesso é bloqueado por política, não por capacidade: regulado, restrito, controlado por mudanças.
• Você está na quarta rodada de "pode executar isso e colar a saída?", e o que voltou foi uma captura de tela de meio terminal.
• Você é um agente de IA de codificação conduzindo uma investigação e precisa das evidências, não do resumo de alguém sobre elas.

Se você consegue simplesmente fazer SSH, não precisa disso.

Três papéis, um limite

O limite é a lacuna, e o layout a declara uma vez:

controle	sua máquina: a CLI heliograph, heliograph mcp e a habilidade que as conduz. Vá, e o que o lado próximo puder suportar
transporte	o canal: git, relay, compartilhamento de arquivos, pacote, armazenamento de objetos — tudo atrás de uma única interface, para que os portões somente leitura fiquem em um só lugar e não possam divergir por transporte
estação	o lado distante: station/bash/, plantado em um repositório de transporte privado. Bash 4+, git e GNU coreutils. Sem pacotes, sem credenciais, sem túnel

Nada é jamais instalado no lado distante. A estação é texto simples que você pode ler antes de executar — bash 4+, ou PowerShell 5.1 para um ambiente Windows que não tem bash e não receberá nenhum — e nenhum Go aparecerá sob station/ além do único arquivo que permite à CLI carregar o payload. A CI impõe isso. Essa restrição é toda a proposta em uma máquina bloqueada onde instalar qualquer coisa é, por si só, uma solicitação de mudança.

Instalação

# Linux and macOS, from a release
curl -sSL https://github.com/dbhq-uk/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/dbhq-uk/heliograph/cmd/heliograph@latest

Um único binário estático, sem runtime. Checksums são publicados a cada lançamento, e o binário carrega o payload da estação com o qual foi compilado.

A habilidade do agente — o mesmo loop, conduzido pelo Claude Code, Codex, Cursor e afins:

/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 dbhq-uk/heliograph       # any agent, via skills.sh

Uso

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

Todo o trabalho do operador é o que plant imprime: clonar o repositório de transporte, executar ./start.sh, e ir embora. O loop é somente leitura, a menos que o operador diga o contrário: cada etapa se declara (# heliograph-mode: read-only ou action), uma que não declare nenhum dos dois não é executada, e a estação recusa uma ação a menos que tenha sido iniciada com --allow-actions. Ela também não será executada como root.

Para um agente, heliograph mcp é a mesma CLI que ferramentas MCP digitadas:

claude mcp add heliograph -- heliograph mcp

Os portões não se movem. Uma chamada de ferramenta publica uma solicitação; a estação ainda decide se a executa.

--gaps é a que vale a pena conhecer. "Examine a coluna de timestamps em busca de lacunas antes de ler o conteúdo" é a instrução mais valiosa do método, e é aritmética:

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

A lacuna pertence à linha anterior a ela: o carimbo em uma linha indica quando essa linha foi produzida, então um intervalo longo significa que a operação nomeada na linha precedente é a que levou o tempo. Um log em que cada linha carrega o mesmo timestamp é relatado como erro, não como "sem lacunas".

Status

CLI de controle sobre git	funciona, testado de ponta a ponta contra uma estação padrão
heliograph bootstrap	funciona: o binário planta a estação com a qual foi compilado
--gaps	funciona
Servidor MCP (heliograph mcp)	funciona
estação bash	em uso via git: o loop, os portões, a captura, hosts Azure, Kubernetes, o launcher Windows
relay	meio transporte. O lado da estação está escrito e completo — ele busca solicitações, publica status e entrega o log finalizado — e o servidor relay está implantado. Nenhum comando CLI pode selecioná-lo
compartilhamento de arquivos, pacote, armazenamento de objetos	somente lado de controle. A CLI implementa os três; a estação não tem transporte para nenhum deles
Azure Blob	funciona de ponta a ponta, através de drop.sh no payload da estação, não na CLI. É o que o host da Azure Function usa
estação PowerShell	planejada: A8
site de documentação	heliograph.dbhq.uk: a CLI, os transportes e o lado distante — a estação, o runner, etapas, hosts, Azure, Windows, contêineres, serviços, segredos, segurança e o contrato de captura

Um transporte que funciona em um lado da lacuna não é um transporte, então esta tabela nomeia ambos os lados. Git é o que a CLI conduz de ponta a ponta; o que os outros ainda precisam, e em que ordem, está em o roadmap.

O relay

Ambos os lados fazem chamadas de saída por HTTPS comum, então um ambiente não precisa de host git, conta de armazenamento ou VNet. Hospedado e auto-hospedável a partir do mesmo binário.

Ainda não utilizável de ponta a ponta. O lado da estação está completo e o servidor está implantado; nenhum comando CLI pode selecioná-lo, então o lado próximo é a metade que falta.

O relay não pode ler seus logs e não pode fazer uma estação executar nada. Essa segunda metade é a que importa: um relay capaz de forjar uma solicitação seria execução de código dentro de todos os ambientes ao mesmo tempo. O conteúdo é criptografado de ponta a ponta com chaves que o relay nunca detém, e cada mensagem é assinada. Nada personalizado — primitivas age mais Ed25519. O relato completo, incluindo o que a DBHQ pode e não pode honestamente afirmar, está em docs/specs/2026-09-06-relay-encryption-design.md. O servidor relay é seu próprio repositório, dbhq-uk/heliograph-relay, porque ele não detém chaves e deve ser publicamente, obviamente incapaz de ler qualquer coisa que carrega.

O que ele não fará

Dar a você acesso que você não tem. Ele não cria túnel, não faz proxy e não mantém uma conexão aberta com um host que você controla, e não há nada aqui para furar um firewall. Um transporte TCP bruto foi considerado e descartado exatamente por esse motivo: uma conexão reversa persistente é um canal C2 pela definição de qualquer time azul, e essa frase é uma grande parte do motivo pelo qual essa classe de ferramenta é permitida em ambientes regulados.

Cada comando é executado no lado distante porque alguém com acesso legítimo escolheu executá-lo.

Layout

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 code

As duas metades costumavam ser repositórios separados, divididos entre Go-versus-bash em vez de ao longo da lacuna, e cada leitor tinha que descobrir em qual metade estava olhando. dbhq-uk/heliograph-skill foi mesclado em 2026-09-08 com seu histórico completo; o raciocínio está em docs/specs/2026-09-08-station-and-skill-merge.md.

Desenvolvimento

PLAN.md é onde o trabalho está: o que foi entregue, o que vem a seguir e quais defeitos são conhecidos e não corrigidos. CONTRIBUTING.md cobre como trabalhar nele e AGENTS.md é para um agente de IA fazendo isso. A habilidade é skills/heliograph/SKILL.md; docs/dev-setup.md a configura a partir do código-fonte com edições ao vivo.

Licença

MIT (c) 2026 DBHQ Consulting Ltd