Skip to content
SHC Docs

Glossary

Glossary of concepts, terminology, and technical patterns used in SHC (Self-Hosted Cloud).


Per-deployment open/gated axis. gated routes the deployment through SHC’s SSO gate (Traefik forward-auth against the tenant’s Keycloak realm); open leaves it ungated so the app relies on its own auth. Set at install with the mutually-exclusive --gated / --open flags; open is the default. Orthogonal to exposure (the LAN-vs-internet reach axis), so a deployment can be open + internet or gated + lan. See Access control; resolved by NormalizeDeploymentDisposition in modules/app/disposition.go.

Automatic Certificate Management Environment. Protocol used by Let’s Encrypt and other CAs to automate SSL/TLS certificate issuance. Traefik uses ACME to automatically obtain and renew certificates for hosted services.

Per-platform component that connects SHC to another self-hosting platform (Runtipi, CasaOS, Umbrel, Coolify, Cloudron, Portainer, and more). An adapter understands the platform’s app grammar and on-box layout, and powers shc adapter load and shc adapter migrate. Each adapter’s declared capabilities are published in the Adapter reference.

The result of shc adapter load: an SHC app transpiled from another platform’s app (compose, typed vars, secrets, plugs), installed and run on SHC like any catalog app, with the source install’s data pulled along.

One word, two scopes, deliberately. Which one is meant is settled by the qualifier, never by context:

  • SHC addon: a platform extension SHC itself operates: keycloak, openobserve, postgres, traefik. One directory each under ce’s addons/, staged into apps/<name> by make modules/stage and shipped inside the binary and the deb. Three of the four are never published and never tenant-installable; postgres is the ruled dual-nature exception (an SHC addon and a catalogue app). Called a “builtin” before SHC-506, which retired that word: the concept was never “compiled in”, it was “an extension SHC runs”.
  • App addon: a versioned variable bundle a single app publishes, installed by name: shc install <app>/<addon>[@<version>]. See Add-on below for the full mechanics.

The shared word is intentional: both are an extension of something, differing only in what they extend: the platform, or one app. Say “shc addon” or “app addon” wherever a bare “addon” could mean either. Neither is the Shipped catalog, which is a repo, not an extension.

A versioned variable bundle an app publishes so an operator can install a known-good configuration by naming it: shc install <app>/<addon>[@<version>]. One file is one add-on: apps/<bucket>/<app>/addons/<name>.addon.yaml, where the filename stem is the add-on’s identity and the directory is its parent app. An add-on that declares vapp: <name> configures that VApp; one with no vapp: key configures the app itself, and the file is what says which, so the vApp segment never appears in the command and both kinds are spelled identically. Crossing the two still refuses (X400055ADNTYP); a name that is both a vApp and an add-on refuses rather than being guessed (X400056ADNAMB). Replaces the retired presets.yaml / <vapp>.vpresets.yaml pair. See Add-ons.

Historical term. In the current architecture, every node runs the full SHC server. There is no separate agent binary.

Declarative database migration tool (ariga/atlas). SHC uses Atlas to generate the store’s migrations from the ent schema (make migrate NAME=<slug> in ce), stored in ce’s migrations/ with an integrity manifest in migrations/atlas.sum.

Internal cron-style registry in modules/task/. The queue subsystem polls each registered cron’s schedule and enqueues a task entry when due.

A deployable application definition consisting of compose.yaml, optional app.yaml metadata, variables, and integration definitions. Apps are installed as deployments.

The indexed collection of available apps from synced repositories. Uses SQLite FTS5 for full-text search.

The set of files that define an app: compose.yaml (required), app.yaml (metadata), vars.yaml (variables), *.plug.yaml, *.socket.yaml, etc.

Optional metadata file for an app containing name, version, description, categories, tags, hooks, and other configuration. If absent, metadata is inferred from compose.yaml.

Unix archive format (like .deb packages). SHC uses AR format for .bak and .exp files to allow reading manifest without extracting data.

Installation source from a compressed archive file (.tar, .tar.gz, .tgz, .zip). Can be local or remote (HTTPS).

