Features and capabilities
This page maps the main public capabilities of AetherFS to the workflows they support.
If you want the lifecycle view first, read Session lifecycle. This page is about what the system can do once you choose a surface and a workflow shape.
Session and workspace control
AetherFS is built around sessions as the primary unit of work.
Public capabilities include:
- Creating a session from a source or a blank starting point.
- Inspecting session metadata, labels, tags, and current state.
- Listing sessions for dashboards, reviewers, or automation.
- Forking a session for parallel work or alternative proposals.
- Checkpointing and restoring a session.
- Committing, archiving, or deleting a session when the work reaches a boundary.
This is the core control surface for task creation, handoff, branching, recovery, and cleanup.
Filesystem and content operations
The public surface supports ordinary file-oriented work as well as more specialized content flows.
Common capabilities include:
- Browsing trees and subtrees through manifests.
- Reading file content and metadata.
- Creating, renaming, linking, and deleting paths.
- Creating and managing directories and symlinks.
- Patching or replacing file content.
- Doing batch changes when one user action maps to several path mutations.
- Inspecting content hashes or CAS extents when a client needs verification, sparse updates, or byte reuse planning.
Most clients should start with manifests, reads, and ordinary mutation routes. Hash- and extent-oriented flows are for more advanced sync, sparse-write, or binary-heavy clients.
Review, approval, and shared workflow state
AetherFS is not just a remote tree of files. It also exposes workflow state that should not be hidden inside the filesystem.
Public capabilities include:
- Annotations for review notes and path-level discussion.
- Approval requests and approval decisions.
- Collaboration and lock-style coordination routes where the workflow needs them.
- Session-scoped bus messages for live progress or event-style coordination.
- Knowledge or cache entries for structured workflow state that needs to be retrieved later.
These capabilities matter when more than one person, tool, or agent is involved in the same unit of work.
Persistence and reusable starting points
The system separates temporary live work from durable outcomes.
Public capabilities include:
- Checkpoints for recoverable milestones.
- Commits for durable session outcomes.
- Exports for moving content out through supported public flows.
- Imports and synchronization flows where the public contract exposes them.
- Promotion of a good session result into a reusable source.
Use these capabilities to decide what should stay temporary, what should become durable, and what should become the next starting point for future work.
Observability and operational signals
AetherFS also exposes non-file signals that clients and support flows can rely on.
Public capabilities include:
- Session health and health reports.
- Usage and analytics views where the public contract exposes them.
- Workflow or activity signals that help with debugging, reporting, and support.
- CAS and service-level metrics where the public API makes them available.
These signals belong in operational views, reviewer tools, support tooling, and internal service dashboards, not inside ordinary file trees.
Local access through Aether CLI
When a workflow still needs local filesystem semantics, Aether CLI provides the local bridge.
Capabilities include:
- Connecting a machine you control to a remote session.
- Mounting a remote session locally.
- Using editors, shells, builds, and tests against that mounted workspace.
- Controlling client-side cache, logging, and metrics.
- Running diagnostics and operational commands from the CLI.
This is the right surface when the workflow genuinely needs a local mounted tree. It should not replace the hosted API for ordinary control-plane actions.
Authentication, authorization, and secrets
The public surface also includes the security controls that make these workflows usable in real systems.
Relevant capabilities include:
- Authenticated access to the service.
- Authorization at the session, source, and workflow level.
- Dedicated secret routes for protected values.
- Separation between secret handling and ordinary file, annotation, or cache flows.
These capabilities matter because real workflows need to control who can start, inspect, mutate, approve, persist, and retrieve work.
Choosing the right surface
Most teams use more than one public surface, but they use them for different jobs.
- Use HTTP for straightforward control-plane integration, browser-friendly flows, and JSON-first clients.
- Use gRPC when you need generated clients, long-lived streams, large binary payloads, or streaming-heavy workflows.
- Use Aether CLI when users or workers need local filesystem semantics on a machine they control.
AetherFS works best when those roles stay explicit instead of trying to force one surface to behave like all of the others.