Aether CLI

Keep your tools. Host the workspace.

Aether CLI 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 your service 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 CLI 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 CLI First

The migration path has to work on day one.

Aether CLI 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 CLI 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 workflow 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 services, agents, and humans

A backend 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 CLI.

How It Fits

Aether CLI is the bridge, not the control plane.

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

Aether CLI 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 CLI 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 app or wrapper.
Use Aether CLI for local file access and the hosted APIs for workflow control.

Adoption Sequence

Adopt it in the right order.

Start API-first, then add mounts where they help. That keeps the hosted story clear while still giving teams a low-friction bridge for workflows that 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 CLI where the toolchain still needs it

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

Keep session identity and policy in the hosted service even when work moves local
Keep builds, tests, and editor-driven tasks on smaller compute boxes
Let humans inspect or patch the exact hosted session the service 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.

The best handoff starts with the service creating the session over API, giving the user one clear launch path, and keeps checkpoints, approvals, and commits in the hosted flow. Aether CLI just opens that exact workspace locally.

Create the session over API

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

Hand off one concrete workspace

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

Mount it locally with Aether CLI

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

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 service: one endpoint, one session, and one obvious command.

Mount the handed-off session

export AFS_AETHER_SERVER_ENDPOINT='https://grpc.aetherfs.io'
aether mount --session-id <session-id> --mount-dir ./workdir

Set endpoint once

[bridge]
server_endpoint = "https://grpc.aetherfs.io"
worker_id = "alice-laptop"

Debug the local runtime

aether doctor
aether status --session-id <session-id>
aether metrics show

Use the docs for commands. Use the workflow to decide where Aether CLI fits.

Docs Platform