AetherFS Read the docs

Aether CLI

Keep the toolchain. Move the workspace.

Aether is the easiest way to adopt AetherFS without rewriting every tool. It mounts a hosted session as a normal local directory, so editors, shells, builds, and tests keep working while the workspace itself stays in the service.

That lets teams stop cloning full workspaces onto every worker box. Compute stays where it is still needed, storage and session state stay hosted, and the product keeps control of lifecycle over HTTP or gRPC.

Why teams start here

  • Keep IDEs, shells, builds, and tests working
  • Mount the hosted session instead of cloning another workspace
  • Let humans and agents open the same session
  • Use Aether as the low-friction bridge into AetherFS

Stay API-first for

  • Pure control-plane workflows over HTTP or gRPC
  • Session creation, approvals, checkpoints, and commits
  • Jobs that never need a mounted workspace
  • First pilots where local paths are not required

Why Teams Choose Aether First

The migration path is the product.

Aether matters because it gives customers a way into AetherFS that feels practical on day one. They can keep local tools, shrink the worker box, and still move the workspace itself into the hosted service.

No toolchain rewrite on day one

Aether is the easiest migration path into AetherFS. Mount the session and keep VS Code, JetBrains, shells, build systems, and other file-based tools working while the rest of the product stays API-driven.

Less duplicated workspace state

When builds and tests still need compute, keep the compute but stop cloning the full workspace onto every box. The session stays hosted and the machine only supplies execution and local tooling.

One session across product, agents, and humans

A product or agent can create the session over HTTP or gRPC, then a human reviewer or another worker can open that exact same session locally with Aether.

How It Fits

Aether is the bridge, not the control plane.

When a workflow still expects local paths, Aether gives it those paths without breaking the SaaS model. The product creates the session, decides policy, and manages approvals, checkpoints, and commits over HTTP or gRPC.

Aether simply projects that hosted session into a machine the user or worker already controls. That is why it works so well for mixed workflows and brownfield adoption.

  • Aether is the client on the machine, not the service customers deploy.
  • Mount one specific hosted session, not a generic shared drive.
  • Keep endpoint and auth pre-decided by the product or wrapper.
  • Use Aether for local file access and the hosted APIs for workflow control.

Adoption Sequence

Adopt it in the right order.

The cleanest rollout is API first, then selective mounts. That keeps the hosted story clear while giving teams a low-friction bridge for the workflows that still need local filesystem semantics.

Start with the hosted API

The first pilot should prove session creation, file mutation, and workflow control over the hosted service.

  • Products and agent backends create, inspect, and mutate sessions over HTTP or gRPC
  • Customers validate fast forks, shared storage economics, and workflow boundaries without client rollout friction
  • Review, approval, and persistence stay in the SaaS control plane from day one
  • If the workload never needs local paths, this may be all they need

Add Aether where the toolchain still needs it

Bring Aether in for the parts of the workflow that still expect a mounted tree on a user or worker machine.

  • Hand off a specific session to open locally instead of asking users to discover one
  • Keep builds, tests, and editor-driven tasks on smaller compute boxes
  • Let humans inspect or patch the exact hosted session the product already tracks
  • Move deeper into API-native workflows later, once the bridge path is already working

Mixed Workflow

The best experience feels like a handoff.

A good product creates the session over API, hands the user one clear launch path, and keeps checkpoints, approvals, and commits in the hosted flow. Aether just opens that exact workspace locally.

01

Create the session over API

Your product chooses the source, creates the session, and decides the policy boundary through HTTP or gRPC.

02

Hand off one concrete workspace

The user gets a specific session ID, launch action, or copy-pasteable command for the workspace they should open.

03

Mount it locally with Aether

Aether turns that hosted session into a normal directory for editors, shells, builds, and test tooling.

04

Finish back in the hosted flow

Approvals, checkpoints, commits, and cleanup still live in the SaaS workflow even when local editing was part of the job.

Practical Path

Give people one obvious mounted workflow.

The local command surface should feel like an extension of the hosted product: one endpoint, one session, and one obvious command.

Mount the handed-off session

export AFS_AETHER_SERVER_ENDPOINT='https://your-service.example.com'
aether mount --session <session-id> ./workdir

Set endpoint once

[bridge]
server_endpoint = "https://your-service.example.com"
worker_id = "alice-laptop"

Debug the local runtime

aether doctor
aether status
aether metrics show

Next

Use the docs for commands. Use the product model to decide whether Aether belongs in the flow.

Docs Platform