Project notes
kylebegeman/helios
Helios
One small program that runs your machines: builds, certificates, secrets, backups, health checks, and alerts from a single static binary.
Repository snapshot
- 517Commits
- Nov 2026Last updated
- Apache-2.0License
- Apr 2026Started
- Go 92.7%
- Shell 3.9%
- Python 3.4%
Recent commits
- Document the 0.7.26 patch: a quiet machine's tested alert legs and moved apps no longer read as broken
- fix(peer): a quiet machine's tested alert legs and moved apps no longer read as broken
- fix(workloads): support per-workload DNS resolvers
- Merge fix/docker-address-pools: Docker gets address pools for more than 31 networks
Overview
Helios installs and operates a whole machine from one static Go binary, with no agent, runtime, or hosted control plane underneath. Each app describes itself in a helios.yaml, and everything follows from that file: DNS records, certificates, secrets, data services, health checks, backups, and alerts. Containers are isolated by default, backups are proven by scheduled restore drills, and a git push deploys with every step streamed back. It is the Go rewrite of Ophelia, and it runs my own production machine.
Highlights
- 01
One binary
A static Go binary installs and operates the machine. There is no agent to babysit, no runtime to keep current, and no control plane to pay for.
- 02
The manifest is the interface
helios.yaml declares workloads, routes, secrets, data, backups, and checks, and helios init writes a validated starting file for each kind of app.
- 03
Isolated by default
Read-only root, no Linux capabilities, no privilege escalation, a non-root user, and a private network per app, with helios exposure to show what each container got.
- 04
Deploys without a pipeline
git push deploys and streams every step back. A failed deploy refuses the push, and the previous revision stays ready for rollback.
- 05
Backups that restore
Consistent, encrypted restic snapshots per app, restored beside the app, started, and verified by scheduled drills.
- 06
Plans you approve
Every machine operation can show its plan first and then apply only that exact plan, named by its digest, so a person or an agent approves what runs.
What it runs
Documentation & getting started
helios host setup # prepare a fresh Ubuntu or Debian machine
helios integration set cloudflare # DNS records for your hosts
helios integration set storage # an S3 store, for backups
helios init my-app --host app.example.com
helios deploy . # build, check, switch the edge
helios status # health, traffic, errors, backups
- Quick startPrepare a machine, write a manifest, and deploy.
- The manifesthelios.yaml in full, from one workload to many.
- IsolationWhat every container gets by default, and the ways out.
- Deploysgit push, launches, previews, and moves between machines.
- BackupsConsistent captures, restic, and scheduled restore drills.
- The laneHow features are proven on a server wiped and rebuilt for each one.