Heyo Web Services

Heyo Web Services

Heyo Web Services (HWS) is an open-source stack for running your own cloud on your own hardware: microVM workloads behind a load balancer and autoscaler, plus the secrets, observability, artifact, CI, database and queue services an application needs around them.

HWS is shaped like the platforms agents already know — deployments, replicas, routes, secrets, namespaces, tokens — but every piece is a single binary you run on hosts you control. Workloads are Firecracker or KVM microVMs (or Incus containers) whose images you build from a Dockerfile, managed by heyvm. HWS adds everything above the VM.

Components

Component What it does Page
app-lb The edge and control plane. A Pingora-based HTTP/HTTPS proxy that routes by host and path to autoscaled microVM pools, fixed upstreams or static sites. Runs the admin API and dashboard for deployments, secrets, builds, artifact pulls, host updates, ACME certificates, disk reclamation and fleet views, and a built-in SIEM with block rules. app-lb
Authentication app-lb protects its admin API (Basic auth, scoped applb_… app-tokens, federated Heyo bearers) and puts an optional sign-in gate in front of each deployment (Google, app-token or JWT/OIDC). Authentication
heyctl A kubectl-style CLI and Rust client library for the app-lb admin API, with named contexts for switching between fleets. heyctl
Orchestrator The Postgres-backed record of what should run where. Provisions CI sandboxes, deploys services (blue/green or rolling), publishes the discovery sets app-lb routes from, and runs durable region-by-region rollouts. Orchestrator
app-obs Collects console and application logs from each VM, accepts pushed logs over HTTP and syslog, polls app-lb's metrics, stores it all as compacted Parquet with retention, and serves a query API, dashboard and webhook alerts. app-obs
Artifacts (art) A content-addressed blob store tuned for ext4: VM images stored sparsely, site bundles, build inputs, workspace snapshots and release binaries, served by the art CLI and art serve. Artifacts
HeyoSecret A single-tenant store of versioned, AES-256-GCM-encrypted secrets in Postgres, with a bearer-authenticated machine API and an optional dashboard. HeyoSecret
pg-fc Postgres with one Firecracker microVM per database behind a single wire-protocol pooler on :6432. Idle databases stop; cold ones move down storage tiers and come back on the next connect. pg-fc
Queue A read-only dashboard over a NATS JetStream server, plus recipes for running NATS itself as a managed microVM. Queue
ci Plans GitHub-Actions-shaped workflow files into jobs, queues them on NATS JetStream with Postgres as the source of truth, and runs each job in a fresh microVM on your runner hosts. Code arrives through git submit. ci
MCP server heyo-mcp gives coding agents tools for sandboxes, deployments, logs, metrics, CI runs and artifacts, over stdio or hosted behind app-lb. MCP server
Developer tools printer (a spec-driven code factory), codegraph (tree-sitter code index and patching) and computer (Linux desktop automation), with plugins and agent skills. Developer tools

How the pieces fit

                        clients / browsers / agents
                                   │
                                   ▼
   heyctl ──admin API──▶  app-lb  (routing · TLS · sign-in gates · SIEM · autoscaler)
   heyo-mcp ───────────▶    │  ▲                 │
                            │  │ metrics         │ creates / stops VMs
                            │  └──── app-obs ◀───┤ console + app logs
                            ▼                    ▼
                  microVM pools, upstreams,    heyvmd on each host
                  static sites                 (Firecracker · KVM · Incus)
                            ▲
                            │ images, workspaces, site bundles
                           art  ◀── ci (builds, artifacts) ◀── git submit
                                     │
                                     └── NATS JetStream (queue) · Postgres
   heyosecret ── secrets for ci and orchestrator
   orchestrator ── discovery sets and regional rollouts consumed by app-lb
   pg-fc ── databases as microVMs, reached by apps on :6432

A request arrives at app-lb, which matches a route, checks the deployment's sign-in gate and block rules, and forwards to the least-busy replica. If the pool is scaled to zero, app-lb asks the host's heyvm daemon to boot a VM and holds the request until it is healthy.

A deployment is a JSON spec registered with app-lb (with heyctl apply, the admin API, or the MCP server). A build block builds its image from a Dockerfile on the host; a workspace block restores and snapshots its data through art; env_from injects secrets from app-lb's secret store.

ci turns a git submit into jobs, boots a microVM per job, and uploads what the job produces to art. The release workflows in this repository publish every HWS binary that way, and installation installs them back out.

app-obs follows every VM's logs and scrapes app-lb's metrics, so a deployment's logs, latency and errors are queryable without any change to the application.

Where to start

  • Installation — stand up a host and register a first deployment.
  • app-lb — the deployment spec, scaling and the admin API.
  • heyctl — drive a fleet from the command line.
  • MCP server — let an agent deploy and debug for you.
  • Multi-region — run one platform across regions.
  • Contributing — build and test the repository.