Declarative Stacks

Managing servers imperatively (e.g., typing super start commands manually) works for small setups, but it leads to Configuration Drift at scale. You forget which arguments you used last week, or someone else changes a setting without documenting it.

Super supports a Declarative approach, similar to kubectl apply or docker-compose up. You define the desired state of the entire system, and Super converges to that state.

The Concept: “Apply”

Instead of managing individual processes, you define a Stack (a list of all services) in a file. Stack files are TOML by default (.toml or no extension); legacy JSON stacks (.json) keep working and can be mixed in the same [include] glob.

When you run super apply stack.toml, Super will:

1. Create new services that are in the file but not in the system.
2. Update existing services if their configuration (args, env, etc.) has changed.
3. Prune (Remove) services that are running in the system but missing from the file — only if prune = true.

One TOML note: structured values such as health_check or artifact can be written either as an inline table — health_check = { type = "tcp", port = 8080 } — or as a nested table ([services.health_check] / [services.artifact]). Only [[array.of.tables]] syntax is rejected for tagged values. The type field selects the probe kind (tcp / http / exec). Per-program OTA fields (source, checksum, destination, extract, restart_policy, download_timeout, verify_timeout): Config reference — artifact and Atomic OTA Updates.

Workflow Example

1. Define the Stack

Create a file named prod-stack.toml. This can be generated by your CI/CD system or managed in Git.

# prod-stack.toml
prune = false

[[services]]
name = "redis-cache"
command = "/usr/bin/redis-server"
autostart = true

[[services]]
name = "backend-api"
command = "/usr/local/bin/api"
env = { PORT = "8080" }
depends_on = ["redis-cache"]
health_check = { type = "tcp", port = 8080 }

2. Apply the Stack

Run the apply command via the CLI.

$ super apply prod-stack.toml

Applying stack from "prod-stack.toml"...
- Creating service: redis-cache
- Updating service: backend-api
- Pruning service: old-worker (not in stack)
Stack applied successfully.

JSON Stacks (Legacy)

JSON stack files remain fully supported — useful when your stack is generated by tooling rather than edited by hand. The API accepts JSON bodies (POST /api/v1/stack), and super export still emits JSON. Example file prod-stack.json:

{
  "prune": false,
  "services": [
    {
      "name": "redis-cache",
      "command": "/usr/bin/redis-server",
      "autostart": true
    }
  ]
}

Format is chosen by file extension: .json → JSON, everything else → TOML.

CI/CD Integration

This feature makes Super ideal for GitOps.

1. Commit your stack to a Git repository — either stack.toml (default) or stack.json (legacy), both are accepted by the API.

2. Configure a GitHub Action / GitLab Runner.

3. On push to main, the runner executes:

   TOML (use --data-binary — plain -d strips newlines and breaks multi-line TOML):

   curl -X PUT http://prod-server:9002/api/v1/stack \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/toml" \
     --data-binary @stack.toml

   JSON (no special header needed — JSON is the default body type; -d works fine):

   curl -X PUT http://prod-server:9002/api/v1/stack \
     -H "Authorization: Bearer $TOKEN" \
     -d @stack.json

   Or use the CLI against the daemon (same files, no curl headers):

   super apply stack.toml
   # or
   super apply stack.json

Exporting Current State

If you have manually configured a server and want to capture its state into a file, you can use the export command. TOML is the default output — the same format super apply / [include] expect:

$ super export > current-stack.toml

This generates a valid TOML stack file representing the currently running system, which you can then check into version control.

To emit the legacy JSON shape instead (for tooling that expects it), pass --format json:

$ super export --format json > current-stack.json

Either output round-trips: super apply current-stack.toml (or dropping it into conf/conf.d/) re-creates the same programs.

Snapshot vs. Stack

Besides stacks, Super also persists every program’s runtime state to data/snapshot.json (with automatic .bak rotation). Stack files are the desired state; the snapshot is the runtime truth — so for same-host disaster rollback, restoring snapshot.json directly is byte-exact, while cross-host migration usually goes through export/apply. For the full comparison and how [include] stacks interact with both, see Snapshot Persistence & Restore.