Skip to content

Host Agent API & Schema Reference

The StackPilot agent runs on port 9091 over HTTPS with self-signed TLS.

1. Authentication

Every request to the Host Agent requires the X-Agent-Token header:

GET /api/status HTTP/1.1
Host: 127.0.0.1:9091
X-Agent-Token: <your-agent-token>

Requests lacking this header or providing an invalid token receive a 401 Unauthorized response.

2. Agent Endpoints

GET /api/status

Returns complete host telemetry, container inventory, pods, and Quadlet units.

  • Sample Response: 
    {
  "agent": {
    "version": "0.9.8",
    "engine": "podman",
    "scope": "user"
  },
  "host": {
    "hostname": "node-01",
    "uptime_seconds": 184200,
    "cpu": { "percent": 14.2 },
    "memory": { "used_bytes": 4294967296, "total_bytes": 17179869184 }
  },
  "pods": [
    {
      "Name": "arrstack",
      "Status": "Running",
      "Containers": [
        { "Names": "sonarr", "Status": "running" },
        { "Names": "radarr", "Status": "running" }
      ]
    }
  ],
  "services": [
    {
      "id": "nextcloud.service",
      "active_state": "active",
      "sub_state": "running"
    }
  ]
}

POST /api/action

Executes an operational state transition on a workload.

  • Payload: 
    {
  "target": "pod|container|service",
  "name": "arrstack",
  "action": "start|stop|restart|remove"
}

POST /api/critical-check

Called by the local self-heal watchdog timer (stackpilot-agent-self-heal.timer) every 60 seconds.

  • Payload: {}
  • Behavior: Verifies that the internal event loop and systemd connections are healthy. If degraded, the self-heal shell script restarts stackpilot-agent.service.

GET /api/apps/config?name=:name

Reads configuration files (e.g. .env, .container, .yaml) for a specific managed stack within canonical path jail limits.

POST /api/apps/deploy

Writes updated Quadlet unit files atomically and triggers systemctl --user daemon-reload.