Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Install a node without creating a reusable agent credential or exposing the agent listener to the public internet.

​
Prerequisites

  • Ubuntu 22.04/24.04 or Debian 12 on amd64/arm64
  • Root access for manual installation or verified SSH access
  • Outbound HTTPS and UDP access
  • Dashboard access

​
Workflow

1
Create a ten-minute, single-use enrollment from Nodes → Connect server.
2
Run the signed command manually, or use SSH assistance with the exact server host-key fingerprint.
3
Follow bootstrap, overlay, certificate, and heartbeat readiness in the dashboard.
4
Place workloads only after the node is healthy and schedulable.

​
Qualified host matrix

  • Ubuntu 22.04 LTS: amd64 and arm64
  • Ubuntu 24.04 LTS: amd64 and arm64
  • Debian 12: amd64 and arm64
  • The bootstrap executable rejects every OS or architecture outside this signed matrix before changing the host.

​
Create and protect the enrollment

The enrollment response contains the pending node, exact expiration time, and generated command. The ticket appears only inside that command. StackShift stores only its SHA-256 hash together with node, tenant, operation, expiry, attempt limit, and consumed time.
  • Copy or run the command before the displayed ten-minute expiry.
  • A successful exchange consumes the ticket exactly once.
  • Create a new enrollment instead of retrying an expired or consumed command.
  • No durable agent password, bearer token, or global registry credential is returned.

​
Manual and SSH-assisted paths

  • Manual installation runs the generated command directly on the target host.
  • SSH assistance requires hostname, username, exact host-key fingerprint, and either a password or private key.
  • SSH credentials remain only in bounded request memory, are redacted from logs and streamed output, and are cleared from browser state after completion.
  • A missing or mismatched fingerprint stops the flow before credentials are sent.
  • Both paths execute the same signed bootstrap and enrollment exchange.

​
Signed bootstrap and idempotent runtime

Bootstrap verifies the Ed25519 release authority, signed manifest, exact Linux target, supported host profile, immutable release ID, and SHA-256 of every executable before installation. Every bootstrap binary, manifest, signature, host profile, and runtime artifact is fetched from /api/v1/bootstrap/{release}/.... The release segment is the exact deployed image tag, is present in both signed manifests and signed host profiles, and makes one-year immutable caching safe. A profile or manifest from another release is rejected even when its signature is otherwise valid.
  • Installs the qualified container runtime, Caddy, StackShift agent, Node Guard, WireGuard, and nftables policy.
  • Installs systemd units and the A/B release manager from the signed host profile.
  • Uses pinned package authorities, keys, and exact versions.
  • The signed profile references the same agent and Node Guard bytes bound by the canonical distribution manifest; deployment aborts if either checksum differs.
  • Preserves customer firewall rules while blocking public agent access.
  • Running the same qualified release repairs drift without creating a second identity.
  • Never remove the release segment, substitute latest, or mirror files under a mutable URL.

​
Node-generated identity and overlay

The node generates its mTLS private key, CSR, WireGuard private key, and WireGuard public key locally. Only the CSR and public key leave the host.
  • The exchange issues a 24-hour certificate for the exact tenant and node and returns the online intermediate chain.
  • Overlay addresses are allocated transactionally from the production CIDR.
  • The agent binds TCP 8443 only to its overlay address.
  • StackShift verifies the WireGuard handshake and certificate identity before scheduling.
  • Certificates rotate before eight hours remain; the previous certificate has only a short in-flight overlap.
  • On StackShift’s control plane, enrolled peers are added to the existing management WireGuard interface. The interface itself and pre-existing management peers are not regenerated or removed.

​
Registry authorization

The node authenticates to the registry gateway with its certificate and receives a 15-minute, pull-only grant for immutable image digests assigned to that node. Global registry credentials and mutable-tag grants are not exposed.

​
Readiness checks

  • Enrollment consumed exactly once
  • Overlay allocated with no route collision and a fresh WireGuard handshake
  • mTLS identity matches the displayed node
  • Node Guard, Caddy, and the container runtime are ready
  • The first monotonically sequenced heartbeat is accepted
  • Node status is healthy and schedulable

​
Expected result

The node has an exact SPIFFE-style identity, a fresh WireGuard handshake, an overlay-only agent listener, and a healthy authenticated heartbeat.

​
Common failures

  • Enrollment ticket expired, was consumed, or exceeded its bounded attempt count
  • Signed manifest, host profile, target, release authority, or artifact digest was rejected
  • SSH host-key fingerprint differs from the server
  • The overlay route collides with an existing host, VPN, or workload route
  • Certificate time or WireGuard handshake is stale

Connect your first node

Bootstrap a Linux host into StackShift and verify it is healthy enough to host workloads.

Node health, diagnostics, and deletion

Interpret overlay, mTLS, heartbeat, runtime, operation, inventory, and explicit deletion-blocker state before taking action.

BYOCloud overview

Provision nodes in your own cloud account with scoped or federated access, durable operations, signed enrollment, private agent networking, and provider-confirmed cleanup.