stackkit host

Provider-neutral host contract operations.

stackkit host [flags]

Subcommands: stackkit host attach-conformance, stackkit host conformance, stackkit host delivery, stackkit host environment, stackkit host gpu-check, stackkit host migrate-browser-ca, stackkit host preflight, stackkit host prepare, stackkit host reboot, stackkit host remediate, stackkit host security, stackkit host ssh, stackkit host updates

stackkit host attach-conformance

Attach exact host evidence to Inventory before plan generation.

stackkit host attach-conformance [flags]

Flag	Type	Default	Description
`--binding`	string	—	Required. Workspace-confined ExternalHostBinding JSON
`--inventory`	string	—	Required. Workspace-confined inventory.json to update atomically
`--receipt`	string	—	Required. Workspace-confined HostConformanceReceipt JSON

stackkit host conformance

Produce a provider-neutral conformance receipt on this host.

stackkit host conformance [flags]

Flag	Type	Default	Description
`--binding`	string	—	Required. Local ExternalHostBinding JSON file
`--output, -o`	string	`-`	Receipt destination (’-’ for JSON on stdout)

stackkit host delivery

Manage this node’s sealed host delivery recipient. Sealed host delivery brings Wallet items, backup targets and SSH access to this node. A delivering authority seals each value to this node’s recipient key (HPKE, pkg/hostdelivery); only this node opens it into its own custody. Techstack and Guard carry ciphertext and references only.

stackkit host delivery [flags]

Subcommands: stackkit host delivery detach, stackkit host delivery recipient, stackkit host delivery status

stackkit host delivery detach

Stop host delivery to this node and list the delivered secrets to rotate. Detach this node from host delivery: every delivered secret is marked as needing rotation, retired recipient keys are destroyed, and no delivery opens until the node is re-enrolled with ‘host delivery recipient --rotate’. The result lists the references and versions to rotate where they came from; it never contains a value. Values already in local custody stay usable here.

stackkit host delivery detach [flags]

Flag	Type	Default	Description
`--owner-approve`	bool	—	Authorize detaching this node

Examples

stackkit host delivery detach --owner-approve

stackkit host delivery recipient

Prove this node’s recipient key, pin the delivering authority, or rotate the key. Print a statement, signed by the local Owner key, that binds this node’s recipient key and its generation to this Site and node and echoes the caller’s challenge. The private key never leaves local custody. --authority-key pins the delivering authority’s Ed25519 public key for the current generation; Wallet items and SSH access open only when signed by it. A pinned key is never replaced in place. --rotate re-enrolls the node under the next generation (and with --authority-key pins a new authority): the previous key still opens deliveries issued before the rotation for at most their 15-minute lifetime and is then destroyed. Rotation also ends a detach.

stackkit host delivery recipient [flags]

Flag	Type	Default	Description
`--authority-key`	string	—	Delivering authority Ed25519 public key (base64) to pin for this generation
`--authority-key-id`	string	—	Key ID the delivering authority signs envelopes with
`--challenge`	string	—	Fresh value from the delivering authority that the statement must echo
`--owner-approve`	bool	—	Authorize this node’s recipient change
`--rotate`	bool	—	Re-enroll under the next recipient generation

Examples

stackkit host delivery recipient --challenge "$CHALLENGE" --authority-key "$WALLET_KEY" --authority-key-id wallet-1 --owner-approve
stackkit host delivery recipient --challenge "$CHALLENGE" --rotate --owner-approve

stackkit host delivery status

Show the recipient generation, pinned authority, detach state and delivered references. Report this node’s recipient generation and fingerprint, retired generations still openable, the pinned delivering authority, whether the node is detached, and every delivered secret by reference and version, with its rotation mark. No value is read.

stackkit host delivery status [flags]

stackkit host environment

Observe whether this host looks like a home network or a public server. Detect the network environment of this machine. This is observation, not kit selection. Installers and init use it to ask before authoring local home addresses on a VPS, or Cloud Kit on a LAN host. STACKKIT_NETWORK_ENV=home|vps|cloud|unknown overrides live detection.

stackkit host environment [flags]

Flag	Type	Default	Description
`--json`	bool	—	Emit the observation as JSON

Examples

# Show whether this host looks like a home network or a public server
stackkit host environment

# The same observation as JSON
stackkit host environment --json

# Override a wrong detection for the next command, here Basement Kit init on a home host
STACKKIT_NETWORK_ENV=home stackkit init basement-kit --catalog-defaults --owner-source=local --owner-email you@example.com

