Config Reference

Edition legend

Mark	Meaning
💎 Subscription	Requires valid `[license].key` in `conf/super.toml` and matching authorized plugin libraries. Single-admin core auth and the embedded Dashboard are OSS (no 💎).
(no mark)	Available in OSS (with or without plugins).

Free 90-day trial

Licensed plugins (Super Pro) are available with a free 90-day trial license (Portal claim). See the feature matrix. Day-to-day auth and Dashboard: Essentials. Licensed plugins: Advanced Management.

Licensed-plugin fields in this reference (quick index):

Location	Keys / file
`[server]`	`auth_secret` — OSS core auth or licensed `security` bootstrap (💎 required when licensed)
`[license]`	`key` 💎 — cryptographically signed subscription token from your vendor
`conf/conf.d/` (program stacks)*	`services[].resource_limits` (`cpu_quota`, `memory_limit`, `memory_warn_percent`, `memory_warn_headroom`, `memory_high`) 💎
`conf/notify.toml` (separate file)	`[[channels]]` 💎 — see Event Notifications

Note

See Configuration — OSS security defaults for fail-closed bind, log path confinement, and other defensive defaults.

Instance layout (`SUPER_ROOT`)

The instance root is resolved from SUPER_ROOT first, then the binary’s directory layout, then the working directory — see Environment Variables.

Path	Purpose
`conf/super.toml`	Daemon settings (this file)
`conf/notify.toml`	Licensed notify plugin config (optional)
`data/`	Persisted registry / auth state
`data/tokens.json`	💎 Access Token records (`security` plugin).
`data/auth_settings.json`	💎 `security` plugin: currently `auth_secret_disabled` (turn off bootstrap `auth_secret` login).
`logs/`	Daemon (`app.log`) and child process logs
`run/`	Runtime files; default pidfile `run/superd.pid` when self-daemonizing
`plugins/`	Licensed `.so` / `.dylib` libraries

`[server]`

Global settings for the daemon.

Key	Type	Default	Description
`auth_secret`	string	—	Admin Bearer secret. Non-empty enables OSS core auth. Required for non-loopback TCP binds (unless `security` is active). Licensed 💎: also required for `security` plugin startup / bootstrap; Admins may later disable login with it after creating an Admin Access Token. Top-level `auth_secret` keys are rejected (must live here under `[server]`).
`host`	string	`127.0.0.1`	Bind address for API and Dashboard.
`port`	int	`9002`	Bind port.
`shutdown_timeout`	int	`10`	Seconds to wait for SIGTERM before SIGKILL during shutdown.
`flapping_window`	int	`60`	Time window (seconds) to detect restart loops.
`flapping_threshold`	int	`5`	Max restarts allowed within the window.
`enable_docs`	bool	`false`	Enable Swagger UI (`/api/docs`) when the binary is built with the docs feature.
`daemon`	bool	`false`	Unix only: self-daemonize after start (like nginx `daemon on`). Keep `false` under systemd/Docker (`Type=simple` / PID 1). CLI: `--daemon` / `--foreground` override this.
`pidfile`	string	—	Optional pidfile path. Relative paths resolve under `SUPER_ROOT`. When daemonizing and unset, defaults to `run/superd.pid`. Foreground writes a pidfile only when this (or `--pidfile`) is set. CLI: `--pidfile`.
`socket`	string	—	Optional Unix socket endpoint for the API, e.g. `socket = "run/superd.sock"`. Relative paths resolve under `SUPER_ROOT`; absolute paths are used as-is. Unix only (macOS/Linux). When set, the daemon listens on both TCP and the socket unless `socket_only = true`. The socket file is created with `socket_mode` permissions (default `0600`, owner only) and removed on clean shutdown.
`socket_mode`	string	`0600`	Unix socket file permission mode as an octal string (`0600` = owner read/write, `0660` = owner + group, `0640` = owner read/write + group read). World-writable modes (`0666`) are refused — a world-writable socket would let any local user drive the control API.
`socket_only`	bool	`false`	When `true`, bind only the Unix socket and skip the TCP listener entirely (zero network exposure). Requires `socket` to be set. The non-loopback bind check no longer applies because no TCP port is opened.
`request_timeout_secs`	int	`30`	Whole-request wall-clock budget for the API in seconds. A request that does not finish in time is answered with `408` (`{"status":"error","message":"request timeout"}`). `0` disables the limit. Plugin HTTP hooks carry their own tighter 10-second budget inside this. Note for control routes (`/stop`, `/system/shutdown`, …): a `408` means the response timed out, not that the operation failed — stop/shutdown work continues in the background; re-query status instead of retrying the request.

