> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# techstack api stacks

> Generated reference for the techstack api stacks commands

<Note>Generated from the Techstack v0.39.0 release (source `49677b729cb9`). For an installed version, `techstack api <command> --help` is authoritative.</Note>

## techstack api stacks create

Create a StackKit deployment in the owner's Homelab.

Creates an internal StackKit deployment under the authenticated B2C
owner's singleton Homelab from the canonical StackKits stack-spec
payload supplied as `stack_spec`. The legacy `/stacks` route and
`stack_id` response field identify that deployment; they do not create
or select a second Homelab product. One TechStack instance can serve
many owners, each with their own Homelab. Legacy
`user_config`/kombination payloads remain accepted at this compatibility
boundary. Wizard clients should send a stable `X-Idempotency-Key`;
retries with the same key and payload return the original deployment,
planned server, and provisioning job.

```bash theme={null}
techstack api stacks create [flags]
```

<Warning>Requires confirmation: This operation creates the StackKit deployment and starts provisioning, which can order billed servers. Pass `--yes` or answer the prompt; a non-interactive run without `--yes` stops before any request with exit code 9.</Warning>

| | |
| - | - |
| HTTP | `POST /api/v1/stacks` |
| Changes state | Yes |
| MCP tool | `create_stack` |

| Argument | Type | Description |
| - | - | - |
| `--x-idempotency-key` | string | Stable wizard-attempt key. Maximum 256 characters. |
| `--mode` | string | Wizard mode. One of `easy`, `techie`. |
| `--name` | string | Stack name. |
| `--options` | object | — |
| `--provider` | string | Infrastructure provider (direct format). |
| `--services` | string\[] | Service names (direct format). |
| `--stack-spec` | object | Canonical StackKits stack-spec.yaml shape generated by the creation wizard. When present, this is the source of truth for provisioning and is stored as the stack user\_config for compatibility. |
| `--user-config` | object | Legacy structured configuration, including older kombination-style payloads. New wizard clients should send stack\_spec. |
| `--user-config-format` | string | One of `json`, `yaml`. |
| `--user-config-raw` | string | Raw YAML/JSON string. |
| `--body` | json | JSON request body (`application/json`) as a literal, `@path` or `-` for stdin. |

## techstack api stacks deploy

Roll out one StackKit deployment (unify + IaC + tofu apply).

```bash theme={null}
techstack api stacks deploy <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `POST /api/v1/stacks/{id}/deploy` |
| Changes state | Yes |
| MCP tool | `deploy_stack` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks destroy

Decommission one StackKit deployment and its infrastructure.

```bash theme={null}
techstack api stacks destroy <stack-id> [flags]
```

<Warning>Requires confirmation: This operation decommissions all infrastructure of the StackKit deployment. Pass `--yes` or answer the prompt; a non-interactive run without `--yes` stops before any request with exit code 9.</Warning>

| | |
| - | - |
| HTTP | `POST /api/v1/stacks/{id}/destroy` |
| Changes state | Yes |
| MCP tool | `destroy_stack` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks drift check

Trigger drift check.

Rate limited to once per 5 minutes (unless force=true)

```bash theme={null}
techstack api stacks drift check <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `POST /api/v1/stacks/{id}/drift/check` |
| Changes state | Yes |
| MCP tool | `check_drift` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |
| `--force` | boolean | Default `false`. |
| `--body` | json | JSON request body (`application/json`) as a literal, `@path` or `-` for stdin. |

## techstack api stacks drift details

Get detailed drift information with affected resources.

```bash theme={null}
techstack api stacks drift details <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks/{id}/drift/details` |
| Changes state | No |
| MCP tool | `get_drift_details` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks drift resolve

Trigger drift resolution (re-apply).

Precondition -- stack must have status "drifted"

```bash theme={null}
techstack api stacks drift resolve <stack-id> [flags]
```

<Warning>Requires confirmation: This operation re-applies the stack spec to its servers and overwrites drifted changes. Pass `--yes` or answer the prompt; a non-interactive run without `--yes` stops before any request with exit code 9.</Warning>

| | |
| - | - |
| HTTP | `POST /api/v1/stacks/{id}/drift/resolve` |
| Changes state | Yes |
| MCP tool | `resolve_drift` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks drift status

Get current drift status.

```bash theme={null}
techstack api stacks drift status <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks/{id}/drift/status` |
| Changes state | No |
| MCP tool | `get_drift_status` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks export

Export stack as stack-spec.yaml.

Returns StackKits stack-spec YAML or JSON depending on Accept header

```bash theme={null}
techstack api stacks export <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks/{id}/export` |
| Changes state | No |
| MCP tool | `export_stack` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks import

Import stack-spec.yaml as a StackKit deployment.

