hips/HIPs/hip-0117-cloud-in-a-box.md

hip, title, author, type, category, status, implementation-go, created, updated, requires

hip	title	author	type	category	status	implementation-go	created	updated	requires
0117	Cloud-in-a-Box — One Binary, Three Modes	Hanzo AI Team	Standards Track	Infrastructure	Final	partial	2026-07-07	2026-07-08	HIP-0036, HIP-0106, HIP-0400

HIP-0117: Cloud-in-a-Box — One Binary, Three Modes

Abstract

This proposal defines the three deployment topologies of the ONE cloud binary (HIP-0106) — from a laptop to an HA cluster without changing the artifact:

1. cloud serve — single process, no Kubernetes: every subsystem in-process, per-tenant SQLite, datastore as a subprocess or gracefully absent. The true cloud-in-a-box for laptop, edge, and single-node installs.
2. cloud cluster init — the binary fetches k3s (it does NOT embed it), bootstraps a Kubernetes cluster, installs the operator, and hands reconciliation to services.hanzo.ai CRs (HIP-0400). Single command from bare metal to HA.
3. helm install — bring your own Kubernetes: the charts at cloud/helm/cloud deploy the same image into an existing cluster.

The mode is topology, not identity: same bits, same config surface, same product behavior. What runs is decided by HIP-0106 (plugins / enabled subsystems); where it runs is decided here — and nowhere else.

Motivation

An OSS AI cloud must install like a tool, not like a platform team. The competition for the first five minutes is docker run and curl | sh, not a 40-page Helm values reference. At the same time the production shape is an operator-reconciled Kubernetes estate (HIP-0400 CRs, HIP-0036 CI/CD). Historically these were different software: a "dev mode" binary and a "real" set of manifests that drifted apart.

HIP-0106 removed the reason for that split. The unified binary already runs every subsystem in one process against SQLite; Kubernetes adds scale-out and self-healing, not features. So the deployment story collapses to one artifact with three entry points, and the only real design question left is: does the binary embed the orchestrator?

The answer is no. Embedding k3s into cloud was considered and rejected:

• App ≠ orchestrator. k3s is a cluster lifecycle concern with its own release cadence, CVE stream, and kernel-facing surface. Baking it into the app binary conflates two lifecycles that must upgrade independently.
• Bloat. The one-binary measured ~303.6 MiB (HIP-0106 realized state); a k3s payload roughly triples it for a code path most deployments never execute.
• Precedent. k3sup and Coder ship exactly this shape — a binary that fetches and bootstraps the orchestrator on demand — and it is the right separation: the app binary orchestrates the bootstrap; it is not the orchestrator.

Specification

Mode 1 — cloud serve (single process, no Kubernetes)

The binary IS the cloud:

• All enabled subsystems mount in-process per HIP-0106 (registry + fail-closed embeds). Disabled-by-default activation and 503 blast-radius isolation apply unchanged.
• Storage is per-tenant SQLite (HIP-1104, HIP-0302) under --data-dir. No external database exists in this mode — SQLite is the default, not the fallback.
• datastore (columnar analytics store; the one non-Go exception per HIP-0106) runs as a locally supervised subprocess when present. When absent, analytics-dependent surfaces degrade fail-closed (503 on their prefixes) while everything else serves — the same isolation rule as any broken subsystem.
• The IAM single-replica guard (HIP-0106 realized state) is trivially satisfied: there is exactly one replica.
• Consensus/replication state per HIP-0106 runs in its single-node, in-memory shape: instant finality, zero configuration.

This mode is shipped: it is cloud.Serve — the same entry the SaaS runs — pointed at local storage. Edge and laptop installs are not a port; they are a smaller instance of production.

Mode 2 — cloud cluster init (the binary bootstraps its own cluster)

For bare metal / VM fleets with no existing Kubernetes:

1. Fetch k3s. The binary downloads a pinned k3s release and verifies its checksum before executing anything. The pin lives in the cloud release, so cloud version N always bootstraps a known orchestrator version — reproducible clusters, no latest.
2. Bootstrap. Install/start k3s (server on the first node; cluster join adds agents), write the kubeconfig.
3. Install the operator. Apply hanzoai/operator and the services.hanzo.ai CRDs (HIP-0400 family).
4. Reconcile. Apply the deployment's CRs; the operator pulls ghcr.io/hanzoai/<service> images (built by HIP-0036 lanes), creates the datastore as a StatefulSet, and converges the estate. From here on, day-2 is GitOps against CRs — cluster init is a bootstrapper, not a parallel management plane.

HA and scale-out are properties of this mode: multiple nodes, replica counts on CRs, and the durable Quasar/ZapDB substrate shape from HIP-0106.

Airgapped variant: an optional cloud-fat build go:embeds the pinned k3s binary for networks that cannot fetch. It is a separate build target, never the default — the default binary never carries an orchestrator. This is the ONLY sanctioned embedding of k3s.

Status: decided; staged behind the SaaS-first cutover. The operator, CRDs, and images it composes all exist and run production today (HIP-0400, HIP-0036); cluster init sequences them from the binary.

Mode 3 — helm install (bring your own Kubernetes)

For teams that already operate Kubernetes:

helm install cloud ./helm/cloud   # charts at hanzoai/cloud helm/cloud

The chart deploys the same ghcr.io/hanzoai/cloud image with the same config surface (--enable / CLOUD_* per HIP-0106) and pins replicas=1 while the embedded IAM is enabled (the session single-replica guard). BYO ingress-controller integration follows the edge routing standard of HIP-0068. Shipped: the chart exists in-tree at cloud/helm/cloud.

Mode invariants

• One artifact. All three modes run the identical binary/image. A mode is a command-line entry point, never a fork or a build flag (the cloud-fat airgap variant differs only by the embedded k3s payload, not by application code).
• One config surface. Enabled subsystems, brand, domain, IAM issuer, and data dir mean the same thing in every mode.
• Same product in every mode. Per-product metering and balance-floor gating (HIP-0106 realized state; HIP-0018) apply identically — a single-node install bills like the SaaS.
• Graduation is data motion, not migration. serve → cluster is: stand up the cluster, replicate the SQLite/ZapDB state (HIP-0107 / HIP-0302), repoint DNS. No schema rewrite, no "export".

References

• HIP-0106 — Cloud — Unified Hanzo Binary (the artifact all three modes run and the product surface it serves; realized state documents cloud.Serve, the embeds, and the measured binary)
• HIP-0106 — Hanzo Plugin & VM Model (what runs: plugins/subsystems + the single-node vs HA state substrate)
• HIP-0400 — Service CRD (the operator/CR family cluster init installs and defers to)
• HIP-0036 — CI/CD Build System Standard (the lanes that build the images the operator pulls)
• HIP-0068 — Ingress Standard (the edge routing shape Mode 2/3 converge to)
• HIP-0107 / HIP-0302 — replication used for serve→cluster graduation concern)
• k3sup, Coder — prior art for fetch-on-bootstrap orchestrator installation