Skip to main content

Mounts

Mounting is the core Aether CLI workflow.

A mount lets local tools interact with a remote session through a local filesystem path.

What a mount gives you​

A mount is useful when you want:

  • A local editor experience.
  • Shell tools operating on paths.
  • Existing programs to read or write session content as files.
  • A familiar workspace model for users who do not want to work through raw APIs.

Basic pattern​

The standard workflow is:

  1. Choose or create a session.
  2. Pick a local mount directory.
  3. Run aether mount against that session.
  4. Work on the mounted tree.
  5. Inspect status, logs, or metrics as needed.
  6. Stop or unmount when finished.

Mount design guidance​

Use a dedicated directory​

Use a clean mount point instead of mounting into a directory that already contains important local files.

Treat the mount as session-scoped​

A mount reflects a specific session. If your workflow changes sessions, remount explicitly rather than assuming a mount is generic.

Keep cache decisions explicit​

If the machine is long-lived or shared, set cache directories intentionally so you know where client-side state is stored.

Tune TTLs for your workflow​

If you need faster visibility of remote changes, reduce lookup and directory TTL values. If you want fewer round trips, increase them cautiously.

Relevant config for mounted workflows​

  • Endpoint: AFS_AETHER_SERVER_ENDPOINT / [bridge].server_endpoint
  • Cache root: AFS_AETHER_CACHE_DIR / cache_dir
  • Shared cache root: AFS_AETHER_CACHE_SHARED_ROOT / shared_cache_root
  • Lookup TTL: AFS_AETHER_LOOKUP_TTL_SECS / lookup_ttl_secs
  • Negative lookup TTL: AFS_AETHER_NEGATIVE_LOOKUP_TTL_SECS / negative_lookup_ttl_secs
  • Directory TTL: AFS_AETHER_DIR_CACHE_TTL_SECS / dir_cache_ttl_secs

Operational commands to keep nearby​

aether mount --help
aether status --session-id '<session-id>'
aether doctor
aether logs tail
aether stop --session-id '<session-id>'

Read-only versus mutable use​

Whether a mounted workflow should be treated as mutable depends on your session policy and application flow.

Good practice:

  • Use distinct sessions for distinct tasks.
  • Use checkpoints before high-risk edits.
  • Prefer forks when multiple actors may diverge.
  • Use review and approval workflows before durable persistence.