Adapter reference
Generated file. Do not edit by hand. Regenerate from the repo root with
CGO_ENABLED=0 go run scripts/gen-adapters-md.go.
Adapters connect SHC to other self-hosting platforms. Each adapter understands one platform’s app grammar and on-box layout, and powers two verbs:
shc adapter loadtranspiles a live install of the platform into an adapted app, an SHC app that runs on SHC, and pulls the app’s data with it.shc adapter migrate --fromextracts a platform app’s data package-free and replays it into the matching native SHC catalog app through a migration recipe: a transform into the native app, not a shim around the foreign one.
See the glossary: Adapter,
Adapted app,
shc adapter load,
shc adapter migrate.
Source of truth is the capability registry
(modules/adapter/capabilities.go);
shc adapter ls renders the same registry live from your binary.
Column key: Load / Migrate: the two verbs above. Env
capture: how live env/secret values are captured from the box
(none, file: <path>, or live-inspect: <mechanism>). Secret
minting: how foreign values classify as secrets and mint
(typed-schema | fixed | heuristic | none). Vars: whether the
foreign config grammar lowers into the typed vars DSL. Plugs:
whether platform addons map onto SHC capability socket+plug pairs.
Quiesce: the pause mechanism wrapped around a data pull so the
capture is a consistent point-in-time copy. Load proven /
Migrate proven are the validation honesty markers, tracked
SEPARATELY per verb (a live-proven load says nothing about migrate):
live = driven end-to-end against a real platform box; fixture =
fixture / fake-box + conformance validated only; unproven = no
meaningful validation yet; n/a, not supported = the verb is absent
by design (not a debt).
Total: 17 platforms: 15 load + migrate, 2 migrate-only.
Compose-based adapters
Section titled “Compose-based adapters”These platforms define apps as Docker Compose, plain or with a manifest riding alongside, and transpile through the shared compose core.
| Adapter | Load | Load proven | Migrate | Migrate proven | Env capture | Secret minting | Vars | Plugs | Quiesce |
|---|---|---|---|---|---|---|---|---|---|
| casaos | yes | live-once | yes | live-once | compose-derived: installed compose env, values carried on Package.Secrets | heuristic | yes | no | async casaos-cli app-management stop + compose-project drain poll |
| coolify | yes | live-once | yes | fixture | file: /data/coolify/services/<uuid>/.env | typed-schema | yes | no | docker compose -p <uuid> stop, no drain poll |
| dockge | yes | live-once | yes | live-once | file: /opt/stacks/<id>/.env | heuristic | yes | no | cd /opt/stacks/<id> && docker compose stop, synchronous |
| dokploy | yes | live-once | yes | live-once | file: /etc/dokploy/compose/<appName>/code/.env | heuristic | yes | no | docker compose -p <appName> stop + drain poll; composeType=stack has no non-destructive stop, so a live pull |
| elestio | yes | unproven | yes | unproven | file: /opt/app/.env, the compose-default reading of the dashboard pairing, uncaptured | heuristic | yes | no | cd /opt/app && docker compose stop, docker-compose as the fallback + drain poll |
| runtipi | yes | live-once | yes | live-once | file: runtipi/app-data/<store>/<id>/app.env | typed-schema | yes | no | sudo runtipi-cli app stop + compose-project drain poll |
| synology | yes | fixture | yes | fixture | compose-derived: project <share>/.env, values carried on Package.Secrets, docker-inspect as the backstop | heuristic | yes | no | sudo docker compose -p <project> stop by absolute path + compose-project drain poll |
| truenas | yes | fixture | yes | fixture | compose-derived: rendered compose inline env, values carried on Package.Secrets, docker-inspect as the backstop | heuristic | yes | no | docker compose -p ix-<app> stop + drain poll; app.stop is destructive and async |
| umbrel | yes | live-once | yes | live-once | live-inspect: docker inspect <compose-project> env | fixed | yes | yes | docker stop by compose-project label + drain poll |
Own-transpiler adapters
Section titled “Own-transpiler adapters”These platforms have their own app grammar (JSON, XML, or template manifests, no compose upstream); each adapter ships a dedicated transpiler.
| Adapter | Load | Load proven | Migrate | Migrate proven | Env capture | Secret minting | Vars | Plugs | Quiesce |
|---|---|---|---|---|---|---|---|---|---|
| caprover | yes | live-once | yes | live-once | none | typed-schema | yes | no | docker service scale srv-captain--<app>=0 with a replica stash + drain poll, on a manager only |
| cloudron | yes | live-once | yes | live-once | none | fixed | yes | yes | no-op: the native backup tarball is a point-in-time snapshot |
| easypanel | yes | fixture | yes | fixture | compose-derived: state-store env block + db password fields, values carried on Package.Secrets | heuristic | yes | no | async docker service scale <project>_<svc>=0 + drain poll + replica restore |
| portainer | yes | live-once | yes | live-once | live-inspect: docker inspect <container> env | heuristic | yes | no | docker stop <container>, no sudo shim, no drain poll |
| shc | yes | live-once | no | n/a: not supported | none | none | yes | no | docker stop by com.docker.compose.project label + drain poll on the docker runtime; swarm captures live |
| unraid | yes | fixture | yes | fixture | compose-derived: my-<Name>.xml Config values, carried on Package.Secrets | typed-schema | yes | no | docker stop -t 10 <Name> + drain poll, over root ssh |
Migrate-only sources
Section titled “Migrate-only sources”Nothing loads from these platforms: their apps cannot run on SHC as adapted apps.
shc adapter migrate extracts the app’s data package-free and replays it into the
matching native SHC app through a migration recipe.
| Adapter | Load | Load proven | Migrate | Migrate proven | Env capture | Secret minting | Vars | Plugs | Quiesce |
|---|---|---|---|---|---|---|---|---|---|
| kube | no | n/a: not supported | yes | live-once | none | none | no | no | kubectl scale deploy/sts to 0 with a replica stash + pod-drain poll + helper-pod PVC stage |
| yunohost | no | n/a: not supported | yes | fixture | none | none | no | no | no-op: yunohost backup create is an operator-run point-in-time snapshot |
Per-adapter crown limits
Section titled “Per-adapter crown limits”One line per adapter: where the importer reads the platform’s install tree from (“live-synthesized catalog” means the platform keeps no static manifest tree, so the catalog is reconstructed over SSH from the live engine), and the adapter’s headline limit.
- caprover: live-synthesized catalog (root
/captain/data). limited load: only image-based apps (~84% of the catalog) load; built-from-source apps (img-captain-*images) are load-rejected but stay fully migrate-capable. - casaos: box tree
/var/lib/casaos/apps. no resolved env file exists on the box, so an imported datastore keeps the source box’s plaintext credentials while the adapted package re-mints fresh values at deploy, and the load report cannot flag the mismatch. - cloudron: box tree
/var/backups/snapshot. shared postgres/mysql/mongo/redis addon dumps inside the backup tarball are not imported: an app without a self-dump contract imports configured-but-empty; the tarball import path has no end-to-end proof. - coolify: box tree
/data/coolify/services. one-click services subset only; migrate recipes ship (gitea, invoice-ninja/mariadb) but no live-box migrate has been driven green end to end. - dockge: live-synthesized catalog (root
/opt/stacks). stacks hold app data as relative binds beside the compose, so the catalog fetch is per-stack config-only; expect a high gate-reject rate, since dockge stacks are arbitrary user compose. - dokploy: box tree
/etc/dokploy/compose.composeType=stackapps have no non-destructive stop upstream (dokploy’s own stop isdocker stack rm), so their quiesce is a no-op and the pull is effectively live. - easypanel: live-synthesized catalog (root
/etc/easypanel). the platform’s headline source-build deploys (github/git/dockerfile/nixpacks/buildpacks) carry no pullable image and load-reject, as do box and wordpress services; the catalog is read from easypanel’s LMDB store inside its own container, so the load needs root or passwordless sudo on the box. - elestio: box tree
/opt/app. catalogue-starved: the per-service definition repos were withdrawn and the public template API is metadata-only, sorepo addrefuses (X400946REPCST).shc adapter loadagainst a live box is the entire surface; normalize is the identity until a real box capture proves whether the nginx-auto-ssl/cloudgate front proxy lives inside the compose. - kube: live-synthesized catalog. no live cluster has run this path, so PVC/RWO/CSI fidelity must be proven on a real cluster; the Kubernetes-to-compose load lowering is a later increment.
- portainer: live-synthesized catalog (root
/var/lib/docker/volumes). quiesce is a plaindocker stopwith no sudo shim and no drain poll, so a passwordless-sudo-but-no-docker-group login silently degrades every pull to a live capture; live env values are never seeded into secrets. - runtipi: box tree
runtipi/apps. thebackup.yamlephemeral-volume exclusion is a substring heuristic, so a data volume named…cache…is wrongly excluded. - shc: live-synthesized catalog (root
/var/lib/shc/deployments). vault-backed secret VALUES never travel:ref+vault://references are carried verbatim and every secret-typed var reports in MissingSecrets, so the target vault must be pre-seeded before the imported app is started or it will meet freshly minted credentials its restored datastore does not accept; integration edges, vdeployments, ledger/audit history, scheduled-backup config and the protection flag are cluster state and are not carried either, and the deployments tree is node-local (point the ssh target at the node that RUNS the app). - synology: live-synthesized catalog (root
/var/packages/ContainerManager/etc/projects). a project’s live values ride its<share>/.env, whose box path is not recoverable from the importer’s handle, so no live-secret seeding is wired;.spk-packaged apps are out of scope. - truenas: box tree
/mnt/.ix-apps/app_configs.host_pathstorage points at arbitrary, multi-TB SMB-shared user datasets and is treated as an external reference, never captured; onlyix_volumeand docker named volumes travel. - umbrel: box tree
umbrel/app-data. never live-imported; only the curatedexports.shprofiles (bitcoin, electrs) lower manifest dependencies onto plugs. Every other dependencies/exports.sh app gates. - unraid: box tree
/boot/config/plugins/dockerMan/templates-user.ExtraParamsis a raw docker-run flag string. The adapter tokenizes it and folds each dangerous flag onto the synthesized compose so the shared gate rejects it; manifests (USB flash) and data (array) live on disjoint filesystems. - yunohost: box tree
/home/yunohost.backup/archives. migrate-only by design: apps are Debian packages over a shared server-side database, so nothing can load; migration recipes are the scarce resource.