Imports YAML or JSON as a deployment under the authenticated owner's Homelab.

```bash theme={null}
techstack api stacks import [flags]
```

| | |
| - | - |
| HTTP | `POST /api/v1/stacks/import` |
| Changes state | Yes |
| MCP tool | `import_stack` |

| Argument | Type | Description |
| - | - | - |
| `--body` | json | **Required.** JSON request body (`application/json`) as a literal, `@path` or `-` for stdin. |

## techstack api stacks intent

Get persisted kombination.yaml (byte-exact, base64).

```bash theme={null}
techstack api stacks intent <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks/{id}/intent` |
| Changes state | No |
| MCP tool | `get_stack_intent` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks list

List the owner's StackKit deployments.

Returns every StackKit deployment beneath the authenticated owner's
singleton B2C Homelab. `kit_deployment_id`, `homelab_id`, and
`stackkit_id` are the product identities; legacy identifiers remain
compatibility aliases on this route while consumers migrate.

```bash theme={null}
techstack api stacks list [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks` |
| Changes state | No |
| MCP tool | `list_kit_deployments` |

## techstack api stacks managed-runtimes add

Add one managed Node through native provider control.

Creates or resumes one deterministic Add-Server job for the exact
owned StackKit deployment. The standard `Idempotency-Key` is mandatory.
Replaying the same key with the same canonical request returns the original
job, lease, runtime-server, resource-generation, and provider-operation
correlations; reusing it with different intent fails with 409.

The raw key is never persisted or returned. A lost response or an
uncertain native-admission outcome remains resumable only with the
same key. HTTP acceptance means native admission is durable and
provider reconciliation is pending; it never claims that the VM is
already provisioned or healthy. Fresh admission atomically reserves
the authenticated tenant/owner capacity slot with the lease generation
and provider operation. When authoritative native admission finds that
bounded capacity full, it persists a non-retryable 403 outcome and
replaying that denied job returns the same outcome. Exact replays of an
already committed admission reuse its existing reservation. This version
has no automatic reservation release: terminal or local decommission
state alone does not free a slot. Lease inventory and feature-delivery
flags never authorize or deny capacity.
Hosted fresh admission also requires the v2-signed commercial runtime
and provider entitlements plus the signed `cloud.runtime.credits`
`managed_servers` mode/limit decision; feature flags alone never grant
provider capacity. Self-host OSS uses its construction-fixed static
release-manifest policy instead of a SaaS entitlement dependency.

```bash theme={null}
techstack api stacks managed-runtimes add <stack-id> [flags]
```

<Warning>Requires confirmation: This operation orders an additional managed server for the StackKit deployment and is billed. Pass `--yes` or answer the prompt; a non-interactive run without `--yes` stops before any request with exit code 9.</Warning>

| | |
| - | - |
| HTTP | `POST /api/v1/stacks/{id}/managed-runtimes` |
| Changes state | Yes |
| MCP tool | `add_managed_runtime_server` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |
| `--ionos-datacenter` | string | IONOS datacenter alias for provider\_region; ignored for other canonical providers. |
| `--node-role` | string | One of `foundation`, `worker`, `storage`. Default `"worker"`. |
| `--provider-id` | string | **Required.** Canonical executable provider identifier; historical display aliases are rejected. One of `centron`, `ionos`. |
| `--provider-region` | string | Provider region. For IONOS this is normalized to the canonical datacenter identifier. |
| `--runtime-offering-id` | string | Canonical managed-runtime offering. Omission uses the stack's snapshotted effective default. |
| `--services` | string\[] | Service keys; duplicates and order are semantically insignificant. |
| `--stackkit` | string | StackKit foundation requested for this server. |
| `--body` | json | JSON request body (`application/json`) as a literal, `@path` or `-` for stdin. |

## techstack api stacks operations

Get the post-configuration operations read model for one owned StackKit deployment.

Returns the exact owner- and tenant-scoped read model used by the TechStack operations dashboard. `approved_servers` records operator approval; `connected_servers` is stricter and counts only assigned, approved Nodes with freshness-qualified canonical Guard heartbeat, connection, and health evidence. The operation is read-only and never starts rollout, provisioning, or provider work.

```bash theme={null}
techstack api stacks operations <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks/{id}/operations` |
| Changes state | No |
| MCP tool | `get_stack_operations` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks owner-spec

Fetch the owner bootstrap spec for a StackKit deployment.

StackKit admin-bootstrap endpoint for fetching local owner fields and
the recovery passphrase hash. This route accepts only the short-lived
bootstrap bearer token returned by `createStack`; it does not use the
normal browser/session bearer token.