Structured log event recording security-relevant operations like vault access, secret changes, and authentication. Uses event codes with audit flag.


A point-in-time snapshot of a deployment’s DATA mounts, secrets, and configuration. Scheduled backups are stored in the cluster’s restic repository and indexed in the ledger; there is no local backups folder. A .bak file is the one-off/export format (see .bak).

App-specific backup configuration defining converters, pre/post backup jobs, restore jobs, include/exclude rules, and pause timeout.

The global configuration scope in the database. All other scopes inherit from base (global).

Berkeley Software Distribution. One of the supported operating systems with specific path conventions.

The maximum number of events stored in an SSE ring buffer per operation. Default: 1000 events.


Temporary storage for cloned git repositories and other reusable data. Located at {cache_home}/. Can be safely deleted.

XDG-compliant cache directory. User: ~/.cache/shc, System: /var/cache/shc.

The inheritance behavior of configuration values from broader to narrower scopes (base → tenant → environment → stack → deployment).

Traefik component that obtains TLS certificates. Default is letsencrypt using ACME protocol.

The shc command-line tool. Primary interface for all SHC operations. Built with spf13/cobra.

Create a copy of an existing deployment, optionally to a different node or with a new name.

The multi-node group linked by the raft engine (rqlited): one elected leader plus voter nodes, providing control-plane HA via leader election. The voter count is the largest odd number no greater than the control-plane fence’s members, capped at 5, and follows the fence automatically. Writes need quorum ((voters/2)+1 reachable voters) or the cluster goes read-only. See modules/cluster (ce module) and core/rqlited. See also: Leader, Voter, Quorum.

Docker Compose. The container orchestration tool SHC builds upon. SHC supports Compose v2 format.

Docker Compose file defining services, volumes, networks, and other container configuration. Required for every app.

Unique identifier formed from multiple values. A deployment is identified by tenant + stack + environment.

User-controlled settings stored in the database. Read-only by the system. Cascades across scopes (global → tenant → stack).

Hierarchical configuration level: base, tenant, environment, stack, or deployment. More specific scopes override broader ones.

Shared identifier for coordinated backups of several deployments. Ensures backups were taken at the same logical point in time.

A running Docker container instance. Multiple containers can exist for a single service (replicas).

The primary SHC node running the server. Manages all orchestration and serves the API. Other nodes are workers.

A backup job that transforms volume data during backup (e.g., pg_dump instead of raw files). Runs against a snapshot copy.

Minimum time between reconciliation attempts. Prevents rapid repeated actions. Default: 60 seconds.

Resource limit for CPU usage. Specified in millicores (e.g., 1000m = 1 CPU core).

Time-based job scheduling format. SHC uses cron expressions for backup schedules and recurring tasks.


The SHC server process running as a systemd service. Listens on Unix socket, manages all operations.

Volume type for persistent application data (databases, uploads). Backed up automatically. Stored in mounts/ directory.

SQLite database (shc.db) in single-node mode, or rqlite (raft-replicated, served by an external rqlited process) in cluster mode. Stores operational data: deployments, services, containers, backups, schedules, audit events, and configuration.

Prevention of duplicate event processing. SHC uses a 5-second time window cache in handle_event() to deduplicate Docker events.

The environment a CLI verb addresses when none is specified. On SHC Enterprise this is prod; on Community, which has exactly one environment, it is default. One answer for every verb: shc install, shc exec, shc logs, shc backup, shc clone, shc stop/start/ restart, shc uninstall and the rest all resolve it identically, so a bare install and a bare anything-else reach the same deployment.

Two exceptions, both deliberate:

  • The master tenant is reserved to default. SHC’s own platform deployments (traefik, keycloak, postgres, openobserve) live at master/<stack>/default and every reconcile that operates them resolves them there, so shc -t master <verb> addresses default whatever the estate default is.
  • Listing verbs are not defaulted. shc ls, shc status and shc backup ls use the environment as a filter, where naming none means “every environment”.

Precedence, narrowest first: the verb’s own -e/--environment, then the global -e / $SHC_ENVIRONMENT / shc ctx -e, then the default above. An explicit -e default always addresses default.

