On this page
#Cluster backup and restore
kalisto export / kalisto import are Lima-only cold disk archives on macOS native VZ, not hot snapshots, process migration or sanitized public templates. Installed workloads and VM-local data already survive ordinary down / up. Archives transfer that state with identities, credentials, disks and boot assets. Apple-container/Firecracker archive support and backend conversion are not provided. Native restore evidence remains pending.
#Export and consistency
kalisto export --name dev --output /secure/dev.kalisto
# Alternative: authorize clean OS shutdown first if nodes are running.
kalisto export --name dev --output /secure/dev.kalisto --stop
Without --stop, every node must already be stopped. Export never force-stops a VM, never deletes source data and leaves the source stopped. Quiesce applications externally for application-consistent backups: stopped disks alone do not guarantee consistency, especially after a previous forced shutdown.
Included:
- Every node's main VM disk and optional VZ EFI variable store.
- Kubernetes datastore resources, Helm releases, CRDs, images/cache and persistent data inside those disks.
- Selected private runtime files: kubeconfigs, node tokens and per-cluster Cilium TLS manifests.
- Matching boot-asset profile and the sanitized base image itself.
Not included: RAM, live processes, connections, external databases/cloud services. Custom provisioning, additional VM disks, external host mounts and unknown host-runtime files are refused rather than silently omitted. Back up external data separately. PIDs/logs are deliberately excluded.
#Native age encryption
Kalisto embeds age 0.11.5, wrapping the gzip archive in standard binary age format. No GPG, age executable, plugins or host crypto tools are required. Native X25519 age keys are supported; SSH/GPG/plugin keys, armored files and encrypted identity-file wrappers are not supported in this version.
kalisto archive-keygen --output /secure/dev.agekey
# Replace age1... with the public recipient printed by keygen.
kalisto export --name dev --output /secure/dev.kalisto.age --recipient age1... --stop
# On a compatible target without a same-name cluster or Lima instances:
kalisto import /secure/dev.kalisto.age --identity /secure/dev.agekey
kalisto up --name dev
archive-keygen atomically creates a mode-0600 private key without overwriting and prints only the public recipient. Repeat --recipient for multiple recovery keys; any one can decrypt. Repeat --identity for multiple key files. Keep recovery keys separate from archives: lost keys mean lost access.
#Passphrases and automation
kalisto export --name dev --output /secure/dev.kalisto.age --passphrase --stop
kalisto import /secure/dev.kalisto.age --passphrase
Terminal prompts do not echo; export asks for confirmation. Export requires at least 16 characters, but length alone does not imply strength; prefer randomly generated words. Native passphrase exports use scrypt with 256 MiB memory cost; imports cap accepted cost at roughly 1 GiB. Recipient keys avoid this KDF.
Noninteractive operations use --passphrase-file /private/path instead. Secret input files must be private regular files (0600/0400), UTF-8 and at most 64 KiB. A passphrase file contains one nonempty line, optionally newline-terminated. Recipients/identities and passphrases are mutually exclusive. Raw passphrases/private keys are never CLI argument values. Secret buffers are zeroized on drop; do not put secrets in filenames.
No encryption flags means an unencrypted, secret-bearing archive. A .age output suffix without encryption is refused. Import detects encryption by header, not suffix; supplying credentials or a .age input suffix rejects plaintext to prevent downgrade. Decryption/authentication failure has no fallback.
Tar/gzip streams directly into age without a plaintext archive intermediate. Export reads stored ciphertext back with SHA-256 before atomic publication, without retaining an extra recovery key or adding an undeclared recipient. Import authenticates the complete age stream, gzip CRC and payload inventory before publishing resources. Decrypted disks still stage privately on the target; archive encryption does not encrypt live VM storage. Secure staging, swap and runtime storage separately.
#Import compatibility and publication
kalisto import /secure/dev.kalisto
# Alternative import with a target API port change:
kalisto import /secure/dev.kalisto --api-port 16444
# After one successful import, explicitly boot:
kalisto up --name dev
The import commands are alternatives, not sequential steps. Import preserves original cluster/node identities; renaming is unsupported. The target requires compatible CPU architecture and the pinned Lima version on macOS native VZ. Import refuses existing cluster directories, Lima instances and archive output paths; it never deletes an existing source cluster to make room.
Use another compatible Mac, or remove the original only through explicitly authorized cleanup after a safe backup. Consider duplicated identities before running original/restored copies against shared external services.
Import checks payload checksums before publishing definitions, restores sparse disk regions without allocating empty logical space, rebuilds host paths/narrow mounts and regenerates host-local VZ identifiers. Archived host configuration, provisioning scripts, SSH private keys, sockets and cloud-init media are not executed/restored. Lima regenerates host integration at the next boot. up refreshes the host kubeconfig endpoint and waits for current guest boot identities, not stale Node Ready conditions from the snapshot.
Import leaves nodes stopped. Boot assets are bundled, but verified managed host tools may download on an unprepared target. The default uncompressed payload limit is 1 TiB, adjustable with --max-bytes. Export/import time is outside the prepared-boot benchmark; restored startup has no separate sub-minute guarantee.
#Secrets, integrity and interruptions
Archives contain cluster credentials, Kubernetes Secrets and application data. Encrypt before transport, keep recovery keys separate and never commit real archives/keys. New keys/archives are 0600; staging/destination roots are 0700. *.kalisto, *.kalisto.age, *.agekey are gitignored, but other output names still require care.
Only import trusted archives. Import does not start guest code, but subsequent up executes the archived OS. SHA-256 and gzip CRC detect corruption, not a malicious author able to replace both payloads and checksums. Age adds authenticated encryption, not a sender signature: anyone with a public recipient can create a new encrypted archive. Plaintext export also verifies tar/gzip during stored-byte readback.
Tar paths/types, duplicates, file counts, sizes and the full inventory are validated. Links, device files and extension headers are rejected; no existing file is overwritten. Per-cluster locks exclude normal lifecycle mutations. Do not manipulate these VMs through Lima or deploy concurrently during the transaction.
Normal import failure cleans only destinations that import created. Hard-killed/interrupted imports can leave a private incomplete-import marker and owned partial directories; the marker blocks automatic creation/overwrite. Inspect resources before cleanup; never blindly delete unrelated data or locks.
#MCP transaction contract
clusters.export:name,output,stop, optionalrecipientsorpassphraseFile.clusters.import:input,apiPort,maxBytes, optionalidentityFilesorpassphraseFile.
Paths are local to the MCP host, not the client. Never send inline secret keys/passphrases. Unsupported fields/malformed recipients are rejected before task JSON/manifests persist. MCP never prompts on a terminal. Both tools use the CLI core and require task-augmented calls. Archive tasks are not cancellable while copying/publishing; poll to a terminal result rather than killing a restore transaction. No encryption flags still means plaintext. These calls grant no implicit permission to stop a running cluster or remove the original to make room. See task completion and ownership.
#Validation limits and authorized live test
Host-safe tests cover format round trips; corrupt/truncated inputs; links, traversal, duplicates, limits/collisions; fake-disk credential/data preservation and locks. Encryption coverage includes standard-age interoperability, multiple recipients, randomized ciphertext, wrong secrets, tampering, truncation/trailing data, private key generation, secret-file limits, plaintext downgrade refusal, and no publication after authentication failure. CLI/MCP argument coverage excludes inline secrets. These are not a security audit or native VM restore proof. Current CI builds candidates and validates native boot budgets; native archive round-trip success is not claimed.
The native archive test is opt-in, for an explicitly authorized macOS CI runner with kubectl and disposable named VMs:
KALISTO_LIVE_CLUSTER_ARCHIVE_TESTS=1 \
KALISTO_ARCHIVE_TEST_ROOT=/absolute/path/to/owned-ci-storage \
cargo test --release --test macos_cluster_archive_live -- --nocapture
It checks Kubernetes objects and worker-local data after encrypted export/destroy/import/boot. Sensitive archives and generated recovery keys are deleted, never published as CI artifacts. Development-Mac test storage/caches must use the configured mounted external build volume. Respect the user's execution policy; do not run live validation without explicit authorization. Native restore evidence remains pending.