# super.toml — [server]
[server]
# Enable API auth (required when binding beyond loopback):
# auth_secret = "your-own-long-random-string"

# Optional self-daemonize when not using systemd/Docker:
# daemon = true
# pidfile = "run/superd.pid"   # default when daemonizing

# Optional wall-clock budget for API requests (seconds, 0 = disabled):
# request_timeout_secs = 30

# Optional Unix socket endpoint (default 0600, owner-only):
# socket = "run/superd.sock"
# socket_mode = "0600"   # "0600" | "0640" | "0660" — never world-writable
# socket_only = true     # disable the TCP listener entirely

# CLI: super --server unix:///path/to/superd.sock list

`[license]` — subscription key (Licensed 💎)

Optional section in conf/super.toml. When present and valid, superd loads authorized plugins from plugins/ and requires the bundled security plugin (security.so + auth_secret) or refuses startup. See Licensed deployments require security.

When a key is present but does not verify, behavior depends on deployment signals:

Condition	Invalid key behavior
Loopback OSS dev (no plugins, no `auth_secret`)	Degrade to OSS with stderr/tracing warnings
Licensed intent (plugins on disk, `auth_secret` set, or non-loopback bind)	Refuse startup
`[license].strict = true` (or `SUPER_LICENSE_STRICT=1`)	Refuse startup always

The SUPER_LICENSE and SUPER_LICENSE_STRICT overrides are documented in Environment Variables.

Key	Type	Default	Description
`key` 💎	string	—	Base64-encoded signed subscription key. Obtain from your subscription vendor. Override: `SUPER_LICENSE` env (same format). Every valid license includes a signing key id (`kid`, e.g. `k_<8hex>`) that must match a verifying key embedded in your `superd` build — see Troubleshooting license verification.
`strict` 💎	bool	`false`	When `true`, invalid or incompatible keys refuse startup instead of degrading to OSS. Recommended for production licensed deployments. Override: `SUPER_LICENSE_STRICT=1`.

# super.toml — [license]
[license]
strict = true
key = "eyJjbGFpbXMiOnsiaXNzdWVkX3RvIjoi..."

`[storage]` / `[logging]` / `[child_logging]`

See Configuration and Logging for examples. Keys mirror ServerConfig in common/src/config.rs.

`[storage]` — data paths & event retention

Key	Type	Default	Description
`data_file`	path	`./data/snapshot.json`	Runtime program snapshot (`snapshot.json`). See Snapshot persistence & restore.
`log_dir`	path	`./logs`	Daemon + child log directory.
`events_file`	path	`./data/events.db`	SQLite event-history database location. Relative paths resolve under `SUPER_ROOT`.
`events_keep_days`	int	`30`	Retention window (days) for persisted event history. Events older than this are pruned once per day. `0` keeps everything (unlimited).

Event history is persisted to SQLite at events_file (default data/events.db, WAL mode). Every lifecycle event is recorded — program crashes, exits, recoveries, health restarts, cron runs (cron_started/cron_exit/cron_spawn_failed), queue drops, and daemon startup/shutdown. The store supports time/type/exit-code/text filtering and retention statistics via super events and the events API. The database is tuned for high write/query throughput: batched transactional inserts from a background writer, indexes aligned with the millisecond sort key, and WAL PRAGMA settings (large page cache, memory temp tables, capped WAL growth) are applied automatically. See Event History for usage.

`[child_logging]` — child process log capture

Key	Type	Default	Description
`driver`	`file` \| `stdout`	`file`	Where captured child `stdout`/`stderr` lines go. `stdout` prints them (prefixed with `[name:source]`) to the daemon’s own stdout; `file` writes to `{log_dir}/{id}.out` / `.err`.
`max_size_mb`	int	`10`	Max size per log file before rotation (MB).
`max_backups`	int	`5`	Number of rotated backups to keep; older backups are deleted (not an infinite archive).
`max_line_size_kb`	int	`16`	Max single-line length in KB; longer lines are truncated before disk/WebSocket.
`timestamp`	`local` \| `utc` \| `none`	`local`	Prefix each captured line with a timestamp. `local` → `[YYYY-MM-DD HH:MM:SS]`, `utc` → `[YYYY-MM-DDTHH:MM:SSZ]`, `none` → raw line. Applied when the daemon consumes the line; the WebSocket stream always carries the raw line.

