> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your first node

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

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## 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

<Steps>
  <Step>
    Open the Nodes page and generate the install command.
  </Step>

  <Step>
    Run the command on the target machine to install and start the agent.
  </Step>

  <Step>
    Wait for the node heartbeat and readiness checks to populate in the dashboard.
  </Step>

  <Step>
    Review health, agent version, runtime readiness, and any maintenance state before using the node.
  </Step>
</Steps>

## 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

<Check>
  The node appears healthy and can accept placements.
</Check>

## Common failures

<Warning>
  * Install token expired or invalid
  * Agent service not running on the node
  * Node appears but stays agent unknown or disconnected
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Install the agent" href="/nodes/install-the-agent">
    Bootstrap a new node and understand what the install command is doing on the target host.
  </Card>

  <Card title="Node overview" href="/nodes/node-overview">
    What a node is, what the agent does, and what node health means in StackShift.
  </Card>

  <Card title="BYOCloud overview" href="/nodes/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.
  </Card>
</CardGroup>