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

​
Goal

Attach your first node and get it to a schedulable state.

​
Prerequisites

  • A qualified Ubuntu 22.04/24.04 or Debian 12 host on amd64/arm64
  • Root access or verified SSH access
  • Dashboard access

​
Workflow

1
Open the Nodes page and create a ten-minute, single-use enrollment.
2
Run the signed command manually, or use SSH assistance with an exact host-key fingerprint.
3
Wait for signed bootstrap, mTLS identity, WireGuard, heartbeat, and runtime readiness.
4
Review every readiness stage before using the node.

​
What “healthy” means before you use it

A node has to do more than appear in the list. StackShift verifies the single-use exchange, exact SPIFFE certificate identity, WireGuard handshake, overlay-only agent listener, fresh sequenced heartbeat, runtime, Node Guard, and Caddy before it becomes schedulable. Place workloads only once every stage reports healthy.

​
Don’t have a server? Use BYOCloud

If you do not want to bring your own Linux host, BYOCloud provisions a node in your own Hetzner, DigitalOcean, AWS, or Azure account from the Nodes page. StackShift verifies provider identity, establishes WireGuard and mTLS, and waits for the first authenticated heartbeat.

​
Expected result

The node appears healthy and can accept placements.

​
Common failures

  • Enrollment ticket expired, was already consumed, or exceeded its attempt limit
  • Signed manifest, host profile, target, or artifact digest was rejected
  • WireGuard route conflicts with an existing network
  • Agent service not running on the node
  • Node appears but stays agent unknown or disconnected

Install the agent

Enroll a qualified Linux host with a ten-minute single-use ticket, signed bootstrap artifacts, WireGuard, and a rotating mTLS node identity.

Node overview

What a node is, what the agent does, and what node health means in StackShift.

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.