# super.toml — [child_logging]
[child_logging]
driver = "file"
max_size_mb = 10
max_backups = 5
max_line_size_kb = 16
timestamp = "local"

`[include]` — program stack files

Programs are declared in stack files, not in super.toml. [include].files lists glob patterns for those files; superd parses every match as a stack and applies it on daemon start and on super reload.

Key	Type	Default	Description
`files`	list of string	`[]`	Glob patterns for program stack files, e.g. `["conf/conf.d/.toml"]`. TOML is the default format* (`.toml` or no extension); legacy `.json` stacks are still parsed and can be mixed in the same glob. Relative patterns resolve under `SUPER_ROOT`; patterns that resolve outside `SUPER_ROOT` are skipped.

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

Stack file schema and per-program keys: the Program stacks section below.

Program stacks — `conf/conf.d/*`

Programs are not declared in super.toml — [[programs]] / [[program]] tables there are ignored (super check reports them as an error). Programs load from stack files matched by [include].files (applied on daemon start and super reload), the API (POST /api/v1/programs), or the CLI (super add); all persist to data/snapshot.json.

A stack file is a TOML (default) or JSON document with services = [...] and an optional prune flag (default false when omitted — pruning never runs unless set to true). TOML uses one [[services]] table per program; JSON uses the legacy {"services":[...]} shape. See Declarative Stacks for a full example.

Note

In TOML stacks, tagged values like health_check are written as an inline table — health_check = { type = "tcp", port = 8080 } — or a nested table ([services.health_check]); [[array.of.tables]] is rejected.

The keys below describe a single program entry — one item in a stack file’s services[] array, or a create/update API payload. Multiple services[] entries are allowed per stack.

Note

Keys such as autostart, autorestart, exitcodes, startsecs, and stopsecs align with Supervisor for migration. Newer keys (retry_limit, health_check, depends_on, artifact, …) use snake_case. In stack JSON / API payloads, stopwaitsecs is accepted as an alias for stopsecs. OTA settings live under per-program artifact (including download_timeout / verify_timeout) — not under [server] or a global [ota] section.

Identity & execution

Key	Type	Default	Description
`name`	string	—	Required. Unique program name.
`command`	string	—	Required. Path to the executable.
`args`	list	`[]`	Command-line arguments.
`env`	dict	`{}`	Inline environment variables (`KEY = "VAL"`).
`env_file`	string	—	Path to a `.env` file loaded at spawn time.
`cwd`	string	—	Working directory. When unset, the program inherits superd’s own working directory (the directory the daemon was started in — under systemd/launchd this is typically `/`). The effective value is shown in `super info` and the Dashboard.
`user`	string	—	Run as this user (requires root).
`group`	string	—	Logical group for batch control (e.g. `@backend`).
`numprocs`	int	`1`	Spawn N OS processes from this program (`super add --numprocs`). For workers / queue consumers — not a rolling dual-version deploy, and not Node cluster mode. See Process Operations.
`process_name`	string	`{name}-{num}`	Name template when `numprocs > 1` (e.g. `worker-{num}`). Each instance gets `SUPER_PROCESS_NUM` / `SUPER_PROCESS_TOTAL`.

Restart & stop behaviour

autostart and autorestart are independent:

autostart — start the program when superd boots.
autorestart — restart the program after it exits (crash recovery).

Example: autostart = false with autorestart = "true" gives a manually started service that still recovers from crashes.

super stop and super start persist their effect: stop holds the program (and its cron schedule) down across daemon restarts; start clears the hold and sets autostart = true. See State Across Daemon Restarts.

Key	Type	Default	Description
`autostart`	bool	`true`	Start on daemon boot. Cron programs skip boot-time start regardless.
`autorestart`	string	`unexpected`	`unexpected` — restart unless exit code is in `exitcodes`; `true` — always restart; `false` — never restart on exit.
`exitcodes`	list	`[0]`	Exit codes treated as success when `autorestart = "unexpected"`.
`retry_limit`	int	`3`	Max consecutive crash restarts before status becomes `Fatal`.
`startsecs`	int	`10`	Seconds of stable uptime before an exit resets the retry counter.
`stopsecs`	int	`[server].shutdown_timeout`	Per-program seconds to wait after SIGTERM before SIGKILL. Omit to use `[server].shutdown_timeout` (default `10`). TOML alias: `stopwaitsecs`.
`priority`	int	`999`	Boot-time autostart order; lower values start first.

