README
¶
StackKits
StackKits is an open-source infrastructure blueprint system for self-hosted homelab and small-server deployments. Standalone Docker Compose is the complete primary experience, including applications. Standard Mode runs independently, without a Kombify account, Techstack, Coolify, or Komodo.
The CLI is an optional user-facing interface to the same governed lifecycle, not a separate full edition. Komodo and Coolify are explicit opt-in integrations. Development proceeds from complete standalone Compose to Komodo, then Coolify; Dokploy remains draft. Existing explicit platform selections are preserved. See the standalone decision for the contract and the separate runtime-evidence requirements.
Install
Basement Kit — local / homelab:
curl -sSL https://base.stackkit.cc | sh
Cloud Kit — cloud VM / BYO-VPS:
curl -sSL https://cloud.stackkit.cc | sh
Modern Homelab — combined Home + Cloud topology (alpha definition archive, not an install target yet):
curl -sSL https://install.stackkit.cc | sh
stackkit init modern-homelab --non-interactive --name my-modern-homelab
The Modern archive and catalog entry prove self-contained native-v2 authoring and validation. They do not claim that every federation runtime owner is graduated.
For the CLI plus the public kit catalog (two install paths plus the Modern
alpha definition), use the same install.stackkit.cc installer and select the
desired kit with stackkit init.
| Kit | Target | Status |
|---|---|---|
| Basement Kit | an existing Linux host at home | supported one-command path |
| Cloud Kit | an existing VPS with your own domain | preview |
| Modern Homelab | Home + Cloud, joined by an explicit federation bridge | alpha definition archive |
A published release is source and distribution evidence, not runtime
acceptance. Each release ships release-evidence.json; kit and use-case
runtime evidence is summarized on https://stackkit.cc and a status only
widens when a cited run exists.
Website, docs and community
- Product site and installers: https://stackkit.cc
- Documentation: https://docs.kombify.io/stackkits
- The StackKit Open Spec (architecture snapshot, lifecycle verbs, placement taxonomy, verification evidence): docs/OPEN-SPEC.md
- Support: see SUPPORT.md. Questions and ideas go to GitHub
Discussions on this repository, bugs to the issue templates, vulnerabilities
to GitHub Security Advisories (see
SECURITY.md). This repository is a generated release mirror; contributions are ported upstream by maintainers (seeCONTRIBUTING.md) - How the project is built, including the AI-assisted development provenance: docs/BUILT-WITH.md
Works with agents
StackKits is agent-native without depending on any AI service. The CLI embeds
the stackkit-mcp connector and the prompt Markdown; llms.txt, OpenAPI and
the JSON schemas are published on https://stackkit.cc for every release:
stackkit agent mcp-config --client codex # or claude / generic
stackkit agent prompt --list
Documentation
Source Of Truth
CUE files are the technical source of truth for schemas, defaults, constraints, module contracts, and kit composition. Generated OpenTofu, Compose, tfvars, state, and rollout snapshots are build output.
The Architecture v2 contract proof
reproducibly binds a two-node Basement topology, named runtime daemons,
provider/consumer interfaces, runtime networks, and an approved direct-socket
exception through the compiler and renderer contract. It uses a separate
contract-only catalog and is explicitly ineligible for product graduation.
Validate the committed hashes and catalog boundary with
node scripts/release/validate-architecture-contract-fixture.mjs --repo-root ..
License
Apache-2.0 OR GPL-3.0-or-later, at your option. See LICENSING.md and the complete Apache-2.0 and GPL-3.0 texts. The WebMCP package is Apache-2.0-only.
Directories
¶
| Path | Synopsis |
|---|---|
|
api
|
|
|
openapi
Package openapi provides embedded access to the kombify StackKits OpenAPI specification.
|
Package openapi provides embedded access to the kombify StackKits OpenAPI specification. |
|
cmd
|
|
|
gen-kit-templates
command
Command gen-kit-templates materializes the per-kit OpenTofu/Terramate template trees (basement-kit/templates/, cloud-kit/templates/) from the single canonical source in foundation/templates/.
|
Command gen-kit-templates materializes the per-kit OpenTofu/Terramate template trees (basement-kit/templates/, cloud-kit/templates/) from the single canonical source in foundation/templates/. |
|
stackkit
command
StackKit CLI - Infrastructure deployment from declarative blueprints
|
StackKit CLI - Infrastructure deployment from declarative blueprints |
|
stackkit-affected-tests
command
|
|
|
stackkit-mcp
command
|
|
|
stackkit-server
command
Package main provides the HTTP API server for kombify StackKits.
|
Package main provides the HTTP API server for kombify StackKits. |
|
stackkit/commands
Package commands implements the CLI commands for stackkit.
|
Package commands implements the CLI commands for stackkit. |
|
stackkit/user
Package user implements stackkit user add/list/remove for PocketID household members.
|
Package user implements stackkit user add/list/remove for PocketID household members. |
|
Package docs embeds public documentation for local agent surfaces.
|
Package docs embeds public documentation for local agent surfaces. |
|
data/os-compat
Package oscompat embeds only the public OS compatibility evidence consumed by the standalone CLI.
|
Package oscompat embeds only the public OS compatibility evidence consumed by the standalone CLI. |
|
internal
|
|
|
actionableerror
Package actionableerror owns the stable CLI/MCP recovery guidance envelope.
|
Package actionableerror owns the stable CLI/MCP recovery guidance envelope. |
|
advancedcapability
Package advancedcapability verifies the short-lived, secret-free capabilities which authorize individual StackKits advanced operations.
|
Package advancedcapability verifies the short-lived, secret-free capabilities which authorize individual StackKits advanced operations. |
|
advancedchangeset
Package advancedchangeset owns the immutable, owner-signed description of one already-rendered advanced change.
|
Package advancedchangeset owns the immutable, owner-signed description of one already-rendered advanced change. |
|
advancedtrust
Package advancedtrust imports and owns the local, Owner-approved trust roots used by offline Advanced capability verification.
|
Package advancedtrust imports and owns the local, Owner-approved trust roots used by offline Advanced capability verification. |
|
agentsurface/cmd/gen
command
|
|
|
api
Package api provides the HTTP API server for kombify StackKits.
|
Package api provides the HTTP API server for kombify StackKits. |
|
applicationlifecycle
Package applicationlifecycle persists the resumable state of every selected Application Kit.
|
Package applicationlifecycle persists the resumable state of every selected Application Kit. |
|
apply
Package apply orchestrates post-deployment bootstrap of identity resources.
|
Package apply orchestrates post-deployment bootstrap of identity resources. |
|
applyevidencev2
Package applyevidence defines the provider-neutral producer wire contract for StackKits Architecture-v2 pre-Apply evidence.
|
Package applyevidence defines the provider-neutral producer wire contract for StackKits Architecture-v2 pre-Apply evidence. |
|
applyledger
Package applyledger records what one Apply actually did, unit by unit.
|
Package applyledger records what one Apply actually did, unit by unit. |
|
applyoutcome
Package applyoutcome owns the StackKits failure-class taxonomy for local runtime execution.
|
Package applyoutcome owns the StackKits failure-class taxonomy for local runtime execution. |
|
architecturecontractproof
Package architecturecontractproof verifies the non-graduating public Architecture v2 contract fixture against the binary's embedded authority.
|
Package architecturecontractproof verifies the non-graduating public Architecture v2 contract fixture against the binary's embedded authority. |
|
architecturev2
Package architecturev2 is the single integration boundary from StackSpec documents to the governed Architecture v2 ResolvedPlan compiler.
|
Package architecturev2 is the single integration boundary from StackSpec documents to the governed Architecture v2 ResolvedPlan compiler. |
|
architecturev2/cmd/bundlegen
command
Command bundlegen builds the deterministic embedded Architecture v2 authority projection.
|
Command bundlegen builds the deterministic embedded Architecture v2 authority projection. |
|
architecturev2/internal/execution
Package execution owns the held-root installation transaction used by the Architecture v2 authority boundary.
|
Package execution owns the held-root installation transaction used by the Architecture v2 authority boundary. |
|
architecturev2renderer
Package architecturev2renderer renders only governed Architecture v2 ResolvedPlans.
|
Package architecturev2renderer renders only governed Architecture v2 ResolvedPlans. |
|
auth
Package auth provides shared authentication primitives for the stackkit CLI and supporting libraries.
|
Package auth provides shared authentication primitives for the stackkit CLI and supporting libraries. |
|
backupcustody
Package backupcustody owns the local Kopia repository passphrase without adding it to the Basement runtime-custody inventory.
|
Package backupcustody owns the local Kopia repository passphrase without adding it to the Basement runtime-custody inventory. |
|
backupexec
Package backupexec holds the Kopia backup engine primitives shared by the `stackkit backup` CLI and the node-local StackAction endpoints.
|
Package backupexec holds the Kopia backup engine primitives shared by the `stackkit backup` CLI and the node-local StackAction endpoints. |
|
backuphooks
Package backuphooks materializes its package-local database quiesce-hook contract (db-hooks.cue, embedded at build time) into the generated backup-hooks.json manifest, and gives the node-side backup engine a typed view of it.
|
Package backuphooks materializes its package-local database quiesce-hook contract (db-hooks.cue, embedded at build time) into the generated backup-hooks.json manifest, and gives the node-side backup engine a typed view of it. |
|
backuplifecycle
Package backuplifecycle owns the local, owner-authorized backup lifecycle journal while delegating repository mechanics to a narrow runtime boundary.
|
Package backuplifecycle owns the local, owner-authorized backup lifecycle journal while delegating repository mechanics to a narrow runtime boundary. |
|
backupplan
Package backupplan builds the non-secret recovery plan emitted by `stackkit generate`.
|
Package backupplan builds the non-secret recovery plan emitted by `stackkit generate`. |
|
clibinding
Package clibinding binds local process dispatch to an explicit StackKit CLI from one build.
|
Package clibinding binds local process dispatch to an explicit StackKit CLI from one build. |
|
cluster
Package cluster contains local cluster bootstrap primitives.
|
Package cluster contains local cluster bootstrap primitives. |
|
composition
Package composition resolves module dependencies and determines deployment order.
|
Package composition resolves module dependencies and determines deployment order. |
|
config
Package config handles configuration file parsing and management.
|
Package config handles configuration file parsing and management. |
|
confinedfs
Package confinedfs provides held-root, root-relative filesystem operations.
|
Package confinedfs provides held-root, root-relative filesystem operations. |
|
contractgen/stackactiongen
Package stackactiongen generates StackAction Go and OpenAPI projections from the canonical StackKits CUE authority.
|
Package stackactiongen generates StackAction Go and OpenAPI projections from the canonical StackKits CUE authority. |
|
contractgen/stackactiongen/cmd
command
|
|
|
crypto
Package crypto provides cryptographic helpers used by stackkit for password generation, hashing, and bundle encryption.
|
Package crypto provides cryptographic helpers used by stackkit for password generation, hashing, and bundle encryption. |
|
cue
Package cue provides CUE schema validation and Terraform bridge for StackKits.
|
Package cue provides CUE schema validation and Terraform bridge for StackKits. |
|
docker
Package docker provides Docker operations for StackKits.
|
Package docker provides Docker operations for StackKits. |
|
errors
Package errors provides standardized error handling for StackKit operations.
|
Package errors provides standardized error handling for StackKit operations. |
|
executionchannelbundle
Package executionchannelbundle verifies the short-lived, offline-authorized handoff into one exact StackKits execution channel.
|
Package executionchannelbundle verifies the short-lived, offline-authorized handoff into one exact StackKits execution channel. |
|
federationbinding
Package federationbinding owns account-free local admission of opaque, externally realized Federation-link bindings.
|
Package federationbinding owns account-free local admission of opaque, externally realized Federation-link bindings. |
|
federationcontrol
Package federationcontrol binds the existing StackKits server to Home-issued Federation actions.
|
Package federationcontrol binds the existing StackKits server to Home-issued Federation actions. |
|
generationartifact
Package generationartifact binds renderer outputs to one verified Architecture v2 ResolvedPlan.
|
Package generationartifact binds renderer outputs to one verified Architecture v2 ResolvedPlan. |
|
hostconformance
Package hostconformance produces StackKits-owned, provider-neutral evidence about the host on which the probe is running.
|
Package hostconformance produces StackKits-owned, provider-neutral evidence about the host on which the probe is running. |
|
hostpreflight
Package hostpreflight observes a target host and admits or refuses a local Apply before it mutates anything.
|
Package hostpreflight observes a target host and admits or refuses a local Apply before it mutates anything. |
|
iac
Package iac provides a unified interface for IaC execution.
|
Package iac provides a unified interface for IaC execution. |
|
identity
Package identity provisions PocketID owner and break-glass accounts.
|
Package identity provisions PocketID owner and break-glass accounts. |
|
identityprojection
Package identityprojection owns the credential-free desired identity projection accepted by a standalone StackKits installation.
|
Package identityprojection owns the credential-free desired identity projection accepted by a standalone StackKits installation. |
|
kitio
Package kitio imports Git-owned stackkit.yaml definitions and generates reviewable CUE, Terraform, Docker Compose, and YAML artifacts.
|
Package kitio imports Git-owned stackkit.yaml definitions and generates reviewable CUE, Terraform, Docker Compose, and YAML artifacts. |
|
kittemplates
Package kittemplates renders the per-kit OpenTofu/Terramate template trees from the single canonical source under foundation/templates/.
|
Package kittemplates renders the per-kit OpenTofu/Terramate template trees from the single canonical source under foundation/templates/. |
|
lifecyclemutation
Package lifecyclemutation owns the one local cross-process mutation authority shared by StackSpec authoring, generation, Apply, drift reconcile, and upgrade recovery.
|
Package lifecyclemutation owns the one local cross-process mutation authority shared by StackSpec authoring, generation, Apply, drift reconcile, and upgrade recovery. |
|
lint
Package lint implements `stackkit module lint` (ADR-0027 Decision 3, gates G1+G3): the deterministic module-hygiene checks that gate proposal PRs and tool-update PRs.
|
Package lint implements `stackkit module lint` (ADR-0027 Decision 3, gates G1+G3): the deterministic module-hygiene checks that gate proposal PRs and tool-update PRs. |
|
localbackuppolicy
Package localbackuppolicy owns the secret-free, generated contract between the Basement renderer and the native local backup lifecycle.
|
Package localbackuppolicy owns the secret-free, generated contract between the Basement renderer and the native local backup lifecycle. |
|
localbackupruntime
Package localbackupruntime adapts the owner-bound local backup lifecycle to the fixed Kopia container runtime without retaining repository secrets.
|
Package localbackupruntime adapts the owner-bound local backup lifecycle to the fixed Kopia container runtime without retaining repository secrets. |
|
localbackupschedule
Package localbackupschedule lowers the CUE-governed UTC backup cadence to a bounded pair of local systemd units.
|
Package localbackupschedule lowers the CUE-governed UTC backup cadence to a bounded pair of local systemd units. |
|
localevidence
Package localevidence produces Architecture-v2 pre-Apply evidence under the local homelab owner's own signing custody.
|
Package localevidence produces Architecture-v2 pre-Apply evidence under the local homelab owner's own signing custody. |
|
localorigin
Package localorigin realizes the node-local mTLS publication inside the existing StackKits server.
|
Package localorigin realizes the node-local mTLS publication inside the existing StackKits server. |
|
localowner
Package localowner realizes and verifies the init-owned human identity in the local PocketID runtime without exposing its bootstrap credential.
|
Package localowner realizes and verifies the init-owned human identity in the local PocketID runtime without exposing its bootstrap credential. |
|
logging
Package logging provides structured deploy logging for StackKits CLI.
|
Package logging provides structured deploy logging for StackKits CLI. |
|
managedentitlement
Package managedentitlement is the fail-closed availability gate for publisher-tagged managed (S2/S3) StackKits surfaces.
|
Package managedentitlement is the fail-closed availability gate for publisher-tagged managed (S2/S3) StackKits surfaces. |
|
netenv
Package netenv provides network environment detection and NodeContext resolution.
|
Package netenv provides network environment detection and NodeContext resolution. |
|
operations
Package operations validates and describes StackKits operation specs.
|
Package operations validates and describes StackKits operation specs. |
|
placement
Package placement resolves the S1 (StackKit-Standalone) capability bindings for a StackSpec.
|
Package placement resolves the S1 (StackKit-Standalone) capability bindings for a StackSpec. |
|
platformdeploy
Package platformdeploy contains the StackKit boundary for PaaS delivery.
|
Package platformdeploy contains the StackKit boundary for PaaS delivery. |
|
pocketid
Package pocketid is a thin HTTP client for the PocketID admin API.
|
Package pocketid is a thin HTTP client for the PocketID admin API. |
|
productkits
Package productkits owns the active product allowlist used by CLI execution, discovery, and registry projections.
|
Package productkits owns the active product allowlist used by CLI execution, discovery, and registry projections. |
|
referenceidv2
Package referenceid contains the closed grammars shared by otherwise independent provider-free wire packages.
|
Package referenceid contains the closed grammars shared by otherwise independent provider-free wire packages. |
|
registry
Package registry exposes the StackKits catalog (tools, module versions, curated stackkits) to the CLI in an OSS-safe way.
|
Package registry exposes the StackKits catalog (tools, module versions, curated stackkits) to the CLI in an OSS-safe way. |
|
resolvedplan
Package resolvedplan compiles the Architecture v2 intent, immutable kit definition, observed inventory, and a governed contract catalog into the one deterministic plan consumed by later generators and runtimes.
|
Package resolvedplan compiles the Architecture v2 intent, immutable kit definition, observed inventory, and a governed contract catalog into the one deterministic plan consumed by later generators and runtimes. |
|
restoreactivation
Package restoreactivation derives and executes the fail-closed authority for promoting an owner-verified staged restore into the live Basement runtime.
|
Package restoreactivation derives and executes the fail-closed authority for promoting an owner-verified staged restore into the live Basement runtime. |
|
rollout
Package rollout records rollout manifests and functional evidence.
|
Package rollout records rollout manifests and functional evidence. |
|
runtimeapplyv2
Package runtimeapply defines the provider-neutral durable operation journal contract for a sealed runtimeexecutor Apply.
|
Package runtimeapply defines the provider-neutral durable operation journal contract for a sealed runtimeexecutor Apply. |
|
runtimeexecutordispatch
Package runtimeexecutordispatch routes an already-authorized shared runtime request across exact opaque execution channels.
|
Package runtimeexecutordispatch routes an already-authorized shared runtime request across exact opaque execution channels. |
|
runtimeexecutorprocess
Package runtimeexecutorprocess implements the account-free, digest-pinned standard execution-channel process boundary.
|
Package runtimeexecutorprocess implements the account-free, digest-pinned standard execution-channel process boundary. |
|
runtimeexecutorv2
Package runtimeexecutor defines the provider-neutral v1beta1 contract for executing already-authorized governed runtime targets.
|
Package runtimeexecutor defines the provider-neutral v1beta1 contract for executing already-authorized governed runtime targets. |
|
runtimeobservation
Package runtimeobservation projects the CUE-owned provider-neutral runtime observation contract onto the standalone Go CLI and MCP surfaces.
|
Package runtimeobservation projects the CUE-owned provider-neutral runtime observation contract onto the standalone Go CLI and MCP surfaces. |
|
scaffold
Package scaffold renders module artifacts deterministically from a schema-validated module_facts.json (ADR-0027 Decision 1: "agents emit facts, a deterministic templater renders CUE").
|
Package scaffold renders module artifacts deterministically from a schema-validated module_facts.json (ADR-0027 Decision 1: "agents emit facts, a deterministic templater renders CUE"). |
|
securitybaseline
Package securitybaseline renders the host security baseline script shared by legacy StackKit execution and architecture-v2 renderers.
|
Package securitybaseline renders the host security baseline script shared by legacy StackKit execution and architecture-v2 renderers. |
|
servicecatalog
Package servicecatalog normalizes StackKit service identity across CUE, the Admin registry snapshot, generated URLs, and kombify.me registration.
|
Package servicecatalog normalizes StackKit service identity across CUE, the Admin registry snapshot, generated URLs, and kombify.me registration. |
|
servicecontrol
Package servicecontrol owns the local, owner-approved desired state and bounded execution contract for StackKits-managed services.
|
Package servicecontrol owns the local, owner-approved desired state and bounded execution contract for StackKits-managed services. |
|
ssh
Package ssh provides SSH operations for remote system management.
|
Package ssh provides SSH operations for remote system management. |
|
stackaction
Package stackaction contains the generated Go projection of StackKits' canonical CUE StackAction contract.
|
Package stackaction contains the generated Go projection of StackKits' canonical CUE StackAction contract. |
|
stackspecadmission
Package stackspecadmission owns the release-policy boundary between the bounded StackSpec v1 compatibility minor and canonical Architecture v2.
|
Package stackspecadmission owns the release-policy boundary between the bounded StackSpec v1 compatibility minor and canonical Architecture v2. |
|
stackspeccompletion
Package stackspeccompletion binds a losslessly read v1 StackSpec to one complete, explicit v2 candidate and resolves it through the governed Architecture v2 service.
|
Package stackspeccompletion binds a losslessly read v1 StackSpec to one complete, explicit v2 candidate and resolves it through the governed Architecture v2 service. |
|
stackspecintent
Package stackspecintent owns the only first-party persistence contract for canonical StackSpec v2 intent.
|
Package stackspecintent owns the only first-party persistence contract for canonical StackSpec v2 intent. |
|
stackspecmigration
Package stackspecmigration contains the bounded compatibility seam for the one-minor StackSpec v1 -> v2 migration described by ADR-0029.
|
Package stackspecmigration contains the bounded compatibility seam for the one-minor StackSpec v1 -> v2 migration described by ADR-0029. |
|
standaloneoperations
Package standaloneoperations owns the public standalone lifecycle operation catalog shared by the StackKits CLI, MCP connector, and State Console.
|
Package standaloneoperations owns the public standalone lifecycle operation catalog shared by the StackKits CLI, MCP connector, and State Console. |
|
system
Package system provides host system detection for StackKits.
|
Package system provides host system detection for StackKits. |
|
telemetry
Package telemetry contains opt-in runtime telemetry setup helpers.
|
Package telemetry contains opt-in runtime telemetry setup helpers. |
|
terramate
Package terramate provides Terramate execution capabilities for Day 2 operations.
|
Package terramate provides Terramate execution capabilities for Day 2 operations. |
|
tofu
Package tofu provides OpenTofu execution capabilities.
|
Package tofu provides OpenTofu execution capabilities. |
|
validation
Package validation provides 3-layer architecture validation for StackKits.
|
Package validation provides 3-layer architecture validation for StackKits. |
|
verify
Package verify implements post-deployment StackKit verification.
|
Package verify implements post-deployment StackKit verification. |
|
windowstoken
Package windowstoken exposes the two process-token principals Windows uses for local custody: TokenUser receives the private DACL grant, while TokenOwner is stamped as the owner of newly created objects.
|
Package windowstoken exposes the two process-token principals Windows uses for local custody: TokenUser receives the private DACL grant, while TokenOwner is stamped as the owner of newly created objects. |
|
workloadremoval
Package workloadremoval preserves the pre-public internal import path.
|
Package workloadremoval preserves the pre-public internal import path. |
|
pkg
|
|
|
backupbinding
Package backupbinding is the public producer contract for StackKits' provider-free external Cloud backup target handshake.
|
Package backupbinding is the public producer contract for StackKits' provider-free external Cloud backup target handshake. |
|
models
Package models defines the core data structures for StackKits.
|
Package models defines the core data structures for StackKits. |
|
productruntime
Package productruntime exposes the provider-free StackKits Product Runtime construction contract and its high-level prepared-Apply composition.
|
Package productruntime exposes the provider-free StackKits Product Runtime construction contract and its high-level prepared-Apply composition. |
|
workloadremoval
Package workloadremoval defines the provider-neutral, owner-approved removal contract for one exact workload from a previously applied Architecture v2 runtime request.
|
Package workloadremoval defines the provider-neutral, owner-approved removal contract for one exact workload from a previously applied Architecture v2 runtime request. |
|
scripts
|
|
|
e2e/identity-projection-fixture
command
|
|
|
e2e/modern-live-site
command
|
|
|
e2e/modern-runtime-process
command
|
Click to show internal directories.
Click to hide internal directories.