Skip to main content

System overview

AetherFS is a session-based filesystem platform for running, reviewing, and persisting work in isolated workspaces.

It gives you three things at the same time:

  • A mutable working filesystem for a session.
  • A programmable control surface over HTTP and gRPC.
  • A local CLI, aether, for mounting and interacting with sessions from a machine you control.

What the system is for​

AetherFS is designed for workflows where you need to:

  • Start from an existing codebase, dataset, or template.
  • Create isolated workspaces quickly.
  • Inspect and modify files safely.
  • Coordinate work between tools, agents, and humans.
  • Review or approve changes before they are finalized.
  • Persist useful outcomes as checkpoints, commits, or exported artifacts.

Typical examples include:

  • Agent-assisted software development.
  • Review and approval workflows around generated changes.
  • Remote development environments that need a filesystem view.
  • Automation that needs repeatable, isolated workspaces.
  • Analysis or transformation pipelines that operate on file trees.

What users interact with​

Most users only need to understand three surfaces:

  • The system itself, which creates and manages sessions.
  • The HTTP API, which exposes the public contract for integrating with the service.
  • The Aether CLI, which connects a machine you control to remote sessions and exposes them as local mounts.

If you are integrating a product or service, start with the HTTP API.

If you want a local filesystem experience, start with Aether CLI.

Core product model​

The system revolves around sessions.

A session is an isolated working environment with:

  • A filesystem tree.
  • Metadata such as labels, tags, or annotations.
  • Optional collaboration state.
  • Optional persistence state such as checkpoints or commits.
  • Health, usage, and activity data.

Sessions can be created from scratch or from an existing source. Once created, they can be inspected, modified, reviewed, forked, checkpointed, committed, archived, or deleted.

Major capability areas​

Session management​

Create, inspect, list, fork, checkpoint, restore, tag, and delete workspaces.

Filesystem access​

Browse trees, read metadata, patch content, rename paths, manipulate directories, manage symlinks, and inspect extent/hash metadata where the public surface exposes it.

Collaboration​

Attach comments, annotations, approvals, knowledge entries, or bus messages to a session so work can be coordinated between people and tools.

Persistence​

Capture useful states as checkpoints and commits, and export or import session content where the public contract supports it.

Observability​

Retrieve health, usage, analytics, and other session-level signals for debugging, reporting, and operational awareness.

Local access through Aether CLI​

Mount a remote session on your machine, control cache and logging behavior, and use CLI workflows for inspection, troubleshooting, and automation.

If you are new to the product:

  1. Read Core concepts.
  2. Read Session lifecycle.
  3. Read Aether CLI quickstart if you want local mounts.
  4. Read API overview if you want to integrate over HTTP.

If you already know the product category:

  1. Read Features and capabilities.
  2. Read Common use cases.
  3. Jump to the CLI or API sections that match your workflow.