Logging

Key	Type	Default	Description
`stdout_logfile`	string	`{log_dir}/{uuid}.out`	Custom stdout log path (must resolve under `storage.log_dir`).
`stderr_logfile`	string	`{log_dir}/{uuid}.err`	Custom stderr log path (must resolve under `storage.log_dir`).

Orchestration

Key	Type	Default	Description
`depends_on`	list	`[]`	Program names that must be Healthy before this one starts. References are validated on stack apply, create, and update: unknown names are rejected with `depends_on: unknown service(s): …`, and configurations that would close a dependency cycle are rejected with the cycle members listed (include stacks applied during daemon start/reload only warn, for backward compatibility).
`cron`	string	—	Cron expression (e.g. `0 0 * * * *`). See Scheduled Tasks.
`on_overlap`	string	`skip`	Cron overlap policy: `skip` (drop tick while previous run is active), `queue` (run after the current instance exits), or `kill` (terminate the running instance, then run).
`catchup`	string	`skip`	Cron catch-up policy for slots missed while the daemon was down: `skip` (drop), `latest` (backfill the most recent slot once), or `all` (backfill every missed slot, capped at 10).
`jitter_sec`	int	`0`	Max random delay in seconds added to each cron trigger to spread load. `0` disables jitter.
`max_concurrent`	int	`1`	Max overlapping cron runs allowed at once (1–64; `0` means the default). See Scheduled Tasks.
`max_queued`	int	`100`	Cap on queued cron firings when `max_concurrent` is reached and `on_overlap` is `queue`/`kill` (0–10000; `0` means the default). Firings beyond the cap are dropped and recorded as `queue_full` events.
`kill_after_secs`	int	`0`	Per-run wall-clock cap for cron runs, measured from process start. When a run exceeds it, the supervisor stops it (`SIGTERM`, then `SIGKILL` after `stopsecs`) and records a `cron_overtime_kill` event; the schedule keeps firing. `0` disables the cap. See Scheduled Tasks.

`artifact`

Per-program OTA / binary update settings (stack entry, create/update API, dashboard, or CLI super update --artifact-*). Storing an artifact does not download by itself — OTA starts when an update changes checksum. See OTA Updates — When OTA runs. Full flow: OTA Updates.

Key	Type	Default	Description
`source`	string	—	Required when triggering OTA. Download URL. Remote hosts must use HTTPS (HTTP allowed on loopback for dev).
`checksum`	string	—	Required when triggering OTA. SHA256 hex of the downloaded bytes (the archive when `extract` is true).
`destination`	string	—	Required when triggering OTA. Absolute path of the final binary on disk.
`extract`	bool	`false`	Unpack `.tar.gz` / `.tgz` / `.tar` / `.zip` and stage one payload file to `destination`.
`restart_policy`	string	`immediate`	`immediate`, `manual`, or `signal` / `signal:<name>`. See OTA Updates.
`download_timeout`	int	`60`	Max seconds for this artifact’s HTTP download (connect + body). Raise for large/slow links. `0` disables the overall transfer timeout (a 10s connect timeout still applies). CLI: `--artifact-download-timeout`.
`verify_timeout`	int	`60`	Post-swap verification window (seconds). The new version must become Healthy within this window; on timeout the daemon rolls back. `0` disables. Without a live `health_check`, commit waits for `startsecs` (min 1s); if this timeout is shorter than that dwell, Super extends it automatically. CLI: `--artifact-verify-timeout`.

# conf/conf.d/api.toml — optional artifact block on a service
[[services]]
name = "api"
command = "/usr/local/bin/api"
# …
[services.artifact]
source = "https://example.com/builds/api"
checksum = "a1b2c3d4e5f6789abcdef0123456789abcdef0123456789abcdef0123456789"
destination = "/usr/local/bin/api"
extract = false
restart_policy = "immediate"
# download_timeout = 60
# verify_timeout = 60

`hooks`

Per-program lifecycle shell hooks. Full behavior table: Lifecycle Hooks.

Key	Type	Default	Description
`pre_start`	string	—	Run before spawn; non-zero exit aborts start.
`post_start`	string	—	Run after PID assigned (async).
`pre_stop`	string	—	Run before stop signal (sync).
`post_stop`	string	—	Run after process exits (async).

`health_check`

