Skip to main content

AFS_AETHER_CACHE_DIR

Deep-dive reference for:

  • AFS_AETHER_CACHE_DIR

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: filesystem path (PathBuf).
  • Default:
    • $XDG_CACHE_HOME/aetherfs-aether when XDG_CACHE_HOME is set.
    • Otherwise $HOME/.cache/aetherfs-aether when HOME is set.
    • Otherwise $TMPDIR/aetherfs-aether (std::env::temp_dir() fallback).

What It Does​

Sets the base cache root for Aether local cache state.

For a given session ID, Aether materializes cache content under:

  • <cache>/<session>/content/

with these subdirectories:

  • blobs/
  • staging/
  • dirty/
  • index/
  • shared/
  • locks/

On Unix, startup ensures these directories exist with 0700 permissions before mount work proceeds.

Input Surfaces​

  • Env: AFS_AETHER_CACHE_DIR=/path/to/cache-root
  • Config file (aether.toml): cache_dir = "/path/to/cache-root"
  • CLI override: --cache-dir /path/to/cache-root (on commands that expose it, including mount/journal/cache flows)

Resolution and Override Order​

  • Defaults < aether.toml < environment < CLI overrides.
  • Default control socket path is derived from cache layout locks:
    • <cache>/<session>/content/locks/control.sock
  • If file logging is enabled and no explicit log path is set, log path defaults to:
    • <cache>/logs/aether.log
  • AFS_AETHER_CACHE_SHARED_ROOT is separate:
    • AFS_AETHER_CACHE_DIR controls per-session cache roots.
    • AFS_AETHER_CACHE_SHARED_ROOT controls the host-wide shared blob root and defaults to <cache_dir>/shared (set to off/none/disabled/false/0 to disable).

Path Handling Notes​

  • The value is taken as provided (no canonicalization/normalization in config load).
  • Relative paths are allowed and resolve relative to the process working directory.
  • Mount startup fails if required directories cannot be created or permissioned.

Example​

If:

  • AFS_AETHER_CACHE_DIR=/var/lib/aetherfs/cache
  • session_id=abc123

then Aether uses:

  • /var/lib/aetherfs/cache/abc123/content/blobs
  • /var/lib/aetherfs/cache/abc123/content/staging
  • /var/lib/aetherfs/cache/abc123/content/dirty
  • /var/lib/aetherfs/cache/abc123/content/index
  • /var/lib/aetherfs/cache/abc123/content/shared
  • /var/lib/aetherfs/cache/abc123/content/locks

Primary Implementation Sources​

  • packages/aether/src/config/types/model_defaults.rs
  • packages/aether/src/config/types/file_config_loader.rs
  • packages/aether/src/config/types/config_resolution.rs
  • packages/aether/src/config/types/apply_env.rs
  • packages/aether/src/cache/mod.rs
  • packages/aether-cli/src/app/dispatch_and_runtime.rs
  • packages/aether-cli/src/cli/args/cli_option_args.rs
  • packages/aether/src/core/control/control_client.rs