This is not the wire fold: an environment OMITTED from a daemon request still normalises to default server-side, which is what every deployment directory and compose project name on disk was written under.

The tenant used when none is specified. Value: default.

Status indicating a deployment is not fully healthy. Containers may be missing, exited unexpectedly, or unhealthy.

The running unit. Identified by tenant + stack + environment, where stack and environment are the axes. Has its own data, config, and secrets.

String identifier for a deployment: {tenant}_{environment}_{stack}. It is the deployment’s Docker Compose project name; a node that runs replica projects names each one {tenant}_{environment}_{stack}-{pod}-r{ordinal} (see Replicas and pods).

Component that monitors Docker events during operations and displays live progress. Used for install, upgrade, start, stop.

Stack status computed from service statuses (running, degraded, complete, failed, stopped). Contrasts with operational status.

The target number of container instances for a service. Defined in compose.yaml deploy.replicas.

Development mode when running from source. All paths consolidate under {project_root}/.shc/. Enabled by detecting go.mod.

Integration jobs that run before main integration to gather information (e.g., checking if a database server is ready).

External service for DNS record management (Cloudflare, Hetzner, PowerDNS, etc.). Used for automatic A/AAAA/CNAME creation.

The engine behind the docker runtime. A node runs one of docker, podman, incus, or apple.

Tool for defining and running multi-container applications. SHC extends Compose with multi-tenancy, backups, and integrations.

Notification from Docker daemon about container lifecycle changes (create, start, stop, die, health_status).

Virtual network for container communication. SHC creates a network per deployment. On Linux, cross-node container traffic uses the shc0 fabric.

Log template mining library. Clusters similar log messages to reduce cardinality. Optional dependency.


API URL or service address. SSE endpoint: /api/method/shc.operation.stream/{operation_id}.

Traefik listener configuration. Default entrypoints: web (HTTP/80), websecure (HTTPS/443).

The other axis beside stack (default, prod, staging, dev). The same app can run once in each environment.

Shell variable for configuration. SHC respects XDG variables and provides SHC_* overrides.

A structured occurrence in the system (Docker events, audit events, config changes). Has a code, timestamp, and payload.

Unique identifier for event types. Format: {prefix}{http_status}{sequence}{mnemonic} with prefix V (info), A (audit), or X (coded error/warning). Example: A200100STKINS (stack installed).

Path of events from source to consumer: Docker → event collector → handle_event() → broadcast → SSE. Each node collects its own Docker events directly.

Function that processes events. handle_event() updates database and broadcasts to subscribers.

Component on each node that watches Docker events and processes them directly. Part of the SHC server.

Integer returned by a container when it stops. 0 = success, non-zero = failure.

Application-level data extraction using app-defined exporters (e.g., pg_dump for a single database). Contrast with backup (volume-level).

Export artifact in AR format. Contains manifest.json and data.tar.gz.


Status indicating a job container exited with non-zero exit code and won’t retry (restart_policy=no).

Subsystem-defined order for DNS or vault providers when resolving a request.

Lightweight Go HTTP router used for SHC’s API. Mounted by each module’s RegisterRoutes and walked by the listeners and the reference generators.

The vault’s only at-rest format (v2: prefix). An Argon2id key-encryption key derived once per unlock wraps a random per-secret AES-256-GCM data key, so a read costs no key derivation. See the vault module.

Symmetric scheme (AES-128-CBC + HMAC-SHA256, PBKDF2 key derivation). Not the at-rest format: it was retired at v0.0.16 in favour of envelope encryption and has no reader. It survives only as the password-based wire format of the vault export bundle and the backup manifest’s inline secrets bundle, which a different cluster has to be able to open.

Volume type for configuration files copied from app definition. Not backed up (regenerated on install/upgrade).

Unique identifier for a deployment instance. Used to detect if a restore targets the original or different deployment.

Git URL extension for specifying ref and path: git+https://...#ref:path.

REST API format compatible with Frappe/ERPNext SDK. SHC implements method API (/api/method/) and resource API (/api/resource/).

