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

# How StackShift works

> A product-level walkthrough of how the control plane, worker, agent, and runtime hosts cooperate.

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

## Goal

Show the end-to-end flow from dashboard action to runtime state.

## Prerequisites

* Understand the core concepts

## Workflow

<Steps>
  <Step>
    A dashboard action creates a control-plane request for a build, deploy, restore, or upgrade.
  </Step>

  <Step>
    The control plane persists state and coordinates worker-side or node-side actions.
  </Step>

  <Step>
    The agent receives runtime instructions on the target node and applies them to local services.
  </Step>

  <Step>
    Operations and resource detail views surface the resulting health, logs, and recovery state.
  </Step>
</Steps>

## The pieces

* Control plane: the API and the source of truth for your resources and their state.
* Workers: background processors that run builds, provision databases, meter billing, and run backups.
* Agent: runs on each node, executes runtime instructions, runs your containers, and serves ingress through Caddy.
* Nodes: the runtime hosts where workloads actually run.

## A deploy, end to end

* A dashboard action creates a control-plane request.
* For source deploys, a build runs (BuildKit) and the resulting image is pushed to the registry.
* The control plane places the workload on a healthy node and instructs that node’s agent.
* The agent pulls and runs the workload and Caddy routes the domain to it.
* Operations and resource detail views surface the resulting health, logs, and recovery state.

## Where a failure lives

Because each stage is distinct, a failure has an address. A build error is a worker/build problem; a workload that builds but will not place is a control-plane/placement problem; a placed workload that never reports healthy is usually an agent or runtime problem on the node. Knowing which stage failed tells you which page to open.

## Expected result

<Check>
  You can reason about where a failure occurred: control plane, worker, node agent, or workload runtime.
</Check>

## Common failures

<Warning>
  * Agent unreachable
  * Placement blocked
  * Backup storage unavailable
  * Template upgrade blocked by drift
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Connect your first node" href="/getting-started/connect-your-first-node">
    Bootstrap a Linux host into StackShift and verify it is healthy enough to host workloads.
  </Card>

  <Card title="Operations overview" href="/operations/operations-overview">
    The operations area is the cross-resource health and runtime visibility surface for StackShift.
  </Card>

  <Card title="Recovery states, logs, and troubleshooting" href="/operations/recovery-logs-and-troubleshooting">
    Read the operation state on a resource — its status, current step, attempt count, retryable flag, and last error — together with logs, instead of treating a single “error” badge as the whole story.
  </Card>
</CardGroup>