Documentation

Three programs, one pipeline.

A sentence in Discord becomes a tested Rails repository and a running demo. Three codebases do that work, and each is documented here: what it is, how it is built, and how the code actually behaves.

01 / THE AGENT

Vela

A Go agent on a credit-card-sized RISC-V board. Plans, writes code, and signs what it ships.

02 / THE STAGE

Holodex

A single Go binary that verifies signed source, builds it, and hosts it in a boxed-in container.

03 / THE FOUNDATION

Rails Foundation

The MIT Rails 8.1 template every generated application starts from.

The pipeline end to end

Nothing here trusts the previous step's word for it. Each stage hands the next a value it can verify on its own.

01 · REQUESTSomeone describes an app. Vela writes a concrete plan and waits for approval.

02 · GENERATEA repository is created from the Rails foundation, private, then given its own identity.

03 · VERIFYHolodex builds the Docker test stage. Passing returns a receipt bound to that exact archive.

04 · DEPLOYOnly bytes matching the receipt are deployed, into a container with no internet egress.

What each boundary actually checks

Boundary	Mechanism	What it prevents
Vela → Holodex	HMAC-SHA256 over canonical metadata plus the raw archive, in `X-Holodex-Sign`	Anyone but Vela's own pipeline deploying, or a signed archive being replayed with a different name, port, or Dockerfile
Verify → deploy	One-hour receipt bound to the archive's SHA-256 digest and the `test` target	Deploying source that never passed its tests, or swapping bytes after they passed
App → internet	Internal Docker network, no egress at runtime	A running demo reaching the network; dependencies are fetched at build time only
App → host	`cap-drop ALL`, `no-new-privileges`, memory/CPU/PID caps	A build or app escaping its box on a machine that also runs production workloads

Why it is shaped this way

The constraint that set the architecture is the hardware. Vela runs on a LicheeRV Nano: a single RISC-V core and 256 MB of RAM, powered from a USB port. That board cannot bundle a Rails app, run a PostgreSQL test suite, or build a Docker image. So the work is split by what each machine is good at.

The board holds the conversation, the judgement, and the credentials. It never sends its GitHub token anywhere. Holodex runs on a rented server with real CPU and disk, and it is deliberately incurious: it verifies a signature, builds a container, and serves it. The foundation is where the actual product engineering lives, so a generated app is production-shaped from its first commit rather than something to harden later.

A demo is not a deployment. Every app on Holodex is deleted at the daily wipe, and the GitHub repository is the permanent copy. Preview URLs are unlisted, not access-controlled: responses carry X-Robots-Tag: noindex, which keeps them out of search results and nothing more.

Repositories

All three are public and MIT licensed.

novaoc/vela ↗ novaoc/holodex ↗ novaoc/vela-foundation ↗