support clone and restore from specific dir (#22)

* snapshot: extract ReadSnapshotEnvelope shared helper

Move the canonical snapshot.json envelope read/write into the snapshot
package so cmd/vm can consume an envelope-bearing directory directly
(needed for the upcoming \`vm clone --from-dir\` and
\`vm restore --from-dir\` paths) without depending on localfile internals.

- snapshot.SnapshotJSONName + envelopeVersion (single const block).
- snapshot.ReadSnapshotEnvelope(dir) parses + version-checks; returns
  ErrEnvelopeMissing when the file is absent so callers can surface a
  precise message instead of a generic open error.
- snapshot.WriteSnapshotEnvelope(dir, cfg) writes via AtomicWriteJSON.
- localfile/export.go now references snapshot.SnapshotJSONName.
- localfile/import.go readAndRemoveSnapshotJSON delegates the parse to
  the shared helper; remove-after-read semantics preserved.

* snapshot: add export --to-dir for directory-based handoff

Adds the snapshot.DirectoryExporter optional interface and a
LocalFile.ExportToDir implementation. The dir form pairs with the
upcoming \`vm clone --from-dir\` and \`vm restore --from-dir\`,
giving users an rsync-friendly handoff path without a tar round-trip.

- snapshot.DirectoryExporter: ExportToDir(ctx, ref, dir) error
- LocalFile.ExportToDir: rejects non-empty target dirs to avoid silently
  merging into an unrelated tree, writes a fresh snapshot.json envelope
  via WriteSnapshotEnvelope, then ReflinkCopy's each data file. Reflink
  is zero-cost on btrfs/xfs and falls back to plain copy elsewhere; the
  result is always standalone (rsync-friendly), unlike the hardlinks
  DirectClone uses internally for memory pages.
- cmd/snapshot: --to-dir flag, mutually exclusive with --output/--gzip.

* vm: clone --from-dir for arbitrary snapshot directories

Lets users clone from any directory containing a snapshot.json envelope
(e.g. an extracted export.tar, an rsync'd \`snapshot export --to-dir\`
result, or an NFS-mounted golden image) without first registering the
snapshot in the local DB.

- cloneCmd args relaxed to MaximumNArgs(1); positional SNAPSHOT and
  --from-dir are mutually exclusive (validated in the handler so the
  error message names both forms).
- cloneFromDir reads the envelope, routes to the matching backend by
  cfg.Hypervisor, asserts hypervisor.Direct, then funnels through the
  same DirectClone path as the snapshot-DB form.
- cloneDirect refactored to share cloneFromSrcDir with cloneFromDir so
  the prepareClone → DirectClone → finalize sequence isn't duplicated.

The dir is read-only across the call so multiple clones of the same dir
(golden image use case) are safe. Trust boundary unchanged: existing
ValidateMetaPaths still rejects envelopes whose storage paths escape
the local rootDir/runDir.

* vm: restore --from-dir with --force ownership gate

Symmetric with \`vm clone --from-dir\` but with an extra safety check:
the envelope's snapshot ID must belong to vm.SnapshotIDs unless --force.
This keeps the typical cross-host "sync the same VM's backup over here"
flow zero-friction while making "use unrelated state to overwrite this
VM" an explicit, opt-in operation (data-loss footgun otherwise).

- restoreCmd args relaxed to RangeArgs(1, 2); positional SNAPSHOT and
  --from-dir are mutually exclusive (handler-validated).
- restoreFromDir reads the envelope, resolves the VM's hypervisor,
  asserts hypervisor.Direct, runs the same NIC-count + resource-flag
  validation as the snapshot-DB form, then DirectRestore over the dir.
- --force does NOT add the envelope's ID to vm.SnapshotIDs — restoring
  doesn't change ownership semantics, the foreign snapshot remains
  external to this VM's lineage.

* docs: --from-dir + --to-dir directory-based snapshot workflow

Bullet point in features + extended export flag table + a worked example
covering the three flows: golden image clone, cross-host same-VM
restore, force-overriding a foreign-lineage restore.

* style: trim verbose godoc on the new envelope/clone/restore paths

Comments per SKILL.md should explain WHY, not narrate or restate the
signature. This pass keeps the load-bearing rationale (atomic write
reason, soft-gate semantics, reflink-vs-hardlink trade-off) and
collapses the rest.

* snapshot: write envelope last in ExportToDir as completion marker

ExportToDir wrote snapshot.json before copying payload files. A
concurrent \`vm restore --from-dir\` reading the envelope could pass
preflight (which only stat()s presence, not byte-completeness) and kill
the running VM while a memory-range or COW file was still mid-copy,
leaving the source VM in Error state with a partial restore.

Move WriteSnapshotEnvelope to after the copy loop so envelope existence
is now an all-data-ready marker. ensureEmptyDir already guarantees the
dir starts empty, so a stale envelope can't survive into the new
export.

* snapshot: envelope helpers take/return SnapshotConfig by value

Returning *types.SnapshotConfig forced an awkward
\`return &envelope.Config\` and a \`*cfg\` deref inside Write.
SnapshotConfig is small (no identity, embedded Config + a few scalars +
a map ref) so copying is cheap; switching to value drops the pointer
dance in the helper bodies. Callers that need a pointer downstream now
take \`&cfg\` once at the call site, which is symmetric with how every
other local SnapshotConfig in cocoon is handled.

readAndRemoveSnapshotJSON in snapshot/localfile/import.go follows the
same shift; the Import flow now embeds cfg by value into the
SnapshotRecord literal instead of dereferencing.

* snapshot+vm: SnapshotConfig flows by value through read-only paths

snapshot.Direct.DataDir, snapshotRecordToConfig, CloneVMConfigFromFlags,
RestoreVMConfigFromFlags, mergeResourceFlags, prepareClone,
cloneFromSrcDir, validateFCCloneOverrides — all of these previously
took or returned *types.SnapshotConfig but only ever read fields. The
chain forced \`return &cfg\` / \`*cfg\` / \`&cfg\` dances at every layer.

Switch to value semantics inside the cmd-layer + snapshot-backend
boundary; the hypervisor backend interface (Clone / DirectClone) keeps
*SnapshotConfig because that's the wider stable API surface, and the
single deref happens at that boundary. SnapshotConfig is small (no
identity, embedded Config + a few scalars + a map ref) so the copy is
cheap and pointer-only mattered for sharing semantics that nothing
actually used here.

* snapshot: Snapshot.Restore returns SnapshotConfig by value

Mirrors the DataDir flip: the snap-DB-side Restore was the only place
in the cmd/vm clone path that still forced \`*cfg\`/\`&cfg\` dancing.
Drop the pointer return on the interface, value-out from LocalFile, and
the cmd-side caller derefs once at the hypervisor boundary just like
DirectClone.

* vm: extract snapshotSource helper for --from-dir vs positional SNAPSHOT

Clone and Restore had near-identical mutex / required-arg blocks; the
only difference was the leading-positional count (0 for clone where
SNAPSHOT is the only arg, 1 for restore where args[0] is VM). Capture
that as baseArgs and let the helper return (fromDir, snapRef) with
exactly one non-empty.

* snapshot: inline ensureEmptyDir into ExportToDir

Single caller (the new ExportToDir); the helper added a function-call
indirection without earning it. Inline the 8-line check; the comment
above the block carries the rationale (no silent merge into an unrelated
tree).

* vm+snapshot: /code+/simplify followups

- ExportToDir: replace inline mkdir + 3-state switch with utils.EnsureDirs
  (existing 0o750 helper); drop the dead snapshot.json skip in the copy
  loop since registered DataDir results never carry the envelope (Create
  doesn't write it; Import removes it via readAndRemoveSnapshotJSON).
- run.go: 'nic count mismatch' -> 'NIC count mismatch' (ALL-CAPS acronym
  rule); fixes both restoreFromDir and the pre-existing legacy Restore
  message for consistency.
- cloneFromDir: copy *config.Config locally before flipping
  UseFirecracker so the mutation doesn't leak to the caller's shared
  conf (CLI tolerates it; daemons embedding cocoon would notice).
- restoreCmd: PreRunE rejects --force without --from-dir so misuse fails
  loud instead of silently no-op.

* vm: extract runDirectRestore to share between restoreDirect and restoreFromDir

restoreDirect (snapshot-DB path) and restoreFromDir (--from-dir path)
duplicated the wantJSON-log + DirectRestore + output tail. Pull it out
into a single helper, parameterized by sourceLabel. -7 lines net.

* snapshot: export EnvelopeVersion + add DirectoryExporter compile-time check

Two strict-walk findings:

1. snapshot/localfile/export.go:80 had a literal Version: 1 that should
   reference the snapshot package's version constant. Promote
   envelopeVersion -> EnvelopeVersion (exported) and use
   snapshot.EnvelopeVersion at the cross-package call site. Future
   format bumps now have one source of truth.

2. localfile.LocalFile didn't carry a compile-time assertion against
   snapshot.DirectoryExporter (the new interface). Add it alongside the
   existing Snapshot/Direct/CompressedExporter checks so signature drift
   in either direction surfaces at build time.

Author: CMGS

README.md

@@ -20,7 +20,8 @@ Lightweight MicroVM engine with dual hypervisor backends: [Cloud Hypervisor](htt
 - **Graceful shutdown** — ACPI power-button for UEFI VMs with configurable timeout, fallback to SIGTERM → SIGKILL
 - **Interactive console** — `cocoon vm console` with bidirectional PTY relay, SSH-style escape sequences (`~.` disconnect, `~?` help), configurable escape character, SIGWINCH propagation
 - **Snapshot & clone** — `cocoon snapshot save` captures a running VM's full state (memory, disks, config); `cocoon vm clone` restores it as a new VM with fresh network and identity, resource inheritance with validation
-- **Snapshot export & import** — `cocoon snapshot export` packages a snapshot into a portable `.tar.gz` archive (with sparse-aware pax headers); `cocoon snapshot import` restores it on another host or cluster; supports piping via stdout/stdin for direct host-to-host transfer
+- **Snapshot export & import** — `cocoon snapshot export` packages a snapshot into a portable `.tar.gz` archive (with sparse-aware pax headers); `cocoon snapshot import` restores it on another host or cluster; supports piping via stdout/stdin for direct host-to-host transfer; `--to-dir` writes a directory form (with `snapshot.json` envelope) for NFS / rsync-friendly handoff
+- **Clone / restore from a directory** — `cocoon vm clone --from-dir DIR` and `cocoon vm restore --from-dir DIR` consume any directory containing a `snapshot.json` envelope without first registering the snapshot in the local DB; the dir is treated as read-only so multi-VM golden-image use cases work without copying
 - **Live status monitoring** — `cocoon vm status` watches VM state changes in real time via fsnotify, with refresh mode (top-like) and event-stream mode (append-only, for scripting and vk-cocoon integration)
 - **Docker-like CLI** — `create`, `run`, `start`, `stop`, `list`, `inspect`, `console`, `rm`, `debug`, `clone`, `status`
 - **Structured logging** — configurable log level (`--log-level`), log rotation (max size / age / backups)
@@ -229,6 +230,10 @@ Applies to `cocoon snapshot export`:
 | Flag            | Default                    | Description                                       |
 | --------------- | -------------------------- | ------------------------------------------------- |
 | `--output`, `-o` |  `<name-or-id>.tar.gz`    | Output file path (`-` for stdout)                 |
+| `--gzip`        | `false`                    | Compress output with gzip                         |
+| `--to-dir`      |                            | Export into a directory (must be empty/absent) instead of a tar; pairs with `vm clone --from-dir` |
+
+`--to-dir` writes a `snapshot.json` envelope alongside reflink-copied data files. Useful for NFS golden images or rsync-friendly handoff: `cocoon snapshot export snap -o ... --to-dir /nfs/golden && rsync ...`. Mutually exclusive with `--output` and `--gzip`.
 
 ### Import Flags
 
@@ -241,6 +246,25 @@ Applies to `cocoon snapshot import`:
 
 When FILE is omitted, data is read from stdin. This enables piping: `cocoon snapshot export snap1 -o - | ssh host2 cocoon snapshot import --name snap1`.
 
+### Direct Clone / Restore From a Directory
+
+`vm clone --from-dir DIR` and `vm restore --from-dir DIR` accept any directory containing a `snapshot.json` envelope (output of `snapshot export --to-dir`, or an extracted `.tar`). The snapshot does not need to be in the local snapshot DB:
+
+```bash
+# Build a portable snapshot dir, ship it, clone from it:
+cocoon snapshot export my-snap --to-dir /nfs/golden
+# ... rsync /nfs/golden to host B if needed ...
+cocoon vm clone --from-dir /nfs/golden --name fresh-vm --pull
+
+# Restore the same VM's externally-staged backup (envelope ID matches → silent OK):
+cocoon vm restore my-vm --from-dir /sync/from-host-a
+
+# Force-restore a foreign snapshot (acknowledges data-loss risk):
+cocoon vm restore my-vm --from-dir /unrelated/lineage --force
+```
+
+The dir is read-only across the call, so multiple clones of the same dir (golden image use case) are safe. Pass `--pull` if the base image's blobs may not be present locally — `EnsureImage` reads `image_blob_ids` from the envelope and pulls as needed.
+
 ### Status Flags
 
 Applies to `cocoon vm status`:

cmd/core/helpers.go

@@ -365,7 +365,7 @@ func VMConfigFromFlags(cmd *cobra.Command, image string) (*types.VMConfig, error
 }
 
 // CloneVMConfigFromFlags builds VMConfig for clone (inherits from snapshot).
-func CloneVMConfigFromFlags(cmd *cobra.Command, snapCfg *types.SnapshotConfig) (*types.VMConfig, error) {
+func CloneVMConfigFromFlags(cmd *cobra.Command, snapCfg types.SnapshotConfig) (*types.VMConfig, error) {
 	vmName, _ := cmd.Flags().GetString("name")
 	flagNetwork, _ := cmd.Flags().GetString("network")
 	network := cmp.Or(flagNetwork, snapCfg.Network)
@@ -410,7 +410,7 @@ func CloneVMConfigFromFlags(cmd *cobra.Command, snapCfg *types.SnapshotConfig) (
 }
 
 // RestoreVMConfigFromFlags builds VMConfig for restore (allows overrides).
-func RestoreVMConfigFromFlags(cmd *cobra.Command, vm *types.VM, snapCfg *types.SnapshotConfig) (*types.VMConfig, error) {
+func RestoreVMConfigFromFlags(cmd *cobra.Command, vm *types.VM, snapCfg types.SnapshotConfig) (*types.VMConfig, error) {
 	result := vm.Config // value copy — keep current VM values
 
 	cpu, memBytes, storBytes, err := mergeResourceFlags(cmd, result.CPU, result.Memory, result.Storage, snapCfg)
@@ -570,7 +570,7 @@ func sanitizeVMName(image string) string {
 	return n
 }
 
-func mergeResourceFlags(cmd *cobra.Command, cpu int, memory, storage int64, snapCfg *types.SnapshotConfig) (int, int64, int64, error) {
+func mergeResourceFlags(cmd *cobra.Command, cpu int, memory, storage int64, snapCfg types.SnapshotConfig) (int, int64, int64, error) {
 	cpuFlag, _ := cmd.Flags().GetInt("cpu")
 	memStr, _ := cmd.Flags().GetString("memory")
 	storStr, _ := cmd.Flags().GetString("storage")

cmd/snapshot/commands.go

@@ -63,6 +63,9 @@ func Command(h Actions) *cobra.Command {
 	}
 	exportCmd.Flags().StringP("output", "o", "", "output file path (default: <name-or-id>.tar)")
 	exportCmd.Flags().Bool("gzip", false, "compress output with gzip")
+	exportCmd.Flags().String("to-dir", "", "export into a directory (must be empty/absent) instead of a tar; pairs with `vm clone --from-dir`")
+	exportCmd.MarkFlagsMutuallyExclusive("to-dir", "output")
+	exportCmd.MarkFlagsMutuallyExclusive("to-dir", "gzip")
 
 	importCmd := &cobra.Command{
 		Use:   "import [FILE]",

cmd/snapshot/handler.go

@@ -174,6 +174,20 @@ func (h Handler) Export(cmd *cobra.Command, args []string) (err error) {
 	ref := args[0]
 	output, _ := cmd.Flags().GetString("output")
 	useGzip, _ := cmd.Flags().GetBool("gzip")
+	toDir, _ := cmd.Flags().GetString("to-dir")
+
+	if toDir != "" {
+		exporter, ok := snapBackend.(snapshot.DirectoryExporter)
+		if !ok {
+			return fmt.Errorf("backend does not support directory export")
+		}
+		logger.Infof(ctx, "exporting to dir %s ...", toDir)
+		if err = exporter.ExportToDir(ctx, ref, toDir); err != nil {
+			return fmt.Errorf("export-to-dir: %w", err)
+		}
+		logger.Infof(ctx, "exported: %s", toDir)
+		return nil
+	}
 
 	var stream io.ReadCloser
 	if useGzip {

cmd/vm/commands.go

@@ -1,6 +1,8 @@
 package vm
 
 import (
+	"fmt"
+
 	"github.com/spf13/cobra"
 
 	cmdcore "github.com/cocoonstack/cocoon/cmd/core"
@@ -52,9 +54,9 @@ func Command(h Actions) *cobra.Command {
 	cmdcore.AddOutputFlag(runCmd)
 
 	cloneCmd := &cobra.Command{
-		Use:   "clone [flags] SNAPSHOT",
-		Short: "Clone a new VM from a snapshot",
-		Args:  cobra.ExactArgs(1),
+		Use:   "clone [flags] [SNAPSHOT]",
+		Short: "Clone a new VM from a snapshot (or a directory via --from-dir)",
+		Args:  cobra.MaximumNArgs(1),
 		RunE:  h.Clone,
 	}
 	addCloneFlags(cloneCmd)
@@ -111,15 +113,25 @@ func Command(h Actions) *cobra.Command {
 	cmdcore.AddOutputFlag(rmCmd)
 
 	restoreCmd := &cobra.Command{
-		Use:   "restore [flags] VM SNAPSHOT",
-		Short: "Restore a running VM to a previous snapshot",
-		Args:  cobra.ExactArgs(2),
-		RunE:  h.Restore,
+		Use:   "restore [flags] VM [SNAPSHOT]",
+		Short: "Restore a running VM to a previous snapshot (or a directory via --from-dir)",
+		Args:  cobra.RangeArgs(1, 2),
+		PreRunE: func(cmd *cobra.Command, _ []string) error {
+			force, _ := cmd.Flags().GetBool("force")
+			fromDir, _ := cmd.Flags().GetString("from-dir")
+			if force && fromDir == "" {
+				return fmt.Errorf("--force only applies with --from-dir")
+			}
+			return nil
+		},
+		RunE: h.Restore,
 	}
 	restoreCmd.Flags().Int("cpu", 0, "boot CPUs (0 = keep current)")
 	restoreCmd.Flags().String("memory", "", "memory size (empty = keep current)")
 	restoreCmd.Flags().String("storage", "", "COW disk size (empty = keep current)")
 	restoreCmd.Flags().Bool("on-demand", false, "use UFFD on-demand memory loading for faster restore (CH only; snapshot file must remain on disk)")
+	restoreCmd.Flags().String("from-dir", "", "restore from a snapshot directory (must contain snapshot.json) instead of the local snapshot DB; mutually exclusive with positional SNAPSHOT")
+	restoreCmd.Flags().Bool("force", false, "skip the snapshot-belongs-to-VM check (only meaningful with --from-dir; risk of restoring to an unrelated lineage)")
 	cmdcore.AddOutputFlag(restoreCmd)
 
 	debugCmd := &cobra.Command{
@@ -259,4 +271,5 @@ func addCloneFlags(cmd *cobra.Command) {
 	cmd.Flags().Bool("no-direct-io", false, "disable O_DIRECT on writable disks (inherit from snapshot if not set)")
 	cmd.Flags().Bool("on-demand", false, "use UFFD on-demand memory loading for faster clone (CH only; snapshot file must remain on disk)")
 	cmd.Flags().Bool("pull", false, "auto-pull base image if not found locally (for cross-node clone)")
+	cmd.Flags().String("from-dir", "", "clone from a snapshot directory (must contain snapshot.json) instead of the local snapshot DB; mutually exclusive with positional SNAPSHOT")
 }

cmd/vm/run.go

@@ -79,12 +79,18 @@ func (h Handler) Clone(cmd *cobra.Command, args []string) error {
 	}
 	logger := log.WithFunc("cmd.vm.clone")
 
-	snapBackend, err := cmdcore.InitSnapshot(conf)
+	fromDir, snapRef, err := snapshotSource(cmd, args, 0)
 	if err != nil {
 		return err
 	}
+	if fromDir != "" {
+		return h.cloneFromDir(ctx, cmd, conf, fromDir, logger)
+	}
 
-	snapRef := args[0]
+	snapBackend, err := cmdcore.InitSnapshot(conf)
+	if err != nil {
+		return err
+	}
 
 	// Infer hypervisor backend from the snapshot's Hypervisor field.
 	snapInfo, err := snapBackend.Inspect(ctx, snapRef)
@@ -124,7 +130,7 @@ func (h Handler) Clone(cmd *cobra.Command, args []string) error {
 
 	logger.Infof(ctx, "cloning VM from snapshot %s ...", snapRef)
 
-	vm, cloneErr := hyper.Clone(ctx, vmID, vmCfg, networkConfigs, cfg, stream)
+	vm, cloneErr := hyper.Clone(ctx, vmID, vmCfg, networkConfigs, &cfg, stream)
 	if cloneErr != nil {
 		rollbackNetwork(ctx, netProvider, vmID)
 		return fmt.Errorf("clone VM: %w", cloneErr)
@@ -146,7 +152,13 @@ func (h Handler) Restore(cmd *cobra.Command, args []string) error {
 	logger := log.WithFunc("cmd.vm.restore")
 
 	vmRef := args[0]
-	snapRef := args[1]
+	fromDir, snapRef, err := snapshotSource(cmd, args, 1)
+	if err != nil {
+		return err
+	}
+	if fromDir != "" {
+		return h.restoreFromDir(ctx, cmd, conf, vmRef, fromDir, logger)
+	}
 
 	hyper, err := cmdcore.FindHypervisor(ctx, conf, vmRef)
 	if err != nil {
@@ -170,11 +182,11 @@ func (h Handler) Restore(cmd *cobra.Command, args []string) error {
 	}
 
 	if snapInfo.NICs != len(vm.NetworkConfigs) {
-		return fmt.Errorf("nic count mismatch: vm has %d, snapshot has %d",
+		return fmt.Errorf("NIC count mismatch: vm has %d, snapshot has %d",
 			len(vm.NetworkConfigs), snapInfo.NICs)
 	}
 
-	vmCfg, err := cmdcore.RestoreVMConfigFromFlags(cmd, vm, &snapInfo.SnapshotConfig)
+	vmCfg, err := cmdcore.RestoreVMConfigFromFlags(cmd, vm, snapInfo.SnapshotConfig)
 	if err != nil {
 		return err
 	}
@@ -209,23 +221,91 @@ func (h Handler) Restore(cmd *cobra.Command, args []string) error {
 	return nil
 }
 
+// restoreFromDir runs DirectRestore over an envelope-bearing dir. The
+// envelope's snapshot ID is gated against vm.SnapshotIDs; a foreign ID
+// requires --force so "overwrite VM with unrelated lineage" is opt-in.
+func (h Handler) restoreFromDir(ctx context.Context, cmd *cobra.Command, conf *config.Config, vmRef, dir string, logger *log.Fields) error {
+	cfg, err := snapshot.ReadSnapshotEnvelope(dir)
+	if err != nil {
+		return fmt.Errorf("load envelope: %w", err)
+	}
+	hyper, err := cmdcore.FindHypervisor(ctx, conf, vmRef)
+	if err != nil {
+		return fmt.Errorf("find VM %s: %w", vmRef, err)
+	}
+	dcr, ok := hyper.(hypervisor.Direct)
+	if !ok {
+		return fmt.Errorf("backend %s does not support direct restore", hyper.Type())
+	}
+	vm, err := hyper.Inspect(ctx, vmRef)
+	if err != nil {
+		return fmt.Errorf("inspect VM: %w", err)
+	}
+	if _, owned := vm.SnapshotIDs[cfg.ID]; !owned {
+		force, _ := cmd.Flags().GetBool("force")
+		if !force {
+			return fmt.Errorf("snapshot envelope id %s does not belong to VM %s; pass --force to override", cfg.ID, vmRef)
+		}
+		logger.Warnf(ctx, "snapshot envelope id %s does not belong to VM %s; --force in effect", cfg.ID, vmRef)
+	}
+	if cfg.NICs != len(vm.NetworkConfigs) {
+		return fmt.Errorf("NIC count mismatch: vm has %d, snapshot has %d",
+			len(vm.NetworkConfigs), cfg.NICs)
+	}
+	vmCfg, err := cmdcore.RestoreVMConfigFromFlags(cmd, vm, cfg)
+	if err != nil {
+		return err
+	}
+	return h.runDirectRestore(ctx, cmd, dcr, vmRef, vmCfg, dir,
+		fmt.Sprintf("dir %s", dir), logger)
+}
+
 func (h Handler) cloneDirect(ctx context.Context, cmd *cobra.Command, conf *config.Config, dcr hypervisor.Direct, da snapshot.Direct, snapRef string, logger *log.Fields) error {
 	dataDir, cfg, err := da.DataDir(ctx, snapRef)
 	if err != nil {
 		return fmt.Errorf("open snapshot %s: %w", snapRef, err)
 	}
+	return h.cloneFromSrcDir(ctx, cmd, conf, dcr, cfg, dataDir,
+		fmt.Sprintf("snapshot %s (direct)", snapRef), logger)
+}
+
+// cloneFromDir runs DirectClone over an envelope-bearing dir. The dir stays
+// read-only across the call so concurrent clones of a golden image are safe.
+func (h Handler) cloneFromDir(ctx context.Context, cmd *cobra.Command, conf *config.Config, dir string, logger *log.Fields) error {
+	cfg, err := snapshot.ReadSnapshotEnvelope(dir)
+	if err != nil {
+		return fmt.Errorf("load envelope: %w", err)
+	}
+	// Local copy so flipping the backend selection doesn't leak to the caller's
+	// shared *config.Config (CLI is fine, daemons embedding cocoon would notice).
+	localConf := *conf
+	if cfg.Hypervisor != "" {
+		localConf.UseFirecracker = cfg.Hypervisor == string(config.HypervisorFirecracker)
+	}
+	hyper, err := cmdcore.InitHypervisor(&localConf)
+	if err != nil {
+		return err
+	}
+	dcr, ok := hyper.(hypervisor.Direct)
+	if !ok {
+		return fmt.Errorf("backend %s does not support direct clone", hyper.Type())
+	}
+	return h.cloneFromSrcDir(ctx, cmd, &localConf, dcr, cfg, dir,
+		fmt.Sprintf("dir %s", dir), logger)
+}
 
+func (h Handler) cloneFromSrcDir(ctx context.Context, cmd *cobra.Command, conf *config.Config, dcr hypervisor.Direct, cfg types.SnapshotConfig, srcDir, sourceLabel string, logger *log.Fields) error {
 	vmCfg, vmID, netProvider, networkConfigs, err := h.prepareClone(ctx, cmd, conf, cfg)
 	if err != nil {
 		return err
 	}
 
 	wantJSON := cmdcore.WantJSON(cmd)
 	if !wantJSON {
-		logger.Infof(ctx, "cloning VM from snapshot %s (direct) ...", snapRef)
+		logger.Infof(ctx, "cloning VM from %s ...", sourceLabel)
 	}
 
-	vm, cloneErr := dcr.DirectClone(ctx, vmID, vmCfg, networkConfigs, cfg, dataDir)
+	vm, cloneErr := dcr.DirectClone(ctx, vmID, vmCfg, networkConfigs, &cfg, srcDir)
 	if cloneErr != nil {
 		rollbackNetwork(ctx, netProvider, vmID)
 		return fmt.Errorf("clone VM: %w", cloneErr)
@@ -239,7 +319,26 @@ func (h Handler) cloneDirect(ctx context.Context, cmd *cobra.Command, conf *conf
 	return nil
 }
 
-func (h Handler) prepareClone(ctx context.Context, cmd *cobra.Command, conf *config.Config, cfg *types.SnapshotConfig) (*types.VMConfig, string, network.Network, []*types.NetworkConfig, error) {
+// snapshotSource resolves the snapshot source for clone/restore: either a
+// directory via --from-dir or a positional SNAPSHOT ref. baseArgs is the
+// number of leading positional args before SNAPSHOT (0 for clone, 1 for
+// restore where args[0] is VM). Returns (fromDir, snapRef, err) with exactly
+// one of fromDir/snapRef non-empty on success.
+func snapshotSource(cmd *cobra.Command, args []string, baseArgs int) (string, string, error) {
+	fromDir, _ := cmd.Flags().GetString("from-dir")
+	if fromDir != "" {
+		if len(args) > baseArgs {
+			return "", "", fmt.Errorf("--from-dir and positional SNAPSHOT are mutually exclusive")
+		}
+		return fromDir, "", nil
+	}
+	if len(args) <= baseArgs {
+		return "", "", fmt.Errorf("SNAPSHOT is required (or use --from-dir)")
+	}
+	return "", args[baseArgs], nil
+}
+
+func (h Handler) prepareClone(ctx context.Context, cmd *cobra.Command, conf *config.Config, cfg types.SnapshotConfig) (*types.VMConfig, string, network.Network, []*types.NetworkConfig, error) {
 	vmCfg, err := cmdcore.CloneVMConfigFromFlags(cmd, cfg)
 	if err != nil {
 		return nil, "", nil, nil, err
@@ -290,26 +389,30 @@ func (h Handler) restoreDirect(ctx context.Context, cmd *cobra.Command, snapRef,
 	if !ok {
 		return false, nil
 	}
-
 	dataDir, _, err := da.DataDir(ctx, snapRef)
 	if err != nil {
 		return true, fmt.Errorf("open snapshot: %w", err)
 	}
+	return true, h.runDirectRestore(ctx, cmd, dcr, vmRef, vmCfg, dataDir,
+		fmt.Sprintf("snapshot %s", snapRef), logger)
+}
 
+// runDirectRestore is the shared tail for the snapshot-DB and --from-dir
+// restore paths: log, DirectRestore, output.
+func (h Handler) runDirectRestore(ctx context.Context, cmd *cobra.Command, dcr hypervisor.Direct, vmRef string, vmCfg *types.VMConfig, srcDir, sourceLabel string, logger *log.Fields) error {
 	wantJSON := cmdcore.WantJSON(cmd)
 	if !wantJSON {
-		logger.Infof(ctx, "restoring VM %s from snapshot %s (direct) ...", vmRef, snapRef)
+		logger.Infof(ctx, "restoring VM %s from %s (direct) ...", vmRef, sourceLabel)
 	}
-	result, err := dcr.DirectRestore(ctx, vmRef, vmCfg, dataDir)
+	result, err := dcr.DirectRestore(ctx, vmRef, vmCfg, srcDir)
 	if err != nil {
-		return true, fmt.Errorf("restore: %w", err)
+		return fmt.Errorf("restore: %w", err)
 	}
-
 	if wantJSON {
-		return true, cmdcore.OutputJSON(result)
+		return cmdcore.OutputJSON(result)
 	}
 	logger.Infof(ctx, "VM %s restored (state: %s)", result.ID, result.State)
-	return true, nil
+	return nil
 }
 
 func (h Handler) createVM(cmd *cobra.Command, image string) (context.Context, *types.VM, hypervisor.Hypervisor, error) {
@@ -529,7 +632,7 @@ func printOCINetworkHints(vm *types.VM, networkConfigs []*types.NetworkConfig) {
 	fmt.Println("  systemctl restart systemd-networkd")
 }
 
-func validateFCCloneOverrides(cmd *cobra.Command, cfg *types.SnapshotConfig) error {
+func validateFCCloneOverrides(cmd *cobra.Command, cfg types.SnapshotConfig) error {
 	if cpuFlag, _ := cmd.Flags().GetInt("cpu"); cpuFlag > 0 && cpuFlag != cfg.CPU {
 		return fmt.Errorf("--cpu %d not supported: Firecracker cannot change CPU after snapshot/load (snapshot has %d)", cpuFlag, cfg.CPU)
 	}