Skip to main content

Authentication and connectivity

Aether CLI needs two things before it can do useful work:

  • A reachable service endpoint.
  • Whatever authentication context your deployment expects.

Service endpoint​

The primary endpoint setting is:

  • Environment variable: AFS_AETHER_SERVER_ENDPOINT
  • Config key: [bridge].server_endpoint

Example with environment variables:

export AFS_AETHER_SERVER_ENDPOINT='https://grpc.aetherfs.io'

Example with config:

[bridge]
server_endpoint = "https://grpc.aetherfs.io"

If this is not set correctly, mount and runtime commands will fail to reach the remote service.

Worker identity​

Some deployments use a worker or client identity label.

Relevant setting:

  • Environment variable: AFS_AETHER_WORKER_ID
  • Config key: [bridge].worker_id

Example:

export AFS_AETHER_WORKER_ID='alice-laptop'

Auth model​

The exact credential source depends on how your environment is set up.

Common options include:

  • Environment variables.
  • Shell login context.
  • A local credential helper.
  • Service-issued tokens or identity federation.

The rule for Aether CLI users is simple: make sure the local environment you launch aether from has the credentials your deployment expects.

If your deployment uses the built-in CLI token path, the supported forms are:

  • AFS_AUTH_TOKEN='Bearer <tenant-uuid>:<principal>'
  • aether --auth-token-file ./token.txt ...
  • aether --auth-token-stdin ...

Connectivity guidance​

When connectivity fails, work through these questions in order:

  1. Is AFS_AETHER_SERVER_ENDPOINT or [bridge].server_endpoint set correctly?
  2. Can your machine reach that hostname and port?
  3. Are your local credentials present in the shell or environment that launches aether?
  4. Are you trying to inspect a running local runtime with aether status, or are you expecting it to validate connectivity before anything is running?

That last distinction matters: aether status is for the running local runtime, not a generic preflight reachability probe.

First commands to use​

aether doctor
aether mount --help
aether config --help

Use doctor first for local preflight checks such as FUSE availability, kernel support, and mount-directory sanity.

If the problem is endpoint reachability, remote auth, or session access, doctor is not enough. Move quickly to a real mount attempt with explicit endpoint/auth settings and readable logs.