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 reachable Linux server
  • SSH access to that server
  • Dashboard access

​
Workflow

1
Open the Nodes page and generate the install command.
2
Run the command on the target machine to install and start the agent.
3
Wait for the node heartbeat and readiness checks to populate in the dashboard.
4
Review health, agent version, runtime readiness, and any maintenance state before using the node.

​
What “healthy” means before you use it

A node has to do more than appear in the list. StackShift waits for a fresh heartbeat and readiness signals — CPU, memory, disk, Docker, and Caddy — before it treats the node as healthy and schedulable. Place workloads only once it 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, or AWS account from the Nodes page. StackShift bootstraps the machine, installs the agent, and waits for heartbeat — after which it behaves like any other node.

​
Expected result

The node appears healthy and can accept placements.

​
Common failures

  • Install token expired or invalid
  • Agent service not running on the node
  • Node appears but stays agent unknown or disconnected

Install the agent

Bootstrap a new node and understand what the install command is doing on the target host.

Node overview

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

BYOCloud overview

Connect customer-owned cloud accounts to StackShift, provision cloud-backed nodes, and operate them through the same node workflows used elsewhere in the product.