stackkit host gpu-check

Prove the NVIDIA GPU under a short real CUDA load. Run NVIDIA’s CUDA vectorAdd sample in a container on the GPU (Docker CDI device nvidia.com/gpu=all), then read the kernel log for NVRM Xid errors and ask nvidia-smi again. nvidia-smi listing the GPU is not proof that it works: a GPU on a weak power supply or a marginal link, typical for a Thunderbolt eGPU, answers at idle and falls off the bus (Xid 79) as soon as CUDA draws power. This check refuses then and names the cause. It changes nothing on the host except pulling the pinned sample image. Run it as root so the kernel log can be read.

stackkit host gpu-check [flags]

Flag	Type	Default	Description
`--image`	string	`nvcr.io/nvidia/k8s/cuda-sample:vectoradd-cuda12.5.0@sha256:7c7540bdf1f942d4fb6db97069fd6c289471b54ac29e3c7fcdf914cf77af7d41`	CUDA sample image that prints “Test PASSED”
`--json`	bool	—	Emit the check and its evidence as machine-readable JSON
`--runs`	int	`10`	How many times the CUDA sample runs

Examples

# Prove the GPU after the driver and Container Toolkit are installed
sudo stackkit host gpu-check

# Longer load, machine-readable result
sudo stackkit host gpu-check --runs 50 --json

stackkit host migrate-browser-ca

Migrate this node’s authenticated legacy CA to the browser-capable policy. Explicitly migrate legacy Basement CA signing keys while preserving the Owner signing key, PocketID identities, runtime secrets, ingress leaf keys, addresses and volumes. Retain an already current root. Apply and verify the current native plan before --complete. Clients must approve a changed public root through the existing client-trust handoff.

stackkit host migrate-browser-ca [flags]

Flag	Type	Default	Description
`--complete`	bool	—	Retire the recovery journal after current native Apply and ordinary TLS verification
`--owner-approve`	bool	—	Authorize this node’s explicit CA transition

stackkit host preflight

Check whether this host can run the selected StackKit. Measure this host and compare it against the floor the kit declares. Preflight performs read-only probes only: it never installs, starts, or configures anything. Apply runs the same admission before it mutates the host.

stackkit host preflight [flags]

Flag	Type	Default	Description
`--json`	bool	—	Emit the versioned preflight report as machine-readable JSON
`--local-node`	string	—	Exact local Node in the supplied ResolvedPlan
`--policy`	string	—	Admission policy: strict, warn (default), or skip
`--resolved-plan`	string	—	Verified canonical ResolvedPlan whose host listeners to check

Examples

# Check this host against the kit selected in the current deployment directory
stackkit host preflight

# Also refuse on warnings and unknown facts, and print the report as JSON
stackkit host preflight --policy strict --json

stackkit host prepare

Prepare this host before Cloud Kit apply. Provision the Cloud execution-channel account and SSH key custody required before host-security disables root login. Cloud Kit installers and apply call this automatically. The command exists for diagnostics and for converging a workspace after manual interruption. It mints or reuses the workspace-custodied key under .stackkit/cloud-host-security/execution-channel/ and installs the matching public key on the execution-channel Linux account.

stackkit host prepare [flags]

Examples

# Converge the execution-channel account after an interrupted Cloud Kit install (run as root in the Cloud Kit deployment directory)
cd my-cloud
stackkit host prepare

stackkit host reboot

Schedule a reboot of this node. Schedule a reboot of this node after a short delay and return immediately. The returned boot_id_before identifies the current boot, so a caller can tell the node came back by reading a different boot ID. The command refuses a node that runs the Techstack control plane, a node where apt or dpkg holds its lock or a host update runs, and a node that cannot boot unattended (volumes in /etc/crypttab that need a passphrase, or no apt). When the delay ends a guard checks again, waits up to 15 minutes for any package operation to finish, and requests the reboot while holding the dpkg locks. A node that stays busy is not rebooted; its boot ID stays the same.

stackkit host reboot [flags]

Flag	Type	Default	Description
`--delay`	duration	`30s`	Time until the reboot starts (1s to 5m)
`--json`	bool	—	Emit the stackkit.host-maintenance/v1 result as machine-readable JSON
`--yes`	bool	—	Confirm that this node may reboot

Examples

# Reboot this node in 30 seconds
sudo stackkit host reboot --yes

