Skip to content
SHC Docs
Search
Ctrl
K
Cancel
GitLab
Select theme
Dark
Light
Auto
Guide
Overview
Coming from Kubernetes
Apps
Overview
Custom builds
Frappe
GitLab
GlitchTip
Huly
Immich
ivatar
Jellyfin
Keycloak
Licensing postures
mailcow
Matrix
Mautic
multiplatform
NetBird
Nextcloud
OpenObserve
OpenReplay
Paperless-ngx
PeerTube
Penpot
PostgreSQL
Postiz
Pulp mirror targets
Pulp npm metadata overlay
Pulp OCI token configuration
SonarQube
SSO coverage policy
Supabase
Apache Superset
Traefik
Uptime Kuma
Wazuh
Clouds
Overview
Alibaba Cloud
AWS
Azure
Cloudflare
DigitalOcean
Exoscale
Google Cloud
Hostinger
OpenStack (OVH)
Oracle Cloud
Scaleway
UpCloud
Vultr
Getting started
Overview
After shc init
Core concepts
Installation
macOS
Reach a portal cluster from your laptop
Quick start
Operations
Overview
Refreshing app packaging
Set a backup destination
Restore onto a new cluster
Block storage by default
Multi-node cluster setup
Read a deployment's constraints
SHC Desktop
Disaster recovery
The cluster entrypoint (dns.public_address)
Enable backups
Estate app refresh: August 2026
Reaching estate nodes over SSH
Gated apps and auth.disable
The HUD on a phone
Nodes on a hypervisor
Losing a location
Rotating nodes in and out
Observability
Paging: the on-call lane
Portal secret custody: operating a bench that holds customer cloud credentials
Private names through the node resolver
Rolling a daemon back
Object storage for apps
Losing a site
Storage providers
Upgrading SHC
Vault & secrets management
Troubleshooting
Overview
Common issues
Troubleshooting SSE streaming
Learn
Overview
The training portal
Access
Overview
Tenants
Environments
Users and SSO
Gated apps
Connections
Storage providers
App
Overview
One node to learn on
A compose file
A simple Postgres
A Postgres socket
A label and a location
A backup and an export
Nextcloud on Postgres
A vapp and an add-on
Postgres members across locations
A node failing
The licence
Clouds
Overview
A Hetzner node
An Alibaba Cloud node
A Scaleway node
A Google Cloud node
An AWS node
An Azure node
A DigitalOcean node
An Exoscale node
A Hostinger node
An OpenStack node
An Oracle Cloud node
An UpCloud node
A Vultr node
Cluster
Overview
Four machines
The first node
The licence
Joining nodes
The control plane and its voters
Locations and labels
Placement rules
Cordon, drain, undrain, uncordon
Nodes failing and rejoining
Upgrading the daemon
Repositories
Restoring the whole cluster
The daemon's settings
Develop
Overview
One node to build on
Your first app
Your own page
A second service
A path under the hostname
A volume
A healthcheck
A seed job
Replicas and scale
Restarting what is unhealthy
The same app in shc.yaml
Variables
Your own catalogue
Stop, start, protect and rename
Secrets and the vault
Jobs, hooks and schedules
Volumes
Back up and restore your app
Schedules, retention and the repository
Exporters
Your own socket and plug
Add-ons
Your own vApp
Copies and deployfiles
Migrating from another platform
Groups and HA
A drain and a disruption budget
A privilege
HUD
Overview
Opening the HUD
Deployments, services and containers
A cluster changing under the HUD
Nodes
Every other table
Network
Overview
A port and a VIP
Who answers a port
A hostname and a certificate
A zone SHC writes
The fabric and its policy
The mesh under it all
Your own ingress
Runtimes
Overview
The default runtime
A podman node
An incus node
An apple node
See
Overview
A node for the observability app
Status
Doctor
Events
Logs
Metrics
Terraform
Overview
A workstation for Terraform
The root module
The cluster
Grow by a count
Deployments through the provider
DNS through the provider
Upgrade
Destroy
Example: hetzner-shc
Example: hetzner-lan
Example: hetzner-lan-lb
Example: hetzner-wan-mesh0
Example: mixed-proxmox-hetzner
Example: proxmox-lan
Example: aws-shc
Example: azure-shc
Example: gcp-shc
Example: digitalocean-shc
Example: linode-shc
Example: scaleway-shc
Example: vultr-shc
Example: exoscale-shc
Example: alibaba-shc
Example: cloudstack-shc
Example: openstack-shc
Under
Overview
Underneath the nginx deployment
Underneath the simple Postgres
Underneath the socket
Underneath the label and the location
Underneath the backup
Underneath Nextcloud
Underneath the vapp
Underneath the members group
Underneath a node failing
Render once on the leader
App development
Overview
Add-ons
App buckets
App capabilities
App definition
App features and openness
Brokers
Bundled services
What SHC does to your compose file
Creating apps: tutorial
Credential reconciliation
The Docker socket
Groups
Database apps, HA by scale
Health probes
HTTP app repositories
Integration doctrine
Lifecycle hooks
Plugs & sockets
Replicas and pods
shc.yaml
Source resolution
Storefront pages: what your app's page in the marketplace can be
Virtual apps (vApps)
App variables
x-shc directives
Reference
Overview
Adapter reference
The address block
Audit reference
CLI symbols
Cron reference
Error code reference
Event reference
Glossary
Init-time decisions
Labels and selectors
Metrics reference
Migration recipes
New-line runtime support
Platform support
Published ports
Quota model: caps versus derivation
The resource model on next
Runtime exceptions
The SSO display-name var
API
Overview
App API
Audit API
Backup API
Clone API
Cluster API
Config API
Events API
Export API
Health API
HUD API
Job API
Logs API
Public API
Node API
Quota API
Repo API
HTTP route reference
Internal RPC
Internal RPC reference
Schedule API
Search API
SSE streaming API
stack module
Storage API
Task API
Tenant API
Vault API
Response models
Overview
acme response models
adapter response models
app response models
audit response models
auth response models
backupbrowserouter response models
backupmountrouter response models
backup response models
branding response models
ca response models
capabilities response models
catalog response models
clone response models
cluster response models
condition response models
config response models
connections response models
console response models
containerbroker response models
cron response models
dns response models
doctor response models
eventpressure response models
events response models
export response models
fence response models
forward response models
health response models
internalrpc response models
job response models
launcher response models
leader response models
license response models
logs response models
mcp response models
network response models
node response models
notification response models
Payload shapes
portal response models
portforward response models
purge response models
quota response models
repo response models
retention response models
scan response models
schedule response models
search response models
shell response models
stack response models
storage response models
supportbundle response models
task response models
telemetry response models
tenant response models
user response models
vault response models
CLI
Overview
shc addon
App commands
shc backup
shc clone
shc cluster
shc config
shc ctx
shc doctor
shc events
shc export / import
shc forward
shc hud
shc import
shc init
shc inspect
shc job
shc logs
shc nfs
shc node
Command overview
shc quota
shc recover
Relocating a deployment
shc repo
shc retention
shc schedule
shc
shc shell
Stack commands
shc status
shc stop
shc storage
shc task
shc tenant
shc command tree
Utility commands
shc validate
shc vault
Tree
shc adapter
shc addon
shc auth
shc backup
shc branding
shc ca
shc catalog
shc cert
shc clone
shc cluster
shc completion
shc config
shc connection
shc constraint
shc container
shc convert
shc cron
shc ctx
shc db
shc deploy
shc dns
shc doctor
shc events
shc exec
shc export
shc finish-forward
shc forward
shc hud
shc import
shc ingress
shc init
shc inspect
shc install
shc integration
shc interrupted
shc job
shc label
shc leader
shc lease
shc license
shc logs
shc ls
shc mcp
shc node
shc notification
shc operation
shc portal
shc protect
shc quota
shc rebalance
shc reclaim
shc reconcile
shc recover
shc rename
shc repo
shc repoint
shc restart
shc retention
shc roll-back
shc run
shc scan
shc schedule
shc search
shc shell
shc show
shc start
shc status
shc stop
shc storage
shc support
shc system
shc task
shc tenant
shc uninstall
shc unprotect
shc update
shc user
shc validate
shc vault
shc version
shc volume
shc workshop
Comparisons
Overview
SHC vs Coolify
Platform comparison
Configuration
Overview
Configuration
Config keys reference
Environment variables
File locations
Token lifespans and session windows
Error codes
Overview
acme
adapter
app
apparchive
audit
auth
backup
branding
ca
capabilities
capacity
catalog
catalogbuild
certbroker
cli
clone
cluster
clusterfs
cmd
collector
completion
condition
config
connections
console
containerbroker
core/addrblock
core/api
core/appcatalog
core/appref
core/collectorcfg
core/composeunits
core/config
core/containerendpoint
core/daemonclient
core/db
core/eegate
core/eestub
core/enginemarker
core/executor
core/fwdhook
core/herd
core/hostactivate
core/hostplat
core/incusapi
core/jinja
core/labeltext
core/log
core/nic
core/nodefact
core/objchange
core/openstack
core/otelboot
core/pagecache
core/replicalabel
core/rqlited
core/secretscratch
core/selector
core/svcexec
core/tenantscope
core/timescale
core/usagecharge
core/validation
core/volume
ctx
daemon
deploymentspec
depnet
dns
docker
doctor
events
export
fabric
failover
fence
forms
forward
freeze
(global)
health
inspect
internalrpc
job
kv
labelcheck
leader
license
logs
mcp
mesh
metrics
network
node
nodeagent
nodelease
notification
otelrelay
pods
portal
portforward
privilege
proxy
purge
quota
rebalance
replicadoc
repo
resolver
retention
rollout
satellite collector/processor/shcscopeprocessor
scan
schedule
scheduler
search
selfclean
shell
stack
storage
storerpc
subsystems
supportbundle
task
telemetry
tenant
test
(unattributed)
underlay
user
vault
vip
Schema
Overview
addressblock
apparchive
application
assignment
audit
backup
backupcache
backupmount
backuporphan
backuprepoindex
backupschedule
certificate
clusterfabric
config
connection
connectiongrant
connectiontombstone
container
deployment
deploymentlease
deploymentnetwork
deploymentnode
deploymentspec
event
fabricallocation
fabricchunk
fabricpin
fence
fencemember
hostmapping
integration
job
jobcontainer
jobrun
kv
leafcertificate
livenessterm
meshendpoint
meshpeer
meshrotation
meshrotationack
meshtoken
namedselector
node
nodelease
payloadblob
placementevent
placementrule
portmapping
replicalabel
repo
revision
rollout
routingdrain
schedule
scheduler
service
servicevip
startfailure
store
storeattestation
storenode
task
tenant
tenanttombstone
usage
vault
vaultconfig
vdeployment
volume
volumeattachment
worker
Writers
Terraform
Overview
Examples
Getting started with Terraform / OpenTofu
Module library
SHC Terraform provider
Contributing
Overview
Updating the CE dependency
Local dev servers
SHC Engineering Standards
Project management
Release lines and backports
Standards
Overview
API design
Coding style
Commenting
Conventions
Error handling
Tech stack quick reference
Testing standards
Validation
Backend
Overview
API Standards
Migrations
Frontend
Overview
Accessibility
Frontend
CSS
Responsive design
Testing
Overview
Multi-node test book
Single-node test book
Multi-node deployment testing
SHC test suite
Writing tests
Architecture
Overview
Architecture register
Access control
Consensus and recovery
Feature graph: human overview
Identity and permission control: the per-app matrix
Host lifecycle: prepare, install, init, run
Marketplace roadmap: the four questions, answered
Output & messaging contract
platform:read: the read-only platform role
SHC scheduling and autoscaling (Design)
Security model
SSO auto-redirect: the fleet coverage matrix
SHC status states
SHC Telemetry Fabric (Design)
Catalogue vendor-minimum sweep (§45.6, ruled 2026-08-14)
Cluster
Overview
Mesh Architecture Diagrams
DNS Providers and Automatic HTTPS
DNS Provider Sync and Traefik ACME Architecture
SHC Network Fabric
SHC Cluster Architecture
Traffic across runtimes
Core
Overview
Subsystem lifecycle management
Data model
Deployment identity
Network architecture
Core
Tech stack
Diagrams
Overview
Events
Overview
Unified event bus
Job Registration System
Live Service Tracking
Flows
Overview
Flow: authentication
Flow: backup and restore
Flow: relocate
Flow: cluster join
Flow: event lifecycle
Failover delivery
Flow: app install
Flow: the launcher
Render once
Flow: app uninstall
Flow: app update
Layers
Overview
Layer 0. Underlay
Layer 1. Mesh
Layer 10. Edge
Layer 11. Lifecycle
Layer 2. Core
Layer 3. Work
Layer 4. Primitives
Layer 5. Objects
Layer 6. Services
Layer 7. Engine
Layer 8. Node
Layer 9. Fabric
Modules
Overview
App module
Audit module
Backup module
Clone and rename
Cluster module
Completion module
Config module
Ctx module
DNS module
Docker module
Doctor module
Events module
Export module
Forward module
Health module
Hud module
Inspect module
Job module
Leader module
Logs module
Metrics module
Network module
Node module
Notification module
Quota module
Repo module
Retention module
Schedule module
Search module
Shell module
Stack module
Storage module
Task module
Tenant module
Vault module
Patterns
Overview
Communication patterns
Cross-Module Access Patterns
Server Privilege Model
Implicit context (Ctx)
Package Architecture
Decisions (ADRs)
Overview
Backup engine convergence: the two engines are wrong in opposite directions
The mailcowtemplate claim: which mechanism replaces the stripped attribute
Owner decision docket: 2026-08-04 (refreshed 2026-08-04, late)
Should an ldap socket exist?
Splitting the sso socket into oidc and saml
The sso socket hands out the cross-realm admin credential, and the boundary that stops it is a property of the edge rather than of the contract
BI/analytics league pick: Apache Superset replaces Metabase's slot
The errors league (GlitchTip) and the uptime/status league
The flagship app tier: one best-in-class pick per league
Gate header injection: SSO for apps that will never have SSO
The gitlab provider socket, and what it does and does not close
2026-08-06: RBAC role matrix, explicit deny, and the permission-filtered menu
The session-replay league: OpenReplay packaged, footprint verified
Avatars: libravatar, the OIDC picture claim, and why ivatar stays a tenant app
The flagship bar is payment, not license family, owner ruling 2026-08-07
Backup rulings: 2026-08-14
Broker & privileged-capability rulings: 2026-08-14
Capability + backlog rulings: 2026-08-14 (evening Q&A)
Ruling: auto-redirect SSO is the corp/prod default across flagship, 2026-08-14
SSO hardening rulings: 2026-08-14
Do we use the saga pattern? And what we should do instead
Frappe is the platform; Medusa is not adopted as infrastructure: owner ruling 2026-08-16
Hyperswitch integrates INTO the Frappe payments abstraction, as ONE gateway: owner ruling 2026-08-16
The install request / approval state machine: BUILT 2026-08-16
marketplace belongs in the shc tenant: 2026-08-16
Marketplace entitlement and licensing: 2026-08-16
Marketplace identity and install: RULED 2026-08-16
netbird stays PUBLIC, and stays in corp, 2026-08-16
Portal accounts and cluster identity: RULED 2026-08-16
Registration is the durable identity, 2026-08-16
Branding is S3-only, served by shcd: 2026-08-18
builtin/ vs deploy/: the placement axis is UNIVERSALITY, not dependency
The comment backend: extend Frappe, do not adopt: 2026-08-18
The community moderation model: built, 2026-08-18
Squashing the migration catalogue, and why it needs no redeploy
Disabling an account at Keycloak revokes nothing inside an app, and SHC has no seam that could tell it to
Marketplace: SIGNALS → SCORES → COLLECTIONS: 2026-08-19
The migrations reset doctrine: a reset is a reset
license-broker folds into the portal deployment: 2026-08-20
DNS-domain licensing: the signed token IS the licence, 2026-08-21
The on-call league: GoAlert takes flagship: oncall
oidc plug groups (realm) and roles (client): Mailcow / Employee
backup.yaml lists what a backup copies: 2026-10-18
ADR-0001: Pure DI at a composition root (no DI container)
ADR-0002: Stack state: three roles, one authority per role (the manifest model)
ADR-0003: One data-ladder Scope type
ADR-0004: Hermetic default test lane, engine fidelity lane
ADR-0005: Architectural fitness functions
ADR-0006: Thread registry.Deps through every seam; no global root pointer
Proposals
Overview
#113 quorum-safe removal v2: reachability-aware guard + bounded RPCs + recovery hint
Canonical app.yaml metadata schema (census-driven) (2026-07-17)
Post-deploy notes templating (Helm NOTES.txt style) (2026-07-17)
Origin ingest gate + materialized transpile (2026-07-17)
Resource Meta-API: self-describing resources, one contract for every client
Edge-CA trust: making server-side OIDC survive a non-public ACME directory
The deployment binding model (proposal)
The node addressing model (proposal)
The storage model (proposal)
A port selector for url() / host() / path() (proposal)
Cert-delivery broker: handing a deployment the edge certificate for a host it terminates itself
LDAP as the universal SSO fallback
Backup schedules: arming the subsystem that is built, idle, and one config row away
Config versus state, the migration (proposal)
The OIDC redirect default: retiring default('') in the Keycloak socket
shc dns: the verb gap-inventory G33/G43/G51 asks for, and why it was not built
Brokers: the runtime half of integrations
The in-stack exec broker: a request-time verb, not a socket
A tenant container runtime: what "this app spawns containers" actually needs
The frappe → Nextcloud calendar bridge
The mailbox reconciler: the identity-broker that makes mail zero-touch
The matrix notification bus: hookshot as a packaged app
The webdav socket on nextcloud: the backup deposit edge
Hookshot phase-0 build readiness: what the measurements changed
The capacity substrate: what a rebalancer has to be able to read
Node selection UX: what the operator has to say, and what the product should decide for them
The placement policy and the scorer: what chooses a node, at install and at rebalance
What triggers a move, and how it cannot run away
Runtime declaration and selection: how a runtime gets chosen, and what an app may say about it
SSO auto-redirect: the arming plan
Implementation D: an injected synthetic click for the structurally-excluded class
The storage constraint: what a move costs today, and what would make it cheap
shc update must say what it did
Console architecture: RULED 2026-08-14
Marketplace architecture: RULED 2026-08-14
The Portal: architecture, RULED 2026-08-14
Hookshot's first deployment: what a live estate settled
License-broker topology: central vs per-estate, 2026-08-15
Portal Terraform runner: secret injection and the run ledger (design)
The tenant model, should SHC's product infrastructure live in its own tenant (proposal)
Per-app landing pages, and the SEO problem underneath them (2026-08-16)
Mobile apps: proposal, owner design conversation 2026-08-16
Native release readiness: iOS and Android
The portal↔cluster channel: protocol spec, 2026-08-16
The settings surface: proposal 2026-08-16
Cluster registration: the four paths, the two primitives, and what is already built
App metrics and the trust score (2026-08-18)
Console settings: the build order (design)
Storefront host rename: marketplace. → apps. (design)
Registry connections
plane × gitlab tickets: the feasibility verdict
Multi-site estates and fences (design)
The SHC scheduler (design)
The new line, deleting first (design)
The apple runtime (design)
Moving bitspur to the new line (design)
The incus runtime (design)
Fabric policy follows the tenant model
Two WireGuard tunnels, never double wrapped (design)
Groups and the members block (design)
Replica projects (contract)
One virtual IP per service (design)
shc.yaml (design)
Store replication tiers for clusters of thousands of nodes (design)
Placement: labels, locations, node selectors and service selectors
Retire the Frappe/Python-era API wire dialect
Persist the backup manifest inside the restic repo (2026-07 cross-cluster recover finding)
Daemon bind/advertise split (2026-07 mixed-cluster finding)
The catalog: a design discussion
Clone/restore lineage is not rename-aware
Console, portal, and marketplace UX
Cross-cloud convergence plan (2026-07-13 live campaign)
SHC Daemon DI Migration: Master Plan
Frappe image architecture: baked apps, dynamic apps, and both at once
Plan: deployment poll consumes recorder rows + small DNS/config knobs
Plan: hook action lists + runtime refs (full migration, no legacy)
Plan: real per-container status during shc install (install-time live service tracking)
Integration teardown: wake the 22 dead jobs, then collapse three runners into one
Live host reconfig: changing the cluster host without re-genesis
Short-lived :4003 node leaves + renewal as the passive revocation backstop
SSO auto-redirect: skip the app login page when a Keycloak plug is connected
Evidence
Overview
2026 08 10 hookshot unknowns
Overview
Re-measurement transcript, 2026-08-10 ~20:12 UTC (lane V-A, second session)
Independent re-verification of §12.3: GlitchTip 6.2.5, second lane
GitLab
Select theme
Dark
Light
Auto
Frontend
Accessibility
Components
Css
Responsive
press
`
to open the console
shc@docs:~$
press
`
or tap here to close ·
help
for commands