SQLite Full-Text Search version 5. Used for app catalog search with fuzzy matching and relevance sorting.


SSE event indicating the client missed events due to buffer overflow. Client should query current state to resync.

Installation source from a git repository. Supports HTTPS, SSH, and various hosting providers.

File pattern matching (e.g., *.yaml). Used for file discovery and filtering.

Visualization platform for metrics. SHC provides dashboard definitions for SSE and other metrics.

Collection of related deployments backed up together with a shared consistency ID. Ensures coordinated point-in-time snapshots across integrated deployments.


Core function (handle_event()) that processes Docker events, updates database, and broadcasts to subscribers.

Application health status independent of lifecycle status. A container can be running but unhealthy. On the container row, health is the raw health check word the runtime reports: none, starting, healthy, unhealthy.

Docker mechanism to verify application health. Runs commands periodically and reports healthy/unhealthy.

Background task that polls node and deployment health every 60 seconds. Triggers reconciliation when needed.

Periodic check of all nodes and deployments. Default interval: 60 seconds.

SSE keep-alive message sent during idle periods. Prevents connection timeout. Default interval: 30 seconds.

Lifecycle callback defined in app.yaml (pre_install, post_install, pre_upgrade, post_upgrade, etc.).

Two senses, disambiguated by context:

  1. Networking: the domain name a service is reached at (e.g., app.example.com), configured via the --expose flag. This is the older and more common use.
  2. VApp: the deployment a Vdeployment installs into and draws its run half from. wordpress/plugin installed into the blog deployment makes that deployment the vdeployment’s host.

Automatic application of config changes without restart. Config files are watched via inotify/FSEvents.


Docker image containing application code and dependencies. Pulled from registry on install/upgrade.

Load data from an export artifact into a deployment.

Network entry point for external traffic. Traefik handles ingress routing to services.

Linux kernel subsystem for file change notifications. Used for config hot-reloading.

Deploy an app as a new deployment. Creates the deployment directory, pulls images, starts containers.

Connection between apps via plugs and sockets. Enables database provisioning, secret sharing, etc.

Job that runs during integration to set up resources (create database, create user, etc.).


Templating syntax used for compose.yaml, config files, and integration definitions. SHC uses a Go Jinja2-compatible template engine.

A <name>.job.yaml in an app: a command run once, in a running service (service), in a new container (container), or as an HTTP call (http). Contrast with a service (always running).

Container for running hooks, integration jobs, converters, or restore jobs.

JavaScript Object Notation. Used for API responses, event payloads, and some configuration.


Process of generating encryption key from password. SHC uses PBKDF2-HMAC-SHA256 with 480,000 iterations.


Docker container metadata. SHC uses labels for tenant, stack, environment, app, and version.

HTTP header for SSE reconnection. Client sends last received sequence number to resume from that point.

The primary node in a cluster responsible for coordinating cluster-wide operations. Elected via Raft consensus in the raft engine (rqlited). See also: Voter, Quorum.

Process to select one server instance as leader in multi-node deployments. Uses Raft consensus in the raft engine (rqlited).

Free certificate authority. Default ACME provider for Traefik TLS certificates.

Container or deployment state progression: install → start → run → stop → uninstall.

Real-time terminal output showing deployment progress. Uses Rich library for TTY formatting.

Component on each node that tails container logs. Part of the SHC server, collects logs directly without intermediate spool files.

Logging verbosity. SHC uses binary mode: INFO (default) or DEBUG (--debug flag).

Multi-format log analysis. Supports JSON, logfmt, syslog, nginx, apache, Drain3 templates.

Automatic archival of log files when they exceed size limit. Configurable size and keep count.

Directory for log files. User: ~/.local/share/shc/logs, System: /var/log/shc.

Log format using key=value pairs. Common in Go applications.


Build automation file. SHC’s Makefile provides dev, test, build, install, and diagrams targets.

Mutual TLS. Authentication mechanism where both client and server present certificates. Used for inter-node communication on ports 4001-4003. Each node has certificates signed by a cluster CA.

