Skip to content

60-Second Quickstart

Get StackPilot running and manage your first host in under two minutes.

1. Deploy the Central Hub

The Central Hub is distributed as a self-extracting executable archive. Copy it to your management server (or homelab controller):

chmod +x stackpilot-0.9.8.run
./stackpilot-0.9.8.run install

./stackpilot-0.9.8.run install --config ~/.config/stackpilot/hub.json

# If the Hub server itself should not run a local monitoring agent
./stackpilot-0.9.8.run install --skip-local-agent

The installer starts the Hub service listening on https://<hub-host>:8081.

Initial Admin Account

Upon visiting the dashboard for the first time, you will be prompted to create your initial admin account. Additional accounts with operator or viewer roles can be configured from Settings.

2. Onboard a Managed Node

To connect a Linux host to StackPilot:

  1. Open the Hub web console at https://<hub-host>:8081.
  2. Click Add Host in the top navigation bar.
  3. Choose the target runtime engine:
  4. Podman (Rootless) (Recommended): Installs under the current Linux user account.
  5. Docker (System Mode): Installs as a systemd system service with Docker socket access.
  6. Copy the generated enrollment command and run it on the target machine:
curl -fsSL https://<hub-host>:8081/api/agents/install.sh?ip=192.168.1.100 \
  -H "Authorization: Bearer <enrollment-token>" | bash

sequenceDiagram
    autonumber
    participant Target as Managed Host
    participant Hub as Central Hub
    Target->>Hub: GET /api/agents/install.sh
    Hub-->>Target: Return Rendered Installer Script
    Target->>Target: Generate local TLS Key & Certificate
    Target->>Hub: POST /api/agents/fingerprint (SHA-256 Registered)
    Hub-->>Target: Return Rotated Runtime Token
    Target->>Target: Configure systemd user service & self-heal timer
    Target->>Target: systemctl --user start stackpilot-agent.service
    Target->>Hub: Heartbeat Active & Metrics Online

3. Verify Node Connectivity

Once installed, the agent automatically starts and reports health back to the Central Hub:

# Check agent status on the managed host
systemctl --user status stackpilot-agent.service

# Check watchdog self-heal timer
systemctl --user list-timers stackpilot-agent-self-heal.timer

In the Central Hub dashboard, the new host will appear in the sidebar with live CPU, memory, and container workload status!