# StackKits Agent Context

StackKits is a local CLI plus node-local server framework for deploying homelab infrastructure from declarative specs. CUE is the source of truth for schemas, defaults, constraints, module contracts, and deployment shape. Generated OpenTofu, Docker Compose, scripts, tfvars, state, and snapshots are outputs.

## Release Stance

Basement Kit is the supported one-command path for a home/LAN host (Cloud Kit is preview; Modern Homelab is an alpha definition archive, not an install target). The default advertised installer detects the host and selects the matching kit:

```bash
curl -sSL https://install.stackkit.cc | sh
```

Home/LAN continues into Basement Kit; a public VPS continues into Cloud Kit (and asks first). Kit-specific full installers remain at `https://base.stackkit.cc` and `https://cloud.stackkit.cc`. `STACKKIT_CLI_ONLY=1` installs only the CLI.

Unreleased kit definitions and optional add-on catalogs are not part of the public OSS release surface.

Standalone Docker Compose is the primary application runtime; Komodo and Coolify are explicit integrations with separately stated evidence. A published release is not runtime acceptance: per-use-case runtime evidence is recorded in the public repository. User-installed apps outside that path are state-unmanaged by StackKit.

## Agent Workflow

Use non-interactive commands and JSON output where available:

```bash
stackkit agent install-plan --json
stackkit agent self-check --json
stackkit agent prompt basekit-autonomous-rollout
stackkit init basement-kit --owner-source=local --non-interactive
stackkit validate
stackkit generate
stackkit plan
stackkit status --json
stackkit verify --http --json
stackkit logs list --json
stackkit compat
```

Never hand-edit generated rollout artifacts. Change StackSpec, CUE, or Go source, then regenerate.

Installation process comparison: /getting-started/installation-processes.md

Choose by three pillars:

- configuration and individualization degree;
- access options and authority boundary;
- automation degree.

Path boundary shorthand:

- `P0`: website/OpenMCP discovery and page-side WebMCP planning only; no target authority.
- `P4`: external agent executes installer/CLI through SSH; SSH is the authority.
- `P5`: protected remote endpoint for the same `stackkit` MCP connection after install; target day-2 capability, not the default first-install path.
- `P6`: local adapter for the same `stackkit` MCP connection through `stackkit-mcp`; same-machine process authority.

## Local API

`stackkit-server` is the node-local API surface. It is not a required hosted cloud service. Native read-only management covers status, logs, and run evidence; native CLI `verify` owns lifecycle verification. Legacy HTTP verify, doctor, and plan routes are exact-v0.6 compatibility surfaces and return typed unavailable responses on native v0.7+. Mutating management APIs are disabled by default.

OpenAPI mirror: /api/openapi.v1.yaml
OpenMCP discovery: /openmcp.json

## MCP

Website MCP discovery is read-only. Use `/openmcp.json` for public installer/docs/schema discovery.

The Module Profile Planner at `/planner` optionally registers four read-only browser tools: `stackkits_list_catalog`, `stackkits_get_module_profiles`, `stackkits_assess_capacity`, and `stackkits_prepare_handoff`. Human and agent actions share one visible planner state. The tools require explicit StackKit, use-case alternative, and module-local compute/storage/accelerator selections, treat CPU/RAM/free-storage facts as user declarations, and never invoke `apply`, a provider, SSH, or a target filesystem. Techstack owns recommendation; this surface exposes CUE facts and feasibility only. The resulting handoff still requires `stackkit compat` on the target host.

Its v2 contract is `/schemas/stackkits-webmcp-v2alpha1.schema.json`; the generated-catalog contract is `/schemas/stackkits-webmcp-catalog-v2alpha1.schema.json`; the exact-SHA CUE projection is `/data/stackkits-webmcp/v2alpha1/catalog.json`.

Agents should configure one MCP connection named `stackkit`. Locally it starts the `stackkit-mcp` adapter. After install, the same connector can be exposed by `stackkit-server` at `POST /mcp` and `GET /openmcp.json`. Write tools require `STACKKIT_MCP_ALLOW_WRITE=true`, an exact sibling-binary identity, and expose individual native CLI-equivalent operations only; there is no combined rollout/update macro. This MCP surface does not run `stackkit app add`, customer app rollout, or managed-serverless provisioning. Remote MCP should use Streamable HTTP through a protected endpoint, tunnel, VPN, or private network; WebSocket is only a custom transport/gateway option.

## Evidence

A release-hardening agent run should produce:

- manifest matching /schemas/stackkit-agent-run-manifest.schema.json
- functional result matching /schemas/stackkit-agent-functional-result.schema.json
- `stackkit verify --http --json` output
- latest run ID and evidence files
- Hub URL `https://base.home` from an enrolled device