Gubernator API Reference

Gubernator provides a complete REST API with auto-generated Swagger documentation. All API calls on port 4000 require a Bearer token header.

Authentication

curl -H "Authorization: Bearer <GBNT_API_TOKEN>" http://localhost:4000/v1/node/ls

Set GBNT_API_TOKEN as an environment variable when starting the Manager (default: admin).

Interactive Swagger UI

While ./gbnt serve is running:

http://localhost:4002/swagger/index.html

---

Endpoints

Cluster & Nodes

| GET | /api/node/join-info | Get Manager IP, join tokens, public key, and formatted join commands | | GET | /join.sh (or /api/node/join.sh) | Standalone bash installer script for automated worker join | | POST | /api/node/add | Remote SSH provisioning with multi-auth (password, private key, manager key) and live step logs | | GET | /v1/node/ls | List all registered nodes | | GET | /v1/node/{id} | Inspect a specific node | | POST | /v1/node/join | Register a new worker node | | POST | /v1/node/heartbeat | Worker heartbeat ping | | POST | /v1/node/{id}/role | Promote or demote a node | | POST | /v1/node/{id}/availability | Set node state (active/pause/drain) | | POST | /v1/node/{id}/sync-token | Synchronize API tokens to worker host via SSH | | POST | /v1/node/{id}/leave | Remove a node from the cluster | | GET | /v1/cluster/token | Get the join token |

Stacks

Method	Endpoint	Description
POST	/v1/stack/deploy	Deploy a Compose stack
GET	/v1/stack/ls	List all stacks
GET	/v1/stack/{id}/services	List services for a stack
DELETE	/v1/stack/{id}	Delete stack + stop containers

Services

Method	Endpoint	Description
GET	/v1/service/ls	List all services
GET	/v1/service/{id}/tasks	List tasks for a service
POST	/v1/service/{id}/scale	Scale service replicas
DELETE	/v1/service/{id}	Remove a service

Tasks

Method	Endpoint	Description
GET	/v1/task/ls	List all tasks
GET	/v1/node/tasks/{node_id}	Fetch pending tasks for a worker node
POST	/v1/node/tasks/{task_id}/status	Worker reports task status
DELETE	/v1/task/{id}	Remove a task record

Caddy Subsystem

Method	Endpoint	Description
GET	/v1/caddy/status	Get Caddy process info, uptime, memory & instance counts
GET	/v1/caddy/routes	Get active reverse proxy route matrix and upstream health
GET	/v1/caddy/certs	Get managed TLS certificates with full X.509 metadata
GET	/v1/caddy/certs/download	Download domain-specific .crt / .pem certificate
GET	/v1/caddy/certs/inspect	Inspect complete X.509 properties and SHA-256 fingerprint
POST	/v1/caddy/certs/renew	Force immediate renewal and rotation of a domain certificate
POST	/v1/caddy/certs/custom	Upload and install a custom TLS certificate and private key
POST	/v1/caddy/certs/sync	Broadcast and synchronize all certificates across all active cluster nodes
DELETE	/v1/caddy/certs/orphaned	Prune orphaned certificates no longer in any Caddyfile
GET	/v1/caddy/ca.crt	Download Caddy internal Root CA certificate (root.crt)
GET	/v1/caddy/logs	Stream/tail container access log output
GET	/v1/caddy/metrics	Get Prometheus metrics (request count, RPS, latency percentiles)

Image Security, SBOM & Auto-Remediation

Method	Endpoint	Description
GET	/v1/security/scans	List all container vulnerability scan reports across cluster
GET	/v1/security/scans/{id}	Inspect vulnerability CVE list and CVSS scoring for an image
POST	/v1/security/scans/trigger	Trigger immediate CVE scan for a container image
POST	/v1/security/scans/sync-all	Re-scan and synchronize all container images deployed in the cluster
GET	/v1/security/sbom	Export Software Bill of Materials (CycloneDX JSON / SPDX JSON)
GET	/v1/security/keys	List trusted Cosign ECDSA public signing keys
POST	/v1/security/keys/generate	Generate in-cluster ECDSA P-256 signing keypair
POST	/v1/security/sign	Cryptographically sign image digest
GET	/v1/security/policy	Get active admission gatekeeper security policy
POST	/v1/security/policy	Update admission gatekeeper security policy
GET	/api/security/remediate/preview	Preview upgrade candidate versions, risk assessment, and affected stacks
POST	/api/security/remediate	Apply atomic image upgrade in a stack with safe automated rollback protection
POST	/v1/caddy/fmt	Format Caddyfile via caddy fmt

---

Stack Deploy Payload

{
  "name": "mystack",
  "compose_raw": "services:\n  web:\n    image: nginx:alpine\n    ports:\n      - \"8080:80\"\n    deploy:\n      replicas: 1\n"
}

The compose_raw field accepts the full YAML content of a docker-compose.yml file. Gubernator parses:

• services.<name>.image
• services.<name>.ports
• services.<name>.environment
• services.<name>.volumes
• services.<name>.command
• services.<name>.deploy.replicas
• services.<name>.deploy.placement.constraints

---

Task Status Update Payload

Workers call this endpoint after starting a container:

{
  "status": "running",
  "container_ip": "172.17.0.5",
  "container_name": "gbnt-550e8400-e29b"
}

---

Example: Deploy via curl

COMPOSE=$(cat examples/example-wordpress/docker-compose.yml)

curl -s -X POST http://localhost:4000/v1/stack/deploy \
  -H "Authorization: Bearer admin" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"wp\", \"compose_raw\": $(echo "$COMPOSE" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}"