Skip to content
SHC Docs

shc clone

The shc clone command creates a duplicate of a running deployment, enabling testing, staging environments, or development copies.

Clone creates a copy of a stack while keeping the original intact. It shares infrastructure with the move command but preserves the source stack.

OperationFlowOriginal Stack
CloneBackup -> RecoverKept
MoveBackup -> Uninstall -> RecoverDeleted

Create a duplicate of a stack:

Terminal window
# Clone under a new name
shc clone myapp myapp-clone
# Clone and say where the copy may run
shc clone myapp myapp-prod --where 'location=hetzner/hel1'
# Clone with all connected stacks (integrations)
shc clone myapp myapp-prod --all-connections
# Clone to different environment
shc clone myapp myapp-staging --target-environment staging
# Clone to different tenant (requires permission)
shc clone myapp myapp-copy --target-tenant other-org
# Dry run (preview without executing)
shc clone myapp myapp-clone --dry-run
ArgumentRequiredDescription
<source>YesSource stack name
<new-name>YesTarget stack name (positional)
FlagDefaultDescription
--where <selector>noneWhere the copy may run, in place of the source’s own --where
--prefer <selector>noneWhich of those nodes the copy should run on, in place of the source’s own --prefer
--target-environmentsameTarget environment
--target-tenantsameTarget tenant (requires permission)
--all-connections, -afalseClone entire integration graph
--rename, -rnoneRename dependencies: old:new,old2:new2
--dry-runfalseShow what would be cloned
Terminal window
# Create a test copy of production database
shc clone postgres postgres-test
# Output:
# Cloning postgres -> postgres-test
# v Backing up postgres
# v Recovering postgres-test
# Clone complete

When a stack has integrations (plugs/sockets), you must use --all-connections to clone the entire graph:

Terminal window
# Clone app and its database together
shc clone myapp myapp-staging --all-connections
# Clone with dependency renaming
shc clone myapp myapp-test --all-connections --rename postgres=postgres-test

Without --all-connections, cloning a stack with dependencies will fail:

Terminal window
$ shc clone nextcloud nextcloud-test
Error: Stack 'nextcloud' has dependencies that would be orphaned:
- postgres (provides: postgres-socket)
Use --all-connections to clone the entire integration graph, or
unplug dependencies first.

A clone names no node. The copy is a new deployment, and the placement engine puts it where an install would go: it reads the source deployment’s own --where and --prefer, or the ones given on the clone in their place, and picks a node that matches. They are recorded on the copy once the clone has succeeded, so shc constraint ls and shc explain show them afterwards.

Terminal window
# The copy keeps the source's rules and adds one of its own
shc clone myapp myapp-prod --where 'location=hetzner/hel1' --all-connections
# --dry-run places the copy and prints the plan without cloning anything
shc clone myapp myapp-prod --where 'location=hetzner/hel1' --dry-run

A clone that passes --node is refused with X400242SELFLG, which names the --where to write instead (ce core/selector/flags.go); -n is an unknown flag; and the API refuses a request body that carries node or node_id (X400647CLNNOD). A clone whose rules leave no node is refused by name before anything is backed up.

When the copy lands on another node, the clone performs a full backup -> recover cycle and the data is transferred there.

Terminal window
# Create staging copy from production
shc clone myapp myapp --target-environment staging
# Note: Same stack name is allowed when environment differs

When cloning to the same node (only name change), SHC uses a fast rename path instead of full backup/recover. This renames:

ResourcePattern
Deployment recorddeployment.stack_name column
Deployment directory{base}/deployments/{tenant}/{stack}/{environment}/
App directory{base}/apps/{tenant}/{stack}/
Docker Compose project{tenant}_{environment}_{stack}
Docker volumes{tenant}_{environment}_{stack}_{volume}
Vault secretstenants/{tenant}/stacks/{stack}/...
Schedule recordsschedule.stack_name column
Backup cachebackup_cache.stack_name column
ScenarioBehavior
No --all-connectionsReintegrates with existing providers (shares integrations); the copy is held to the source’s node, where those providers are read, and a --where that leaves that node out is refused
--all-connectionsClones all connected stacks (full backup + recover); the set lands together on the node the engine picks, and each member’s own rules must allow it
--all-connections, a peer left behindThe set is held to the source’s node until --closure carries the peer too
Auto-suffix on collisionDependencies get -1, -2, etc. suffix

Clone always requires a different name, environment, or tenant from the source:

Terminal window
# These will fail (same name in same scope)
$ shc clone myapp myapp
Error: Target stack 'myapp' already exists in tenant 'default', environment 'default'
# These work (different scope)
shc clone myapp myapp --target-environment staging # Different environment
shc clone myapp myapp --target-tenant other-org # Different tenant
shc clone myapp myapp-copy # Different name
  1. Preflight - Validate target doesn’t exist, check quota
  2. Backup - Create coordinated backup of source stack(s)
  3. Recover - Deploy to target with new name/location
  4. Integrate - Re-establish integrations (if applicable)