# Reboot in two minutes and report the boot ID to compare against
sudo stackkit host reboot --yes --delay 2m --json

stackkit host remediate

Show or carry out fixes for what host preflight found. List the fixes that answer this host’s preflight findings, or carry one out. Without --apply nothing is changed: the command measures the host and prints what each fix would do, whether it can be undone, and whether it needs root. With --apply <id> --yes the named fix runs, and the check that justified it is measured again afterwards so the result states what actually changed rather than that something was attempted.

stackkit host remediate [flags]

Flag	Type	Default	Description
`--apply`	string	—	Carry out the named resolution (requires `--yes`)
`--auto-reversible`	bool	—	Carry out every undoable fix that may run unattended (requires `--yes`)
`--json`	bool	—	Emit the remediation plan or record as machine-readable JSON
`--policy`	string	—	Preflight policy used to find findings: strict or warn (default)
`--yes`	bool	—	Confirm that the named resolution may change this host

Examples

# List the fixes for this host's preflight findings without changing anything
stackkit host remediate

# Carry out one fix by the ID the list printed
stackkit host remediate --apply <resolution-id> --yes

# Carry out every undoable fix that may run unattended
stackkit host remediate --auto-reversible --yes

stackkit host security

Verify and repair the host security baseline with versioned evidence. Observe this node against the StackKits host security baseline, and restore what drifted without cutting the management path. ‘verify’ never changes the host. It produces stackkit.host-security-evidence/v1 for the firewall, sshd, brute-force protection, automatic and pending security updates, reboot state, kernel parameters, exposed listeners and certificate expiry, and for the SSH CA trust and host certificate delivered to this node (‘host ssh apply’) once they are recorded. Every control is compliant, drifted, unknown or an owner-approved exception, and the evidence expires: a stale observation is unknown, and an unknown control never counts as compliant. It works on its own (Standard Mode, no account) and through the pinned CLI when Techstack manages the deployment (--mode advanced).

stackkit host security [flags]

Subcommands: stackkit host security repair, stackkit host security status, stackkit host security verify

stackkit host security repair

Restore drifted baseline controls without cutting the management path. Plan, or with --apply carry out, the restoration of drifted controls. Without --apply nothing is changed: the command measures the host and prints what each repair would do. With --apply only the named (--control) or drifted controls are touched, and every change is checked first:

  - the firewall always keeps admitting the ssh sessions in use and every
    --management-source on every sshd port, and a policy that would not is
    refused before it is loaded;
  - password logins are disabled only when an account holds an authorized key;
    without one they stay on, the step is refused with reason no_authorized_key
    and the rest of the baseline is still repaired. The previous sshd and
    firewall configuration is restored if the new one does not validate or does
    not take effect;
  - fail2ban never bans the management path.

A control that cannot be observed, or that the owner approved an exception for, is not touched. A Cloud site’s firewall and root login are restored by ‘stackkit apply’. Each step records the control before and after, and a repeated repair of a compliant control changes nothing.

stackkit host security repair [flags]

Flag	Type	Default	Description
`--apply`	bool	—	Carry out the repair; without it the command only plans
`--control`	stringArray	—	Restrict the repair to this control ID (repeatable)
`--declared-port`	stringArray	—	Declared service port as tcp/443 or udp/5353 (repeatable)
`--exceptions`	string	`/etc/stackkit/host-security/exceptions.json`	Owner-controlled exceptions file (each exception needs an owner and an expiry)
`--freshness`	duration	`15m0s`	How long the evidence may be relied on before it expires (1m to 24h)
`--host-name`	stringArray	—	Name the delivered SSH host certificate must carry (repeatable; default: the system hostname)
`--json`	bool	—	Emit the result as machine-readable JSON
`--kit`	string	—	Kit slug to record (default: the kit of the workspace StackSpec)
`--local-node`	string	—	Exact local Node in the supplied ResolvedPlan
`--management-source`	stringArray	—	Network that must always reach ssh, as a CIDR (repeatable)
`--mode`	string	`standard`	Lifecycle mode to record: standard, or advanced when Techstack manages this deployment
`--no-record`	bool	—	Do not write the post-repair evidence under .stackkit/
`--resolved-plan`	string	—	Verified canonical ResolvedPlan whose declared listeners to judge exposure against
`--site-kind`	string	—	Site kind of this host: home or cloud (default: inferred from the kit; modern-homelab needs it)

Examples

# See what would be repaired
sudo stackkit host security repair --site-kind home

