Skip to main content
The StackKit Open Spec is the thin, published contract behind “the open homelab standard”. It indexes artifacts that ship with every StackKits release; it introduces no new schema. The spec version follows the release tag it ships with, and changes within v0 are additive. The canonical copy lives in the public repository at docs/OPEN-SPEC.md. Everything in the spec is account-free: Standard Mode needs no kombify account, no hosted kombify endpoint, and no Techstack.

​
1. Architecture snapshot

The facts-only architecture snapshot describes a release: kits, topology, capabilities, placement model, modules, add-ons, and support maturity. CUE is the technical source of truth; the snapshot is a projection of it. A consumer reads the snapshot, never the CUE, and must tolerate additive fields.

​
2. Lifecycle verbs

Every kit is driven by the same verbs through the stackkit CLI and the stackkit-mcp connector. Inputs and outputs are documented in the CLI reference and the CLI walkthrough. A verb either completes with evidence or fails with a terminal reason. It never reports success for work it did not do.

​
3. Placement taxonomy

Placement describes where a kit or module may run. The vocabulary is published in foundation/placement.cue:
  • #PlacementMode: local-only, standard, managed-serverless
  • #PlacementSupport: per-module eligibility metadata (which modes a module can run in)
The open-source lifecycle realizes local-only and standard. managed-serverless is eligibility metadata only; its realization is outside StackKits and outside this spec.

​
4. Verification evidence

Maturity words are evidence-backed, never declared. The evidence shapes are public JSON Schemas; the release ships the instances. Vocabulary:
  • Kits: supported (a cited verification path exists for the committed cell), preview (installs, but verification or recovery evidence is pending), alpha (definition only).
  • Compatibility rows (operating systems, hypervisors, kits by environment, applications): supported (every lifecycle phase passed in the newest run on the evidence release), preview (install through verify passed; a later phase failed) or unverified (no completed run on that release yet, or the newest run failed before verify). Absence of evidence is published as unverified, never as support.
  • A status widens only when a cited run exists for the exact release.

​
5. Conformance

A tool or service is StackKit-compatible when it
  1. consumes the architecture snapshot of the exact release it targets,
  2. drives kits only through the lifecycle verbs above (directly or through the MCP connector) and preserves their evidence,
  3. describes placement with the published taxonomy, and
  4. publishes verification results in the evidence shapes above with the release tag they belong to.

​
Status

This is a v0 draft published with the public beta. A separate specification repository with a versioning policy follows after the beta; until then the repository document and the linked artifacts are the spec.