Skip to main content

afs-server

afs-server is the hosted service that powers AetherFS.

If you use the Aether CLI, the HTTP API, or the public gRPC surface, you are already using afs-server even if you never interact with it directly.

From a user perspective, the important facts are:

  • It creates and manages remote sessions.
  • It exposes the public API contract documented on this site.
  • It enforces access, tenancy, and workflow boundaries.

What it does for you​

afs-server is the thing that makes these user-visible workflows work:

  • Creating and tracking sessions.
  • Serving filesystem reads, writes, metadata, and mutation workflows.
  • Handling checkpoints, persistence, and managed-source flows where the public contract supports them.
  • Returning health, analytics, usage, and approval state.
  • Acting as the remote endpoint that Aether CLI connects to from your machine.

You do not need to know its internal architecture to use those features well, but it helps to know that your CLI or integration is always talking to a hosted session service, not just a local tool.

When users actually need to care about it​

Most users only need to think about afs-server in a few cases:

  • You need the right endpoint or environment.
  • You need to authenticate a client or integration.
  • You need to understand where a remote session lives.
  • You are troubleshooting connectivity, permissions, or unexpected session behavior.

Outside of that, you usually work through a higher-level surface such as Aether CLI or the HTTP API.

What you configure​

As a user, the things you usually care about are:

  • Which endpoint you connect to.
  • Which tokens, credentials, or client config you use.
  • Which public workflow fits your task.

Common questions​

Which address should my client connect to?​

Use the endpoint your environment or deployment gives you.

For Aether CLI, that usually means AFS_AETHER_SERVER_ENDPOINT or [bridge].server_endpoint.

For API clients, that means the base URL for the public /v1/... contract.

Start here:

How do I choose between Aether CLI, HTTP, and gRPC?​

Use the surface that matches the job:

  • Use Aether CLI when you want a local mounted filesystem view on your machine.
  • Use HTTP when you want browser-friendly or JSON-first integration.
  • Use gRPC when you want typed clients, streaming flows, or service-to-service integration.

You are still talking to the same remote session service either way.

Where does the actual session live?​

The session lives on afs-server.

Aether CLI can cache and expose that session locally, but the remote session, its metadata, and its public workflow state are managed by the service.

That distinction matters when you are debugging:

  • local mount/runtime issues
  • remote auth or permission failures
  • session state that does not match what you expected

What should I know before opening a support request?​

Usually just:

  • Which environment or endpoint you were using.
  • Which session or source you were working with.
  • Which public surface you were using: Aether CLI, HTTP, or gRPC.
  • Which command, route, or RPC failed.
  • Any relevant local logs or request IDs.

Where to go next​