# Restore only the firewall, keeping a jump host reachable
sudo stackkit host security repair --apply --control firewall.default_inbound --management-source 198.51.100.0/24

stackkit host security status

Read the stored evidence as it stands now, without observing the host. Read the evidence ‘verify’ last recorded in this workspace and judge it at the current time. Evidence past its freshness budget is unknown: an old observation proves nothing about the host now.

stackkit host security status [flags]

Flag	Type	Default	Description
`--drift-scope`	string	`all`	Controls that decide `--fail-on-drift`: all, or enforced (only the controls the baseline itself enforces; patch lag, pending reboot, exposure and certificates are still observed and reported)
`--fail-on-drift`	bool	—	Exit 5 when the host is drifted and 6 when its state is unknown
`--json`	bool	—	Emit the evidence as machine-readable JSON

stackkit host security verify

Observe the host security baseline and write versioned evidence. Observe every baseline control on this node and produce stackkit.host-security-evidence/v1. Nothing on the host is changed. Most controls need root to be observed; one that cannot be observed is reported unknown with the reason, not as a failure. The evidence is written to .stackkit/host-security-evidence.json in the workspace unless --no-record is given, and it expires after --freshness.

stackkit host security verify [flags]

Flag	Type	Default	Description
`--declared-port`	stringArray	—	Declared service port as tcp/443 or udp/5353 (repeatable)
`--drift-scope`	string	`all`	Controls that decide `--fail-on-drift`: all, or enforced (only the controls the baseline itself enforces; patch lag, pending reboot, exposure and certificates are still observed and reported)
`--exceptions`	string	`/etc/stackkit/host-security/exceptions.json`	Owner-controlled exceptions file (each exception needs an owner and an expiry)
`--fail-on-drift`	bool	—	Exit 5 when the host is drifted and 6 when its state is unknown
`--freshness`	duration	`15m0s`	How long the evidence may be relied on before it expires (1m to 24h)
`--host-name`	stringArray	—	Name the delivered SSH host certificate must carry (repeatable; default: the system hostname)
`--json`	bool	—	Emit the result as machine-readable JSON
`--kit`	string	—	Kit slug to record (default: the kit of the workspace StackSpec)
`--local-node`	string	—	Exact local Node in the supplied ResolvedPlan
`--management-source`	stringArray	—	Network that must always reach ssh, as a CIDR (repeatable)
`--mode`	string	`standard`	Lifecycle mode to record: standard, or advanced when Techstack manages this deployment
`--no-record`	bool	—	Do not write the evidence under .stackkit/
`--resolved-plan`	string	—	Verified canonical ResolvedPlan whose declared listeners to judge exposure against
`--site-kind`	string	—	Site kind of this host: home or cloud (default: inferred from the kit; modern-homelab needs it)

Examples

# Verify this host and record the evidence
sudo stackkit host security verify

# Machine-readable, advanced mode, exit non-zero on any drifted control
sudo stackkit host security verify --mode advanced --json --fail-on-drift

# What the Techstack host pre-step runs: only the controls the baseline enforces decide the exit code; patch lag, pending reboot, exposure and certificates are still observed and reported
sudo stackkit host security verify --mode advanced --json --fail-on-drift --drift-scope enforced

# Judge exposure against the ports the verified plan declares
sudo stackkit host security verify --resolved-plan plan.json --local-node node-1

stackkit host ssh

SSH certificate access delivered to this node.

stackkit host ssh [flags]

Subcommands: stackkit host ssh apply

stackkit host ssh apply

Apply a sealed SSH CA trust, revocation or host certificate delivery from stdin. Read one sealed ssh-ca-trust, ssh-ca-revoke or ssh-host-certificate envelope on stdin, signed by the pinned delivering authority, and apply it to this server’s sshd:

  - ssh-ca-trust installs the owner's user CA keys as TrustedUserCAKeys
    (/etc/ssh/stackkit/trusted_user_ca_keys) and one AuthorizedPrincipalsFile
    per local user (/etc/ssh/stackkit/principals/<user>). Root is never a
    target. An empty key list revokes like ssh-ca-revoke.
  - ssh-ca-revoke removes that trust. Revocations take effect at once and are
    never rolled back; one sshd cannot reload for is recorded as cleanup
    pending and finished by 'host security repair'.
  - ssh-host-certificate installs a host certificate beside the host key it
    certifies, only if it names every --host-name (default: the system
    hostname) and is currently valid.

