01
Create a session
Start from a repository, snapshot, template, dataset, or blank workspace. The session becomes the unit of work.
Workflows
Design the workflow, not just the storage layer.
AetherFS works best when the work has a real lifecycle: create a session, inspect it, make changes through the right surface, review the result, and either persist it or retire it.
Lifecycle stages
A typical session flow.
This is the common path: start from a source, inspect the state, mutate through the right surface, review the result, and then decide whether to persist or retire the session.
02
Inspect the state
Read metadata, fetch manifests, or mount locally with Aether CLI before any mutation begins.
03
Mutate through the right surface
Products can use HTTP or gRPC, and users can switch to Aether CLI when they need local filesystem semantics.
04
Review and coordinate
Annotations, approvals, bus messages, and knowledge entries let people and automation share context without hiding it in the filesystem.
05
Persist the outcome
Capture checkpoints for recovery, commit durable work, or export session content when the result should leave the workspace.
06
Fork, restore, or retire
Keep working, branch for alternatives, restore a checkpoint, or archive the session when it has done its job.
Workflow patterns
Defaults that keep the workflow understandable.
These patterns are usually enough to keep the workflow legible for both users and operators. They make ownership, rollback, and review easier to reason about.
One session per task
Use one session for one clearly bounded piece of work so ownership, review state, and cleanup stay obvious.
Baseline plus forked proposals
Keep the baseline stable and fork once per proposal when reviewers need to compare alternatives side by side.
Checkpoint before risk
Checkpoint before large automated edits, imports, or handoffs so rollback stays cheap and support stays simple.
Short-lived sessions, durable sources
Keep sessions temporary and let commits or promoted sources carry the durable meaning. That is usually the right default for a SaaS product.
Common use cases
Where this tends to fit.
The model shows up in code workflows, agent fleets, review-heavy systems, and other products where the file tree is the actual unit of work.
Agent-assisted software engineering
Feature work, bug fixes, modernization, security remediation, tests, and infrastructure changes all benefit from cheap forks and explicit review boundaries.
API-first agent fleets
Point agents at the hosted service over HTTP or gRPC, create sessions from a repo, mutate files, and persist only the results worth keeping.
Build-and-test agents with Aether CLI
When an agent still needs local filesystem semantics for builds or tests, mount the remote session locally instead of copying the whole workspace onto another larger VM.
Review-heavy approval flows
Fork one baseline into several proposals, attach evidence and annotations, request approval, and only then commit or promote the winner.
Data and analytics workspaces
Notebooks, SQL migrations, pipeline configs, and structured file trees benefit from the same session and coordination model as codebases.
Short-lived task sandboxes
Create a session, do the work, checkpoint or commit if useful, and retire the live workspace quickly instead of carrying idle boxes forever.