Metadata file in backup/export archives. Contains version, timestamps, sizes, and restoration information.

Resource limit for memory usage. Specified in bytes or with units (e.g., 512Mi).

Markdown-based diagramming syntax. SHC uses Mermaid for architecture diagrams in docs/architecture/diagrams/.

The node plane giving nodes cross-node peer reachability: mesh0 on UDP 4244, coordinated by shcd through kernel WireGuard on Linux or userspace WireGuard on a utun on macOS (docs/proposals/2026-10-01-two-tunnel-mesh.md). Container traffic rides the separate shc0 fabric (modules/fabric). Peer liveness is probed on the mesh_ping timeout role (DefaultMeshPing / RoleMeshPing). Raft and the internal API ride mesh0.

Quantitative measurements exported for monitoring. SHC exports Prometheus-format metrics via OpenTelemetry.

Frappe-compatible API pattern: /api/method/{dotted.path}. Used for RPC-style operations.

Database schema change managed by Atlas. Also: moving a deployment between nodes.

Volume binding between host and container. Types: DATA, FILE, RUNTIME, SYSTEM.

Directory containing DATA mount volumes for a deployment. This is what gets backed up.

Relocate a deployment to a node its --where and constraints allow, using shc update --where.


A deployment’s containers share its network. On Linux, cross-node container traffic uses the shc0 fabric. Ingress is Traefik.

A host machine running Docker and the SHC server. In cluster mode, nodes are classified as leader (runs background tasks), voter (participates in consensus), or non-voter (read replica).

Process of finding nodes in a network. Supports subnet scanning and manual registration.

Unique identifier for a node. Auto-generated or specified during registration.

Connection parameters for a cluster node (address, node ID, certificates).

Converting values to a standard form. SHC normalizes restart policies (unless-stopped → always).


Observability platform for logs, metrics, and traces. Default export destination for SHC telemetry.

Vendor-neutral observability framework. SHC uses OTEL for logs, metrics, and traces export.

A tracked long-running action (install, backup, restore). Has an operation_id for SSE streaming.

UUID identifying a long-running operation. Used for SSE progress streaming.

Component that tracks active operations and their SSE subscribers.

Stack status set by user commands: created, starting, stopping, updating, removing. Blocks derived status updates.

Component that renders data structures to TTY, plain text, JSON, or YAML based on context.


SSH library. Not used by SHC: inter-node communication uses mTLS. SSH is only for human admin access.

Installation source from a local filesystem directory.

Docker command to suspend container processes. Used during backup snapshots for consistency.

Password-Based Key Derivation Function 2. Used for vault encryption key derivation.

File containing server process ID. Located at {runtime_dir}/shc.pid.

Node requirements for deployment (architecture, OS, available resources).

What an app requires from another app. Defines data schema and references socket provider.

Docker-compatible container runtime. SHC supports Podman with podman-compose.

Collection of reusable connections. SHC uses HTTP connection pooling for internal API calls between nodes.

Making a container port accessible from outside. Can be public (via Traefik) or direct (host port binding).

Integration jobs that run after both deployments are up and healthy.

Completion percentage (0-100%) of a long-running operation. Streamed via SSE.

Metrics monitoring system. SHC exports Prometheus-format metrics.

External service implementation (DNS provider, vault provider). Multiple providers can be configured; resolution order is defined per subsystem.

The dependency-inversion interface modules expose for cross-module deps (e.g. clone.StackProvider, clone.BackupProvider). The daemon implements each seam in daemon/clone_adapters.go so the producer module stays import-cycle-free.


Task queue for background job execution. SHC uses an internal queue with worker processes.

The minimum number of voter nodes required for cluster consensus. Requires (N/2)+1 nodes for N voters. Without quorum, the cluster becomes read-only. See also: Leader, Voter.

Resource limit at a scope (tenant, stack, deployment). Includes CPU, memory, disk, stack count.


Automatic recovery of degraded deployments. SHC runs compose up -d when containers are missing or dead.

Create new deployments from coordinated backups. Validates consistency_id and auto-wires integrations.