sshd is reloaded only after ‘sshd -t’ accepts the new configuration; a change that fails is rolled back. The applied state is recorded in owner custody, so ‘host security verify’ reports drift and ‘host security repair’ reinstalls it.

stackkit host ssh apply [flags]

Flag	Type	Default	Description
`--host-name`	stringArray	—	Name a host certificate must carry as a principal (repeatable; default: the system hostname)
`--owner-approve`	bool	—	Authorize changing this server’s SSH access
`--tenant-ref`	string	—	Tenant the sealed delivery must be addressed to

Examples

sudo stackkit host ssh apply --tenant-ref "$TENANT" --owner-approve < envelope.json

stackkit host updates

Plan and apply operating-system package updates on this node. Plan and apply operating-system package updates on this Debian or Ubuntu node. The container runtime (docker.io, docker-ce*, containerd*, runc) is held: it is listed in the plan but never installed by apply, because upgrading it restarts every workload. Apply never removes packages, never runs autoremove, and never reboots; use ‘stackkit host reboot’ for that.

stackkit host updates [flags]

Subcommands: stackkit host updates apply, stackkit host updates plan

stackkit host updates apply

Install exactly the reviewed update plan. Install exactly the package set a reviewed ‘stackkit host updates plan’ reported. The pending set is simulated again first; when its digest differs from --plan-digest nothing is installed (plan_stale). apt runs non-interactively in a transient systemd unit (kombify-host-update-*), keeping existing configuration files, so a CLI or agent timeout stops only the wait and never dpkg. The result records every package’s version before and after and whether the node now requires a reboot.

stackkit host updates apply [flags]

Flag	Type	Default	Description
`--json`	bool	—	Emit the stackkit.host-maintenance/v1 result as machine-readable JSON
`--plan-digest`	string	—	Required. plan_digest of the reviewed plan (sha256:<hex>)
`--yes`	bool	—	Confirm that the planned packages may be installed

Examples

# Apply the plan you reviewed
sudo stackkit host updates apply --plan-digest sha256:<digest> --yes

stackkit host updates plan

Refresh the package index and show the pending updates. Refresh the package index and show what ‘stackkit host updates apply’ would install. The result lists every pending package with its current and new version, the held container-runtime packages, packages apt keeps back, whether a reboot is likely (kernel, C library or systemd), and dpkg problems. plan_digest binds the exact package set; apply refuses when it no longer matches.

stackkit host updates plan [flags]

Flag	Type	Default	Description
`--json`	bool	—	Emit the stackkit.host-maintenance/v1 result as machine-readable JSON

Examples

# Show the pending updates of this node
sudo stackkit host updates plan

# Machine-readable plan with its plan_digest
sudo stackkit host updates plan --json

Get started

Get help

Guides

Reference

stackkit host attach-conformance

stackkit host conformance

stackkit host delivery

stackkit host delivery detach

stackkit host delivery recipient

stackkit host delivery status

stackkit host environment

stackkit host gpu-check

stackkit host migrate-browser-ca

stackkit host preflight

stackkit host prepare

stackkit host reboot

stackkit host remediate

stackkit host security

stackkit host security repair

stackkit host security status

stackkit host security verify

stackkit host ssh

stackkit host ssh apply

stackkit host updates

stackkit host updates apply

stackkit host updates plan

​stackkit host attach-conformance

​stackkit host conformance

​stackkit host delivery

​stackkit host delivery detach

​stackkit host delivery recipient

​stackkit host delivery status

​stackkit host environment

​stackkit host gpu-check

​stackkit host migrate-browser-ca

​stackkit host preflight

​stackkit host prepare

​stackkit host reboot

​stackkit host remediate

​stackkit host security

​stackkit host security repair

​stackkit host security status

​stackkit host security verify

​stackkit host ssh

​stackkit host ssh apply

​stackkit host updates

​stackkit host updates apply

​stackkit host updates plan

stackkit host attach-conformance

stackkit host conformance

stackkit host delivery

stackkit host delivery detach

stackkit host delivery recipient

stackkit host delivery status

stackkit host environment

stackkit host gpu-check

stackkit host migrate-browser-ca

stackkit host preflight

stackkit host prepare

stackkit host reboot

stackkit host remediate

stackkit host security

stackkit host security repair

stackkit host security status

stackkit host security verify

stackkit host ssh

stackkit host ssh apply

stackkit host updates

stackkit host updates apply

stackkit host updates plan