Key	Type	Default	Description
`type`	string	—	Required. `tcp`, `http`, or `exec`.
`host`	string	`127.0.0.1`	For `tcp` checks.
`port`	int	—	For `tcp` checks.
`url`	string	—	For `http` checks.
`method`	string	`GET`	For `http` checks: `GET`, `HEAD`, or `POST`.
`command`	string	—	For `exec` checks.
`interval_secs`	int	`5`	Seconds between probes. `0` = default.
`timeout_secs`	int	`3` (tcp) · `5` (http) · `7` (exec)	Max seconds a single probe may take. `0` = default.
`start_period_secs`	int	`1`	Grace window after start during which probe failures do not count toward `max_failures`. Probes run immediately; the first success ends the window early. `0` = default.
`max_failures`	int	`3`	Consecutive failures before auto-restart; `0` disables auto-restart. Bounded by `retry_limit` — see Health Checks.

`resource_limits` 💎

Schema fields are always accepted and stored. Enforcement (Linux cgroups v2 CPU/memory) requires the isolation plugin — without it, Super warns that limits are stored only. See Resource Isolation.

Key	Type	Default	Description
`cpu_quota` 💎	float	—	CPU quota in cores (`1.0` = one core, `0.5` = half a core).
`memory_limit` 💎	int	—	Hard memory limit in MB (`1 MB = 1024² bytes`); kernel OOM-kills when exceeded.
`memory_warn_percent` 💎	int	`80`	Pre-kill warning threshold as % of `memory_limit` (Tier 1). `0` disables.
`memory_warn_headroom` 💎	int	`0`	Also warn when live memory is within this many MB of the limit. `0` disables.
`memory_high` 💎	int	`0`	Kernel soft limit in MB (cgroup `memory.high`, Tier 2, opt-in). `0` disables.

`[[event_hooks]]` (OSS)

Global event listeners: local scripts (JSON on stdin) or native webhooks (url). Distinct from licensed conf/notify.toml webhooks (notify plugin). Full reference: Event Hooks.

Warning

[webhook] is not supported in super.toml. superd and super check reject configs that still contain a [webhook] table. For IM-specific templates, use conf/notify.toml with the notify plugin.

Key	Type	Default	Description
`command`	string	—	Shell command (`sh -c`). Receives JSON on stdin. Ignored when `url` is set.
`url`	string	—	HTTP(S) webhook URL. When set, the event JSON is `POST`ed here instead of running `command`.
`headers`	map	—	Extra headers for webhook mode (e.g. `Authorization`).
`events`	list	`["*"]`	Event names (`process_fatal`, …) or `"*"`.
`programs`	list	`["*"]`	Program names to match, or `"*"`.
`async`	bool	`true`	Run hook in background task (webhooks are fire-and-forget).
`timeout_secs`	int	`30`	Kill hook script / abort webhook request after N seconds.
`id`	string	—	Optional label for logs.

`conf/notify.toml` 💎

Licensed plugin only (notify). Separate from super.toml. Hot-reloadable webhook / IM channels. Schema and presets: Event Notifications.

System events & reactions

Super emits System Events (process_fatal, process_started, etc.). Where to configure reactions:

Mechanism	Config file	Edition	Status
Lifecycle hooks	per-program `hooks` (stack JSON / API)	OSS	✅ Active
Event hooks	`super.toml` → `[[event_hooks]]`	OSS	✅ Event Hooks
Webhook notifications	`conf/notify.toml`	💎 Licensed (`notify`)	✅ Event Notifications

Was this page helpful? Thanks for your feedback!

Still have questions? Open an issue or browse the source.

Technical FAQ CLI Reference

Config Reference

Edition legend

Instance layout (SUPER_ROOT)

[server]

[license] — subscription key (Licensed 💎)

[storage] / [logging] / [child_logging]

[storage] — data paths & event retention

[child_logging] — child process log capture

[include] — program stack files

Program stacks — conf/conf.d/*

Identity & execution

Restart & stop behaviour

Logging

Orchestration

artifact

hooks

health_check

resource_limits 💎

[[event_hooks]] (OSS)

conf/notify.toml 💎

System events & reactions

Instance layout (`SUPER_ROOT`)

`[server]`

`[license]` — subscription key (Licensed 💎)

`[storage]` / `[logging]` / `[child_logging]`

`[storage]` — data paths & event retention

`[child_logging]` — child process log capture

`[include]` — program stack files

Program stacks — `conf/conf.d/*`

`artifact`

`hooks`

`health_check`

`resource_limits` 💎

`[[event_hooks]]` (OSS)

`conf/notify.toml` 💎