CLI Storage

Podplane stores several kinds of files on your computer when it runs, for example to:

• download and cache dependencies such as local VM OS images and VM component packages
• store login metadata while keeping tokens in the OS-native secret store
• track runtime metadata such as VM process IDs

Podplane uses the same storage categories on macOS, Linux, and Windows:

• config: long-term config and auth metadata; meaningful to back up.
• cache: downloaded or derived files; safe to delete and recreated on demand.
• data: durable local VM/local-cluster files; deleting them deletes local clusters.
• runtime: ephemeral process metadata; recreated by restarting Podplane processes.

These categories are based on the XDG Base Directory Specification, a convention for separating different kinds of user-owned application files. You do not need to know XDG to use Podplane; the important idea is that each file is grouped by how safe it is to delete and how important it is to preserve.

Cluster and OIDC server configuration files such as podplane.cluster.jsonc and podplane.oidc.jsonc are not covered here. See the Config Files & Context section in the CLI Overview for more information about those files.

Base Directories

Podplane uses the following default base directories for CLI-owned files:

The XDG_* environment variables can be used on any operating system to move Podplane’s base directories away from the defaults. On macOS and Windows, Podplane defaults to keeping CLI-owned files together under a single .podplane directory, separated into category subdirectories.

Category Definitions

• Config

  • User- or tool-authored settings/configuration needed to determine behavior.
  • Persistent across reboots and not regenerated automatically.
  • Small and meaningful to back up.

• Cache

  • Reconstructable, downloadable, or derived files.
  • Does not contain authoritative user data or durable local-cluster state.
  • Safe to delete at any time, though deletion may cause redownloads or recomputation.

• Data

  • Durable application data, especially local VM and local-cluster resources.
  • Deleting it loses local cluster contents or local service data, not merely cached downloads.
  • Partial deletion may corrupt or break local cluster behavior.
  • Persistent across reboots and meaningful to back up if the user cares about local environments; otherwise generally safe to delete.

• Runtime

  • Ephemeral process/session coordination files.
  • Only valid while processes or sessions are running.
  • Deleting it while Podplane, QEMU, or the local server is running may break process coordination.
  • Stopping/restarting processes or rebooting the machine should recover from runtime file problems.
  • Safe to delete when the Podplane CLI is not running.

File Contents & Category Mapping

Config Files

• Auth metadata file: stores durable metadata needed to resolve auth state, but not token secrets. It influences CLI/kubectl auth behavior and is small, structured, persistent configuration.
• File-backed keyring fallback file/store: used only when file-backed keyring is enabled. It is encrypted and contains persistent auth secret material, so it is not cache, data, or runtime. Keep it with auth-related config.

Cache Files

• Dependencies cache: dependency files are grouped by dependency domain under the dependencies cache root. VMConfig manifests and artifacts live under vmconfig/, component image metadata and blobs for the local zot storage live under components/, and template manifests and cached chart OCI data live under templates/.
• VMConfig dependency manifests: metadata about all vmconfig dependencies relevant to the specified architecture and desired OS kind/version, stored under vmconfig/manifests/. Safe to delete; the Podplane CLI can fetch it again.
• Downloaded VMConfig dependency artifacts: downloadable and checksum-verifiable artifacts stored under vmconfig/artifacts/<artifact-name>/<version>/<file>. Includes VM base images, tar.gz archives, and deb packages. Safe to delete, though deletion will require a potentially slow re-download before local clusters can start.
• Component container image cache: component manifests are cached under components/manifests/, and mirrored container image data for the local zot registry is stored under components/images/. Safe to delete; it can be recreated by downloading dependencies again.
• Template chart cache: template manifests are cached under templates/manifests/, and Helm chart data is stored under templates/charts/. Safe to delete; it can be recreated by downloading dependencies again.
• Cached CA certs derived from inline PEM or URL specs: reconstructable from the original inline PEM or URL input. Safe to delete; the Podplane CLI can resolve/cache them again.

Data Files

• Local generated cluster config stash: part of the durable local cluster environment. It lets later Podplane CLI commands and the kubectl auth hook understand the local cluster. Not user config, cache, or runtime.
• Rendered cloud-init user-data: part of the durable local cluster environment served to the VM. It is generated, but it belongs with local VM/cluster data rather than a separate state area.
• Local fake OIDC signing key: part of the durable local cluster environment. Deleting it changes local issuer signing identity and can invalidate local auth assumptions/tokens. Not cache or runtime.
• QEMU VM disk images: durable local cluster data. Deleting them destroys the local VM contents.
• Fake S3 object storage: durable local service/application data visible to the local cluster. Deleting it loses local object-storage state such as the default <cluster-id>-netsy and <cluster-id>-telemetry buckets. The special registry bucket is backed by the component image cache instead, so it can be recreated by downloading dependencies again.

Runtime Files

• Local server PID file: process coordination only. Valid only while the server process exists. Safe to delete when not running.
• QEMU VM PID files: process coordination only. Valid only while the VM process exists. Safe to delete when not running.
• Local server address/port runtime metadata: describes a currently running process endpoint. Belongs with the local server PID/runtime record.