heliograph

---

Alguien puede llegar a la máquina. Tú no puedes, y eres quien sabe qué preguntarle. heliograph recorre esa brecha como un bucle, no como un relevo: publicas un paso, se ejecuta en el otro lado, y toda la ejecución regresa como un registro con cada línea con marca de tiempo en UTC, ya sea que haya pasado o fallado.

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

¿Te resulta familiar?

• No tienes acceso SSH a producción, y no te lo van a dar.
• El entorno está aislado, o detrás de un bastión, un host de salto o una VPN a la que no estás conectado.
• Es un entorno propiedad del cliente o gestionado por el cliente. Solo su personal puede iniciar sesión.
• El acceso está bloqueado por política, no por capacidad: regulado, restringido, controlado por cambios.
• Estás en la cuarta ronda de "¿puedes ejecutar esto y pegar la salida?", y lo que devolvieron fue una captura de pantalla de medio terminal.
• Eres un agente de codificación de IA que dirige una investigación y necesitas la evidencia, no el resumen de alguien.

Si puedes simplemente conectarte por SSH, no necesitas esto.

Tres roles, un límite

El límite es la brecha, y el diseño lo establece una vez:

control	tu máquina: la CLI de heliograph, heliograph mcp y la habilidad que los impulsa. Go, y lo que el lado cercano pueda permitirse
transporte	el canal: git, relevo, recurso compartido de archivos, paquete, almacén de objetos: todo detrás de una interfaz, para que las puertas de solo lectura vivan en un solo lugar y no puedan desviarse por transporte
estación	el lado lejano: station/bash/, plantado en un repositorio de transporte privado. Bash 4+, git y GNU coreutils. Sin paquetes, sin credenciales, sin túnel

Nunca se instala nada en el lado lejano. La estación es texto plano que puedes leer antes de ejecutar: bash 4+, o PowerShell 5.1 para un entorno Windows que no tiene bash y no se le dará ninguno, y ningún Go aparecerá jamás bajo station/ más allá del único archivo que permite que la CLI transporte la carga útil. CI lo hace cumplir. Esa restricción es toda la propuesta en una caja bloqueada donde instalar cualquier cosa es su propia solicitud de cambio.

Instalación

# 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

Un único binario estático, sin tiempo de ejecución. Los checksums se publican con cada versión, y el binario lleva la carga útil de la estación con la que fue construido.

La habilidad del agente: el mismo bucle, impulsado desde Claude Code, Codex, Cursor y similares:

/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 el trabajo del operador es lo que plant imprime: clonar el repositorio de transporte, ejecutar ./start.sh, alejarse. El bucle es de solo lectura a menos que el operador haya dicho lo contrario: cada paso se declara a sí mismo (# heliograph-mode: read-only o action), uno que no declara ninguno no se ejecuta, y la estación rechaza una acción a menos que se haya iniciado con --allow-actions. Tampoco se ejecutará como root.

Para un agente, heliograph mcp es la misma CLI que las herramientas MCP escritas:

claude mcp add heliograph -- heliograph mcp

Las puertas no se mueven. Una llamada a una herramienta publica una solicitud; la estación aún decide si ejecutarla.

--gaps es la que vale la pena conocer. "Escanea la columna de marcas de tiempo en busca de brechas antes de leer el contenido" es la instrucción más valiosa del método, y es 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...

La brecha pertenece a la línea anterior: la marca en una línea es cuando esa línea se produjo, por lo que un intervalo largo significa que la operación nombrada en la línea anterior es la que tomó el tiempo. Un registro donde cada línea lleva la misma marca de tiempo se informa como un error, no como "sin brechas".

Estado

CLI de control sobre git	funciona, probado de extremo a extremo contra una estación estándar
heliograph bootstrap	funciona: el binario planta la estación con la que fue construido
--gaps	funciona
Servidor MCP (heliograph mcp)	funciona
estación bash	en uso sobre git: el bucle, las puertas, la captura, hosts de Azure, Kubernetes, el lanzador de Windows
relevo	medio transporte. El lado de la estación está escrito y completo: obtiene solicitudes, publica estado y entrega el registro terminado, y el servidor de relevo está desplegado. Ningún comando de CLI puede seleccionarlo
recurso compartido de archivos, paquete, almacén de objetos	solo lado de control. La CLI implementa los tres; la estación no tiene transporte para ninguno de ellos
Azure Blob	funciona de extremo a extremo, a través de drop.sh en la carga útil de la estación en lugar de la CLI. Es lo que usa el host de Azure Function
estación PowerShell	planificada: A8
sitio de documentación	heliograph.dbhq.uk: la CLI, los transportes y el lado lejano: la estación, el ejecutor, los pasos, los hosts, Azure, Windows, contenedores, servicios, secretos, seguridad y el contrato de captura

Un transporte que funciona en un lado de la brecha no es un transporte, por lo que esta tabla nombra ambos lados. Git es el que la CLI impulsa de extremo a extremo; lo que los demás aún necesitan, y en qué orden, está en la hoja de ruta.

El relevo

Ambos lados se conectan hacia afuera a través de HTTPS ordinario, por lo que un entorno no necesita un host de git, ni una cuenta de almacenamiento ni una VNet. Alojado, y autoalojable desde el mismo binario.

Aún no utilizable de extremo a extremo. El lado de la estación está completo y el servidor está desplegado; ningún comando de CLI puede seleccionarlo, por lo que el lado cercano es la mitad que falta.

El relevo no puede leer tus registros, ni puede hacer que una estación ejecute nada. Esa segunda mitad es la que importa: un relevo capaz de falsificar una solicitud sería ejecución de código dentro de cada entorno a la vez. El contenido está cifrado de extremo a extremo con claves que el relevo nunca posee, y cada mensaje está firmado. Nada personalizado: age primitivas más Ed25519. El relato completo, incluido lo que DBHQ puede y no puede afirmar honestamente, está en docs/specs/2026-09-06-relay-encryption-design.md. El servidor de relevo es su propio repositorio, dbhq-uk/heliograph-relay, porque no posee claves y debe ser pública y obviamente incapaz de leer cualquier cosa que transporte.

Lo que no hará

Darte acceso que no tienes. No hace túneles, no actúa como proxy ni mantiene una conexión abierta a un host que controlas, y no hay nada aquí para perforar un firewall. Se consideró un transporte TCP crudo y se descartó precisamente por esa razón: una conexión inversa persistente es un canal C2 según la definición de cualquier equipo azul, y esa frase es una gran parte de por qué esta clase de herramienta está permitida en entornos regulados.

Cada comando se ejecuta en el lado lejano porque alguien con acceso legítimo eligió ejecutarlo.

Diseño

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

Las dos mitades solían ser repositorios separados, divididos a lo largo de Go-versus-bash en lugar de a lo largo de la brecha, y cada lector tenía que averiguar qué mitad estaba mirando. dbhq-uk/heliograph-skill se fusionó el 2026-09-08 con su historial completo; el razonamiento está en docs/specs/2026-09-08-station-and-skill-merge.md.

Desarrollo

PLAN.md es donde está el trabajo: qué ha aterrizado, qué sigue, y qué defectos son conocidos y sin corregir. CONTRIBUTING.md cubre cómo trabajar en ello y AGENTS.md es para un agente de IA que lo haga. La habilidad es skills/heliograph/SKILL.md; docs/dev-setup.md la configura desde el código fuente con ediciones en vivo.

Licencia

MIT (c) 2026 DBHQ Consulting Ltd