Git reference (branch, tag, or commit). Specified in git URL fragment or --ref flag.

Docker image storage (Docker Hub, private registries). Images are pulled during install/upgrade.

Internal tracking of active operations for SSE streaming.

Installation source from an HTTPS URL pointing to an archive file.

SSH is only used for human admin access. Inter-node operations use mTLS-authenticated internal APIs.

Container instance of a service. Services can have multiple replicas for scaling.

Source of app definitions. Types: git, local, HTTP. Synced to local catalog cache.

Frappe-compatible CRUD pattern: /api/resource/{type}. Used for data operations.

Docker configuration for container restart behavior: no, on-failure, always.

Backup program with deduplication and encryption. SHC uses Restic for remote backup storage (S3, B2, etc.).

In-place data recovery to an existing deployment from a backup.

Job that processes converter outputs during restore (e.g., pg_restore).

Policy for keeping/deleting old backups. Configurable by count and age.

SHC uses charmbracelet/lipgloss and bubbletea for terminal formatting, tables, progress bars, and live displays.

Fixed-size circular buffer for SSE events. Oldest events are overwritten when full. Default size: 1000 events.

Revert a deployment to a previous backup state.

Distributed SQLite database with Raft consensus, served by an external rqlited process the daemon supervises. Used for cluster state synchronization. Runs on ports 4001 (HTTP API) and 4002 (Raft consensus). Provides strong consistency across cluster nodes.

Log file archival when size limit exceeded. Old files renamed with numeric suffix (.1, .2, etc.).

go-chi component grouping related API endpoints. Each module exposes its own router via its init() block in modules/<name>/register.go (ce module; ee-only modules under modules/).

One engine per node: docker, podman, incus, or apple (macOS).

Directory for runtime files (PID, socket). User: $XDG_RUNTIME_DIR/shc, System: /run/shc.

Volume type for ephemeral data (caches, temp files). Cleared on reboot. Not backed up.


Adjust the number of replicas for a service.

Cron-based timing for recurring operations (backups, maintenance).

Structure definition for data validation (Go structs with validate: tags, Vault variable schemas).

Hierarchical level in configuration: base, tenant, environment, stack, deployment.

Encrypted value stored in vault. Accessed via !ref+vault://path.

