> ## 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. # 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. ## OpenAPI ````yaml /techstack/reference/api/openapi.yaml post /api/v1/stacks/{id}/managed-runtimes openapi: 3.1.0 info: title: kombify-TechStack API description: > REST API for kombify-TechStack -- the hybrid cloud control plane for homelabs. kombify-TechStack manages infrastructure through a spec-driven architecture: validate YAML specs via CUE, generate OpenTofu configurations, and manage nodes through a gRPC agent protocol. ## Authentication Authenticated endpoints accept an OIDC/JWKS bearer token or an API key where documented. Self-hosted TechStack defaults to Pocket ID as identity provider. SaaS routes enter through the edge with Auth0 as the platform identity provider. PocketBase session exchange remains legacy migration compatibility only. ## Response Format **Success:** `{ "data": , "meta": { "total": int, "page": int, "per_page": int } }` **Error:** `{ "error": { "code": "", "message": "...", "details": } }` ## Pagination List endpoints accept `page` (default: 1) and `per_page` (default: 20, max: 100) query parameters. version: 1.0.0 contact: name: kombify url: https://kombify.io license: name: Apache-2.0 AND GPL-3.0 url: https://github.com/KombiverseLabs/kombify-TechStack/blob/main/LICENSE servers: - url: https://api.kombify.io/v1/techstack description: >- Production canonical (via Cloudflare edge gateway, strip-prefix). Clients MUST use this projection. The Gateway strips /v1/techstack and re-adds /api/v1 at the origin, so it resolves the /api/v1/* paths below cleanly. - url: http://localhost:5260 description: Local development - url: https://techstack.kombify.io description: Production (direct, no Gateway prefix) - url: https://api.kombify.io/v1/orchestrator description: >- Legacy StackKit-Orchestrator projection of the same origin. RETAINED for backward compatibility with existing consumers only. Do NOT use for mobile or new clients: combined with the /api/v1/* paths it double-resolves (yielding /v1/orchestrator/api/v1/...). Prefer /v1/techstack. security: - bearerAuth: [] tags: - name: Health description: Health checks and service info (no auth required) - name: Instance description: Local instance identity and enrollment metadata - name: Stacks description: Stack lifecycle management (create, provision, deploy, destroy) - name: Stacks - Specs description: Access persisted specification chain (intent, requirements, unified) - name: Stacks - Import/Export description: Import and export StackKits stack-spec.yaml configurations - name: Stacks - Drift description: Infrastructure drift detection and resolution - name: Unifier description: Spec validation, analysis, unification, and IaC generation pipeline - name: StackKits description: Infrastructure template catalog - name: Add-ons description: Add-on detection and registry - name: Workers description: Worker node registration and management - name: Servers description: Canonical server lifecycle, connection, and health state - name: Inventory description: >- Owner-scoped sanitized server and service read models for UI, API, and MCP clients - name: Pre-Checks description: Pre-deployment hardware and software validation - name: Agents description: Connected gRPC agent management and commands - name: Jobs description: Background job monitoring and SSE streaming - name: Discovery description: Network device discovery and SSH testing - name: Features description: Feature flags (read-only; managed centrally via the kombify Admin API) - name: Monthly Runtime description: Provider-free user API for subscription-backed stack runtime control - name: Runtime description: Recent runtime/deploy logs (job/deploy progress + container tail) - name: Wallet description: >- Redacted recovery-item wallet with biometric/platform-reauth-gated reveal. List responses strip secret/totp; reveal requires a fresh trusted-reauth HMAC proof (5-minute window) and is audited server-side. - name: Trust description: Pairing tokens for worker enrollment - name: Client Binding description: >- Short-lived HTTPS pairing for a second client and normal OIDC account handoff - name: Tunnel description: Cloudflare tunnel management for NAT traversal - name: Backups description: Database backup management (admin only) - name: Auth description: Authentication mode and SSO configuration - name: Metrics description: Prometheus-compatible instance metrics for admin/infra scrapers - name: Internal description: >- Internal SaaS-only APIs, including servicecall-protected executor contracts paths: /api/v1/stacks/{id}/managed-runtimes: post: tags: - Stacks - Jobs summary: Add one managed Node through native provider control description: > 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. operationId: addManagedRuntimeServer parameters: - $ref: '#/components/parameters/stackId' - name: Idempotency-Key in: header required: true description: >- One opaque, case-sensitive Add-Server attempt key. Supply exactly one value without leading/trailing whitespace, comma separators, or control characters. Maximum 256 UTF-8 bytes. schema: type: string minLength: 1 maxLength: 256 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddManagedRuntimeServerRequest' responses: '202': description: >- Native managed-runtime admission accepted or safely replayed; provisioning remains pending. content: application/json: schema: $ref: '#/components/schemas/AddManagedRuntimeServerEnvelope' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/ValidationError' '503': $ref: '#/components/responses/ServiceUnavailable' components: parameters: stackId: name: id in: path required: true description: Stack ID schema: type: string schemas: AddManagedRuntimeServerRequest: type: object required: - provider_id properties: provider_id: type: string enum: - centron - ionos description: >- Canonical executable provider identifier; historical display aliases are rejected. provider_region: type: string maxLength: 128 description: >- Provider region. For IONOS this is normalized to the canonical datacenter identifier. ionos_datacenter: type: string maxLength: 128 description: >- IONOS datacenter alias for provider_region; ignored for other canonical providers. node_role: type: string enum: - foundation - worker - storage default: worker runtime_offering_id: type: string description: >- Canonical managed-runtime offering. Omission uses the stack's snapshotted effective default. stackkit: type: string description: StackKit foundation requested for this server. services: type: array maxItems: 128 items: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$ description: Service keys; duplicates and order are semantically insignificant. AddManagedRuntimeServerEnvelope: type: object required: - data - meta properties: data: $ref: '#/components/schemas/AddManagedRuntimeServer' meta: $ref: '#/components/schemas/ResponseMeta' AddManagedRuntimeServer: type: object required: - stack_id - job_id - lease_id - runtime_server_id - resource_generation_id - operation_id - provider_id - node_role - runtime_offering_id - enrollment_status - runtime_phase - idempotent_replay - message properties: stack_id: type: string job_id: type: string description: >- Deterministic tenant/stack/operation/key job identity; it does not expose the raw key. lease_id: type: string runtime_server_id: type: string resource_generation_id: type: string format: uuid description: Sole generation authority for this admitted resource intent. operation_id: type: string description: Exact native provider-control operation correlation. provider_id: type: string enum: - centron - ionos provider_region: type: string ionos_datacenter: type: string node_role: type: string enum: - foundation - worker - storage runtime_offering_id: type: string enrollment_status: type: string const: pending runtime_phase: type: string const: lease_pending idempotent_replay: type: boolean description: True when the HTTP job or native admission was safely replayed. message: type: string warnings: type: array items: type: string description: >- Non-terminal persistence warning; clients must retry only with the same Idempotency-Key. ResponseMeta: type: object properties: total: type: integer page: type: integer per_page: type: integer managed_runtime_inventory_complete: type: boolean description: >- True only when the managed RuntimeLease authority was configured and read successfully for this inventory response. worker_inventory_sha256: type: string pattern: ^[0-9a-f]{64}$ description: >- Stable digest of the complete worker identity, attachment, freshness, and managed RuntimeLease authority snapshot used for pagination. managed_runtime_active_lease_ids: type: array items: type: string description: >- Canonically sorted IDs of visible managed RuntimeLeases classified as active for inventory and cleanup. This visibility projection is not capacity reservation or release authority. managed_runtime_inactive_lease_ids: type: array items: type: string description: >- Canonically sorted IDs of visible managed RuntimeLeases classified as cancelled or archived for inventory and cleanup. Inactive state does not prove provider absence or release managed-server capacity. managed_runtime_lease_generation_digests: type: array items: type: object required: - lease_id - resource_generation_digest properties: lease_id: type: string resource_generation_digest: type: string pattern: ^[0-9a-f]{64}$ description: >- Canonically sorted opaque bindings from each visible managed RuntimeLease ID to its exact provider-resource generation. Missing coverage makes destructive inventory proof invalid while leaving ordinary dashboard inventory readable. managed_runtime_duplicate_lease_ids: type: array items: type: string description: >- Managed RuntimeLease IDs represented by multiple persisted worker rows before UI projection deduplication; must be empty for destructive inventory proof. managed_runtime_attachment_conflict_lease_ids: type: array items: type: string description: >- Canonically sorted caller-visible managed RuntimeLease IDs with a conflicting tenant-wide worker attachment; must be empty for destructive inventory proof and never exposes foreign private lease or worker details. ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - INTERNAL_ERROR - NOT_FOUND - BAD_REQUEST - UNAUTHORIZED - FORBIDDEN - CONFLICT - VALIDATION_ERROR - RATE_LIMITED - SERVICE_UNAVAILABLE - METHOD_NOT_ALLOWED message: type: string details: description: Additional error context (validation errors, etc.) responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: Request conflicts with existing state content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ValidationError: description: Request failed semantic validation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServiceUnavailable: description: Required control-plane persistence or dependency is unavailable content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- OIDC/JWKS bearer token. Self-hosted defaults to Pocket ID; SaaS uses Auth0 through the edge. PocketBase JWT is legacy migration compatibility only. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.