Generated from the Techstack v0.39.0 release (source
49677b729cb9). For an installed version, techstack api <command> --help is authoritative.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 asstack_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.
techstack api stacks deploy
Roll out one StackKit deployment (unify + IaC + tofu apply).techstack api stacks destroy
Decommission one StackKit deployment and its infrastructure.techstack api stacks drift check
Trigger drift check. Rate limited to once per 5 minutes (unless force=true)techstack api stacks drift details
Get detailed drift information with affected resources.techstack api stacks drift resolve
Trigger drift resolution (re-apply). Precondition — stack must have status “drifted”techstack api stacks drift status
Get current drift status.techstack api stacks export
Export stack as stack-spec.yaml. Returns StackKits stack-spec YAML or JSON depending on Accept headertechstack api stacks import
Import stack-spec.yaml as a StackKit deployment. Imports YAML or JSON as a deployment under the authenticated owner’s Homelab.techstack api stacks intent
Get persisted kombination.yaml (byte-exact, base64).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.
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 standardIdempotency-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.
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.
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 bycreateStack; it does not use the
normal browser/session bearer token.
techstack api stacks pipeline-status
Get complete pipeline status for all spec phases.techstack api stacks provision
Start provisioning an existing StackKit deployment.techstack api stacks prune-orphans
Review or apply owner-scoped test-residue cleanup. Two-phase cleanup for control-plane projections only. Adry_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.
techstack api stacks requirements
Get requirements spec (Phase 1 output).techstack api stacks resume-enrollment
Resume one overdue managed Node wait on its exact existing VM. Authenticated, idempotent recovery for a persistedwaiting_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.
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 durabletenant/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.
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.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.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.