Configuration

Super uses TOML (Tom’s Obvious, Minimal Language) for configuration. The daemon reads $SUPER_ROOT/conf/super.toml; SUPER_ROOT defaults to the directory containing the bin/ next to the superd executable, or the current working directory (see Config Reference — Instance layout and Environment Variables). The CLI’s offline tools (super check) additionally probe super.toml, conf/super.toml, and /etc/super/super.toml.

Server Configuration

The [server] section controls the superd daemon itself. Example from conf/super.toml:

# conf/super.toml

[server]
# The IP and port for the API and Dashboard
host = "127.0.0.1"
port = 9002

# Optional: enable admin Bearer auth (required for non-loopback binds)
# auth_secret = "your-own-long-random-string"

# Graceful shutdown timeout (seconds)
shutdown_timeout = 10

# Flapping detection (e.g., max 5 restarts in 60 seconds)
flapping_window = 60
flapping_threshold = 5

# Self-daemonize (Unix only). Keep false under systemd/Docker.
# CLI overrides: --daemon / --foreground. See Config reference.
# daemon = false
# pidfile = "run/superd.pid"   # default when daemonizing; relative to SUPER_ROOT

[logging]
# Daemon's own log level (debug, info, warn, error)
log_level = "info"

OSS security defaults (fail-closed)

Super defaults to restrictive, fail-closed behaviour in OSS. You can opt into broader exposure, but the daemon will not silently widen the attack surface:

See Authentication and SECURITY.md for the full OSS security model.

Data Storage & Event Retention

The [storage] section controls where Super keeps its data files. Example from conf/super.toml:

# conf/super.toml — [storage]
[storage]
data_file = "./data/snapshot.json"  # runtime program snapshot
events_file = "./data/events.db"    # SQLite event history (default)
events_keep_days = 30               # prune events older than 30 days; 0 = keep everything

• Event history is written to events_file (SQLite, WAL mode). Default retention is 30 days (events_keep_days); set 0 to keep everything. Pruning runs once per day.
• data_file is the program snapshot persisted at runtime — see Snapshot persistence & restore.
• Relative paths resolve under SUPER_ROOT. Full key reference: Config reference — [storage].

Program Configuration

Programs are not declared in super.toml. Define them via stack files, the API, or the CLI — Super persists them to data/snapshot.json and reloads them on start.

Stack files (declarative, TOML default)

Point super.toml at your stack directory once with [include].files (a glob list of stack files):

# super.toml
[include]
files = ["conf/conf.d/*"]

Stack files are TOML by default (.toml or no extension); legacy .json stacks keep working. Then create files under conf/conf.d/ — each file is a stack applied on daemon start and on super reload:

# conf/conf.d/my-worker.toml
prune = false

[[services]]
name = "my-worker"
command = "/usr/local/bin/worker"
args = ["--config", "/etc/worker.conf"]
cwd = "/tmp"
autostart = true

prune = false (the default when omitted) never removes programs. prune = true removes every managed program that is not listed in the stack — keep it false unless the file is the complete desired inventory. See Declarative stacks.

Environment Variables

You can inject environment variables into the process. Example file conf/conf.d/my-worker.json:

{
  "services": [
    {
      "name": "my-worker",
      "command": "./app",
      "env": {
        "NODE_ENV": "production",
        "DB_HOST": "10.0.0.5"
      }
    }
  ]
}

User & Group

If running as root, you can drop privileges to a specific user. Example: services[] entry in a stack file (conf/conf.d/*.json or *.toml):

{
  "services": [
    {
      "name": "safe-service",
      "command": "./app",
      "user": "www-data"
    }
  ]
}

Advanced Settings (OSS)

Dependency orchestration — the depends_on array names programs that must be Healthy first. Example: services[] entry in a stack file:

{
  "services": [
    { "name": "database", "command": "./db", "health_check": { "type": "tcp", "port": 5432 } },
    { "name": "heavy-job", "command": "./processor", "depends_on": ["database", "redis"] }
  ]
}

Unknown names are rejected when the config is submitted (depends_on: unknown service(s): …), and so are configurations that would close a dependency cycle (depends_on: dependency cycle detected involving: …). A dependency that exists but is not yet healthy keeps the dependent in WAITING until it turns Healthy — see Health Checks.

Plugin-only blocks 💎

The following require licensed plugins (resource limits on Linux). OSS accepts resource_limits in the API schema but does not enforce them without the matching plugin. Example: services[] entry in a stack file:

{
  "services": [
    {
      "name": "heavy-job",
      "command": "./processor",
      "resource_limits": {
        "memory_limit": 512,
        "cpu_quota": 0.5
      }
    }
  ]
}

Scheduled tasks

Cron scheduling is built into OSS superd. See Scheduled Tasks. Example: services[] entry in a stack file:

{
  "services": [
    {
      "name": "nightly-backup",
      "command": "/scripts/backup.sh",
      "cron": "0 0 2 * * *"
    }
  ]
}

See Resource Isolation and Scheduled Tasks.

OTA artifact

Per-program binary updates use an artifact block on the stack entry / API payload — not keys under [server] in super.toml. Optional timeouts default to 60 seconds:

Full field list and examples: Config reference — artifact · Atomic OTA Updates.

Restart & stop behaviour

Supervisor-compatible restart and stop settings. Example: services[] entry in a stack file:

{
  "services": [
    {
      "name": "api-server",
      "command": "/usr/local/bin/api",
      "autostart": true,
      "autorestart": "unexpected",
      "exitcodes": [0],
      "retry_limit": 3,
      "startsecs": 10,
      "stopsecs": 30,
      "priority": 100
    }
  ]
}

For a full list of options, see the Config Reference. Cron scheduling: Scheduled Tasks.