YAML tag (!ref+vault:// or !ref+env://) for referencing secrets or environment variables.

Concurrency control mechanism. Used to limit concurrent operations (e.g., parallel deployments).

Incrementing identifier for SSE events. Enables gap detection and reconnection.

HTTP-based streaming protocol. SHC uses SSE for real-time operation progress and status updates.

Logical grouping of containers defined in compose.yaml. Can have multiple replicas.

Transpiles a live install of a supported platform into an adapted app and pulls its data with it: shc adapter load <adapter> ssh://[user@]host [app].

Extracts a platform app’s data package-free and replays it into the matching native SHC catalog app through a migration recipe: shc adapter migrate <app> --from <src>. A transform into the native app, not a shim around the foreign one.

Semantic container status derived from status, health, exit_code, and restart_policy. Values: starting, running, paused, complete, failed, degraded.

The project itself. CLI tool and server for managing self-hosted applications.

SQLite database file containing all operational data.

Unix socket for CLI-server communication.

Git clone with limited history (--depth 1). Faster than full clone.

The implicit repo of apps that ship inside the SHC package, crawled from the node’s install roots (/usr/share/shc/apps, /usr/lib/shc/apps) rather than fetched, so shc search and the HUD list them with no repo add bootstrap. It is the one sanctioned non-remote repo: reserved name shipped, sentinel URL shipped://apps, daemon-managed end to end: repo add refuses the name, repo rm refuses the row, and the daemon re-creates and re-crawls it at boot and on every sync pass. Its rows are per-node (application.node_id), because two nodes legitimately ship different trees. Spelled builtin / builtin://apps before SHC-506; the daemon migrates that row in place, and both spellings resolve while an estate is mid-roll.

Tab-completion for CLI commands. Supports bash, zsh, fish.

Point-in-time copy of volume data. Uses ZFS/BTRFS instant snapshots or rsync two-pass for traditional filesystems.

What an app provides to other apps. Defines data schema and provisioning jobs.

IPC mechanism for CLI-server communication. Located at {runtime_dir}/shc.sock.

Origin of an app definition: repo, path, git, archive.

Recording the original source of an installed deployment for upgrades.

Historical concept. In the current architecture, events and logs are processed directly without intermediate spool files.

SHC uses Go’s database/sql (the sqlite driver single-node, the rqlite driver in cluster mode) for database operations. No ORM layer.

Embedded SQL database. SHC stores all operational data in SQLite.

Settings for Server-Sent Events: buffer_size, max_connections, heartbeat_interval, etc.

Prometheus metrics for SSE monitoring: connections, events_emitted, latency, memory, slow_clients.

The name axis of a deployment. Unique per tenant and environment. The running unit is the deployment.

A job that names after: or before:. It runs once per deployment at the install and each update, after its after: services read ready and before its before: services start. Run-once work in an app is a start job, not a service.

System-managed operational data stored in YAML files. Does not cascade. Travels with backups.

Directory for state files and database. User: ~/.local/share/shc, System: /var/lib/shc.

Per-scope state file containing system-generated values (ports, IDs, timestamps).

Lifecycle state of a container, service, or deployment. See: Operational Status, Derived Status. On the container row, status is the raw container state the runtime reports: created, running, paused, restarting, exited, dead.

Progress milestone in a long-running operation. Emitted as SSE step events.

Status indicating intentional shutdown via shc stop. Deployments with stopped=True don’t auto-start.

Path within a git repository containing the app definition. Specified via --path flag or fragment syntax.

Update local cache from remote source (repository sync, backup cache sync).

Linux service manager. SHC server runs as a systemd service.

A mount whose source is an absolute host path. Refused, except a short list of read-only system files (/etc/localtime, /etc/timezone, /dev/urandom, /dev/random). /var/run/docker.sock mounts the deployment’s own broker socket, never the host’s. Not backed up.


Component that follows log output in real-time. ContainerLogTailer tails Docker container logs.

Background job executed by queue workers.

Jinja2 file with variable placeholders. Processed before YAML parsing.

Top-level isolation boundary. Each tenant has separate deployments, config, and secrets.

Collection of worker threads for parallel operations. Configurable size.

Duration for event deduplication. SHC uses 5-second windows.

Transport Layer Security. Encryption for HTTPS connections. Managed by Traefik via ACME.

Authentication credential for private git repositories. Never stored permanently.

Distributed tracing record. SHC exports traces via OpenTelemetry.

Cloud-native reverse proxy. SHC uses Traefik for ingress routing and TLS termination.

Time To Live. Duration before expiration (operation_ttl, leader_ttl).

Terminal device. SHC uses different output formats for TTY vs non-TTY.


Event hierarchy (container → service → deployment) with consistent derived status.

Remove a deployment and its resources. Deletes containers, networks, and optionally volumes.

IPC mechanism for local communication. SHC server listens on Unix socket.

Update a deployment to a new version or configuration.

SHA-256 hash of normalized git URL. Used for cache directory naming.


Checking correctness of configuration, variables, and app definitions.

Extension template that installs into a parent app. Examples: WordPress plugins, Keycloak realms. Shipped as <name>.vapp.yaml beside the parent’s app.yaml. The vapp is the template; an installed one is a Vdeployment. See also: Add-on, VPlug, VSocket, VVars.

Configurable value in app definition. Defined in vars.yaml with type, default, validation.

Variable definition file specifying schema, defaults, and validation rules.

Encrypted secret storage. Secrets are scoped and inherit through the hierarchy.

External secret management service (AWS Secrets Manager, HashiCorp Vault, 1Password).

An installed VApp: the thing a shc install <parent>/<vapp> produces. Its host is the parent deployment. The v-family completes symmetrically: app : deployment :: vapp : vdeployment, alongside vvars, vplug, vsocket. (There is no vpreset half any more: add-ons are one flat file shape that declares its own target.)

A vdeployment is deployment-shaped, not deployment-stored: it shares a deployment’s whole resolve half (name → repo → version pin → add-on → vars → async operation) and has none of the run half (compose project, containers, network, directory, placement, health); that half belongs to its host. The “v” is what says so, and it is why a vdeployment has no row in the deployment table.

App release identifier. Extracted from app.yaml or defaults to “latest”.

A cluster node that participates in leader election and Raft consensus. Voter nodes must maintain quorum for write operations. Non-voter nodes can read data but don’t participate in elections. See also: Leader, Quorum.

Vault export file. JSON format with version, encryption flag, and base64-encoded secrets.

Docker persistent storage. Types: named volumes, bind mounts, tmpfs.

Plug definition for VApp integration with parent.

Socket definition for what a VApp provides.

Variable values for a Vdeployment. Stored in {instance}.{vapp}.vvars.yaml.


shcd watchdog, a process outside shcd, stops containers labelled shc.single_writer once the node’s lease has expired.

HTTP callback for notifications. SHC supports webhook notifications for events.

Background process executing tasks from the queue.


freedesktop.org Base Directory Specification. Defines standard locations for config, data, cache, runtime files.

Environment variable for user cache directory. Default: ~/.cache.

Environment variable for user config directory. Default: ~/.config.

Environment variable for user data directory. Default: ~/.local/share.

Environment variable for user runtime directory. Typically /run/user/{uid}.

Environment variable for user data/state directory. Default: ~/.local/share. SHC uses this for state_home in non-root mode.


YAML Ain’t Markup Language. Primary configuration format for SHC.


Zettabyte File System. Copy-on-write filesystem supporting instant snapshots. SHC detects ZFS for efficient backups.

Archive format (.zip). Supported for archive source installation.


Default deduplication time window for Docker events in handle_event().

Default health monitor poll interval.

PBKDF2 iteration count for vault key derivation (OWASP recommendation).

Default ring buffer size per SSE operation.

YAML tag for vault secret reference. Resolved during template processing.

YAML tag for environment variable reference.

Prefix for converter output archives in backup data/ directory (e.g., @database.tar).

One-off backup archive file extension (AR format). Produced only when an operator names an output location: shc backup create --file <dir|path> or shc backup export -i <id> --file <dir|path>; there is no default folder. A .bak supports three things and no others: restore directly from it (shc backup restore --file), hand it to someone, or ingest it into the indexed store (shc backup import). It is not indexed, not encrypted, and never reclaimed by retention.

Export artifact file extension.

Mermaid diagram source file extension.

Vault export file extension.


Event codes follow the pattern V{severity}{module}{sequence}{mnemonic}:

  • V200 - Success (2xx)
  • V400 - Client error (4xx)
  • V404 - Not found
  • V500 - Server error (5xx)
  • 100 - Stack operations
  • 200 - Config operations
  • 300 - Vault operations
  • 400 - Health/status operations
  • A200100STKINS - Stack installed
  • A200102STKUPD - Stack updated
  • V500320STKERR - Stack transitioned to error
  • A200300VLTCRT - Vault secret created
  • V200320STKRUN - Stack transitioned to running
  • V200322STKDGR - Stack transitioned to degraded

  • starting - Initializing or health check pending
  • running - Running and healthy
  • paused - Processes suspended
  • complete - Job finished successfully (exit 0)
  • failed - Job failed (exit ≠ 0, no retry)
  • degraded - Unexpected state
  • stopped - Desired replicas = 0
  • starting - Any container starting
  • running - All replicas running
  • complete - All jobs complete
  • failed - All jobs failed
  • degraded - Partial availability
  • created - After install, before start
  • starting - Start in progress
  • stopping - Stop in progress
  • updating - Upgrade in progress
  • removing - Uninstall in progress
  • running - All services running
  • degraded - Any service degraded
  • complete - All services complete
  • failed - All services failed
  • stopped - All services stopped
  • unknown - No containers
  • unhealthy - Any container unhealthy
  • starting - Health check pending
  • healthy - All health checks passing
  • none - No health checks defined