```bash theme={null}
techstack api stacks owner-spec <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks/{id}/owner-spec` |
| Changes state | No |
| MCP tool | `get_stack_owner_spec` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks pipeline-status

Get complete pipeline status for all spec phases.

```bash theme={null}
techstack api stacks pipeline-status <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks/{id}/pipeline-status` |
| Changes state | No |
| MCP tool | `get_pipeline_status` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks provision

Start provisioning an existing StackKit deployment.

```bash theme={null}
techstack api stacks provision <stack-id> [flags]
```

<Warning>Requires confirmation: This operation starts provisioning the StackKit deployment, which can order billed servers. Pass `--yes` or answer the prompt; a non-interactive run without `--yes` stops before any request with exit code 9.</Warning>

| | |
| - | - |
| HTTP | `POST /api/v1/stacks/{id}/provision` |
| Changes state | Yes |
| MCP tool | `provision_stack` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |
| `--body` | json | JSON request body (`application/json`) as a literal, `@path` or `-` for stdin. |

## techstack api stacks prune-orphans

Review or apply owner-scoped test-residue cleanup.

Two-phase cleanup for control-plane projections only. A `dry_run`
returns the exact authenticated-owner E2E/runtime-cloud candidates and
a stable revision-bound digest. `apply` recomputes the plan and accepts
only that exact digest. This route never decommissions a lease, calls a
provider, destroys infrastructure, or enqueues lifecycle work.

```bash theme={null}
techstack api stacks prune-orphans [flags]
```

<Warning>Requires confirmation: This operation deletes the reviewed orphaned control-plane records when mode is apply. Pass `--yes` or answer the prompt; a non-interactive run without `--yes` stops before any request with exit code 9.</Warning>

| | |
| - | - |
| HTTP | `POST /api/v1/stacks/prune-orphans` |
| Changes state | Yes |
| MCP tool | `review_or_apply_orphan_projection_cleanup` |

| Argument | Type | Description |
| - | - | - |
| `--digest` | string | Required for apply; copied unchanged from the reviewed dry-run. |
| `--mode` | string | **Required.** One of `dry_run`, `apply`. |
| `--stack-id` | string | Optional exact deployment scope used by E2E cleanup. |
| `--body` | json | JSON request body (`application/json`) as a literal, `@path` or `-` for stdin. |

## techstack api stacks requirements

Get requirements spec (Phase 1 output).

```bash theme={null}
techstack api stacks requirements <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks/{id}/requirements` |
| Changes state | No |
| MCP tool | `get_stack_requirements` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks resume-enrollment

Resume one overdue managed Node wait on its exact existing VM.

Authenticated, idempotent recovery for a persisted `waiting_enrollment`,
`waiting_provider_provision`, or `waiting_canonical_guard` job whose
`next_resume_at` has been overdue beyond the bounded grace period. The
server validates the owned StackKit deployment, source job, wait reason,
exact lease, active foundation role, and canonical Node as one operation. It
atomically retires the exact source wait, creates or rehydrates one
deterministic replacement deploy bound to the same lease and Node,
and replays that job on later calls. Before handler entry,
queue workers atomically acquire the durable `tenant/stack` compatibility
execution claim; this serializes different jobs for the same StackKit
deployment across Techstack
replicas. The claim remains durable `running` until the handler exits,
including during cancellation. This endpoint never invokes provider VM
creation or selects a newer VM. A replacement found durable `running`
after a crash remains fail-closed, is reported as the same job, and is
never duplicated automatically; runtime-action reconciliation remains a
separate operator concern.

```bash theme={null}
techstack api stacks resume-enrollment <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `POST /api/v1/stacks/{id}/resume-enrollment` |
| Changes state | Yes |
| MCP tool | `resume_stack_enrollment` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |
| `--job-id` | string | **Required.** Persisted source job currently projected as waiting\_enrollment. |
| `--lease-id` | string | **Required.** Exact managed foundation lease already bound to the source job. |
| `--body` | json | JSON request body (`application/json`) as a literal, `@path` or `-` for stdin. |

## techstack api stacks retry-rollout

Retry one failed StackKit deployment rollout on its exact existing managed VM.

Validates the owned failed deploy, its exact active foundation lease,
and canonical Node in one server-side operation. The deterministic
durable replacement bypasses provider VM creation, wins a durable
`tenant/stack` compatibility execution claim before handler entry, and is
replayed on repeated calls to this operation. The claim serializes different
jobs for the same StackKit deployment across replicas and remains
fail-closed as `running` after a process crash until operator reconciliation.

```bash theme={null}
techstack api stacks retry-rollout <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `POST /api/v1/stacks/{id}/retry-rollout` |
| Changes state | Yes |
| MCP tool | `retry_stack_rollout` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |
| `--candidate-spec` | object | Optional canonical StackSpec repairing missing route, access and data dependencies of already admitted modules. The pinned CLI validates it; revision CAS and candidate digest bind retries. Applied installations must use their existing change-set authority. |
| `--current-spec-hash` | string | Normalized current node intent hash for an exact failed INIT whose immutable retry lineage proves a prior failed APPLY on this runtime. Required only for that partial INIT recovery; rejected on other paths. This is solely the CLI atomic CAS precondition, never authorization. Obtain through the pinned CLI resolve on the same current canonical node document. The durable receipt seals this value and lineage against changed replay. |
| `--lease-id` | string | **Required.** Exact active managed foundation lease bound to the failed job. |
| `--owner-approved` | boolean | Required true when supplying a canonical initial-rollout repair candidate. |
| `--source-job-id` | string | **Required.** Exact failed deploy job used as immutable retry evidence. |
| `--body` | json | JSON request body (`application/json`) as a literal, `@path` or `-` for stdin. |

