Reference
Exhaustive lookup for when you know what you’re searching for. Audience: anyone consulting the spec of a command, endpoint, config key, error code, or term.
For prose walkthroughs, see ../guide/. For internals, see
../architecture/.
Every shc command, grouped by subcommand. Pages are hand-written where
prose adds value; auto-generated from the command classes otherwise.
- Overview: global flags, output formats, exit codes
- CLI symbols: what
=:@/+!,mean inside a flag’s value, and the--exposeand--scalegrammars - Labels and selectors: node labels, the selector grammar,
--whereand--prefer, named node selectors and constraints - Published ports: how a deployment is reached from outside on next, the
--exposegrammar, the listen rules, and the refusals
Core operator commands (hand-written):
shc addon: list and inspect the add-ons an app publishesshc app: install, uninstall, upgrade, list appsshc backup: create, list, restore, pruneshc clone: duplicate a deploymentshc cluster: cluster-level operationsshc export/shc import: selective data export/importshc job: run and manage jobs- Relocating a deployment:
shc update --whererelocates,shc renamerenames shc node: multi-node managementshc retention: retention policiesshc stack: start, stop, exec, shell, logsshc storage: storage pools and volumesshc utility:ctx,config,schedule, miscshc vault: secrets management
Auto-generated from command classes:
shc events,shc config,shc ctxshc doctor,shc events,shc forwardshc hud,shc inspect,shc logsshc quota,shc repo,shc scheduleshc shell,shc task,shc tenantshc init,shc nfsshc status,shc stopshc recover,shc validate,shc import
Endpoints exposed under /api/method/* and /api/resource/*. The
exhaustive per-module (method, path) inventory is the generated
HTTP route reference; regenerate with
make docs/generate. The pages below add hand-maintained
request/response notes for the major operator modules; modules without
a dedicated page (auth, ca, dns, doctor, user, …) are still
fully listed in the route reference.
- HTTP route reference: every route each module registers (auto-generated)
- Internal RPC reference: every function one node calls on another, with its arguments and result (auto-generated)
- SSE streaming: Server-Sent Events for events + long-running operations
app: app install, upgrade, uninstallaudit: audit log queriesbackup: create, list, restoreclone: clone or relocate a deploymentcluster: join tokens, cluster opsconfig: config CRUDevents: event stream + queryexport: import/exporthealth: health endpointshud: HUD overlayjob: job CRUDlogs: log retrievalnode: node managementquota: quota get/setrepo: app repository CRUDschedule: scheduled task CRUDsearch: app searchstack: start, stop, exec, and logs for a deploymentstorage: storage providerstask: task queriestenant: tenant CRUDvault: secrets CRUD
Configuration
Section titled “Configuration”-
Config files: file formats, scopes, precedence
-
Config keys: every key in
default.yamlwith its default -
Token lifespans: the 4 h access token default, the idle-timeout interaction, revocation lag
-
Environment variables:
SHC_*env overrides -
File locations: where SHC stores data, logs, cache
-
The SSO display-name var:
keycloak.displayName/saml.displayName, the catalogue-wide name for the login-page label, why its value is the provider noun, and the two apps that do not fit -
The resource model on next: CPU, memory and disk per service, per scope, per volume and per node, each line marked built, partly built or not built, with the code that does it
-
Quota model: caps versus derivation: the two mechanisms that share the word “quota”, which one gives every container its limits, which one enforcement checks against, the ratio defaults and what
nullindefault.yamlmeans, plus the measured state of both production estates
Operational timeouts are role-named keys under the timeouts: section of
default.yaml (e.g. timeouts.keycloak,
timeouts.backup, timeouts.drain), read via core/timeouts.
Terraform / OpenTofu
Section titled “Terraform / OpenTofu”Provisioning and driving a cluster as code: the custom shc provider, the
core + shc/<cloud> module library, and ~18 per-substrate examples.
- Overview: the modules, the provider, the examples, and the publish/mirror model
- Getting started: install from the mirror,
tofu init/plan/apply - The
shcprovider: every resource and data source - The module library:
coreand theshc/<cloud>front doors - Examples: every example + an end-to-end walkthrough
Adapters
Section titled “Adapters”- Adapter reference: every platform adapter with its declared load/migrate capabilities (auto-generated)
Errors & events
Section titled “Errors & events”- Error code reference: every typed error SHC can raise (auto-generated)
- Event reference: every event-bus topic with durability class and payload shape (auto-generated)
Platform support
Section titled “Platform support”- Platform support: which host OSes SHC supports, exactly which subsystems refuse off Linux, and the coded error each raises
- Runtime exceptions: the one list of gaps where an app sees a runtime differ from docker, each with its ticket and the apps that live with it
Bootstrap
Section titled “Bootstrap”- Init-time decisions: every decision fixed at
shc initor at node join, classified HARD / SOFT / CHANGEABLE / LOSSY, with what each one costs to change - The address block: the one IPv4 block every SHC range is carved from, the four ranges it gives, and what to do on a site that already uses them
Upgrades & legacy
Section titled “Upgrades & legacy”- Legacy and breaking changes: every breaking change since v0.0.14 grouped by who feels it (and which ones shipped unannounced), plus every legacy, dead and never-implemented path still in the tree, classified and ranked by what it costs to keep
Glossary & comparisons
Section titled “Glossary & comparisons”- Glossary: SHC terminology
- vs Docker / K8s / Nomad / Coolify / Vercel
- vs Coolify (deep dive)