## techstack api stacks routing ensure

Ensure the desired routing overlay for one exact StackKit deployment and Node.

Atomically persists an idempotent, revisioned routing overlay without mutating the user's immutable intent. server\_id is always exact and mandatory. lease\_id is mandatory for managed runtimes and omitted for a local/Basement runtime which has no lease. For a managed target, a true ensure\_rollout request dispatches the existing deploy pipeline only after proving that its selected active foundation lease and canonical Node equal this exact target. The API never reports the resulting job as already applied. The overlay is consumed only while deriving StackKits artifacts and this path never creates or selects a replacement VM.

```bash theme={null}
techstack api stacks routing ensure <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `PUT /api/v1/stacks/{id}/routing` |
| Changes state | Yes |
| MCP tool | `ensure_stack_routing` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |
| `--if-match` | string | Optional optimistic-concurrency routing revision, for example `"3"`. |
| `--domain` | string | **Required.** Normalized custom domain; schemes, paths, ports, and wildcards are rejected. |
| `--ensure-rollout` | boolean | Request reconciliation without implying that it has already been dispatched or applied. Default `false`. |
| `--lease-id` | string | Exact RuntimeLease for a managed target. Omit for a local/Basement ServerRuntime that genuinely has no lease; invented leases are rejected. |
| `--mode` | string | **Required.** One of `custom-domain`. |
| `--provenance` | object | **Required.** |
| `--server-id` | string | **Required.** Exact canonical ServerRuntime target belonging to the stack and owner. For a managed lease this is the server\_id exposed by the operations/ worker projection. If that read-model row is not present yet, TechStack may create only this deterministic ID from the validated exact lease. |
| `--body` | json | JSON request body (`application/json`) as a literal, `@path` or `-` for stdin. |

## techstack api stacks routing get

Read desired and observed routing state for one StackKit deployment.

Returns the tenant- and owner-bound routing overlay for the exact StackKit deployment. Desired state and observed/applied state are reported separately so clients never infer a successful DNS, TLS, or StackKit rollout from persistence alone.

```bash theme={null}
techstack api stacks routing get <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks/{id}/routing` |
| Changes state | No |
| MCP tool | `get_stack_routing` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks routing targets

List explicit primary routing targets for one StackKit deployment.

Read-only discovery backed by active RuntimeLease authority. Returns every owner-visible foundation/control-plane target and never selects one, creates a canonical Node (`ServerRuntime`) projection, or mutates the StackKit deployment. Callers must send the complete server\_id and lease\_id tuple to a routing mutation.

```bash theme={null}
techstack api stacks routing targets <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks/{id}/routing/targets` |
| Changes state | No |
| MCP tool | `list_stack_routing_targets` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks unified

Get unified spec (Phase 2 output).

```bash theme={null}
techstack api stacks unified <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks/{id}/unified` |
| Changes state | No |
| MCP tool | `get_stack_unified` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |

## techstack api stacks validate-import

Validate spec without importing.

```bash theme={null}
techstack api stacks validate-import [flags]
```

| | |
| - | - |
| HTTP | `POST /api/v1/stacks/import/validate` |
| Changes state | Yes |
| MCP tool | `validate_import` |

| Argument | Type | Description |
| - | - | - |
| `--body` | json | **Required.** JSON request body (`application/json`) as a literal, `@path` or `-` for stdin. |

## techstack api stacks verify-chain

Verify spec hash chain integrity.

```bash theme={null}
techstack api stacks verify-chain <stack-id> [flags]
```

| | |
| - | - |
| HTTP | `GET /api/v1/stacks/{id}/verify-chain` |
| Changes state | No |
| MCP tool | `verify_spec_chain` |

| Argument | Type | Description |
| - | - | - |
| `<stack-id>` | string | **Required.** Stack ID. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.