Installation

This page covers installing Aether in all supported configurations: AetherLite (single binary), full gateway (Docker or source), and the client SDKs.

Prerequisites

• Go 1.25+ — required to build from source or install the Go SDK
• Docker — optional, needed for the full stack (Redis, RabbitMQ, PostgreSQL)
• Python 3.11+ — optional, for the Python SDK
• Node.js 18+ — optional, for the TypeScript SDK

Verify Go:

go version
# go version go1.25.x linux/amd64

---

AetherLite (Single Binary, No External Services)

AetherLite is the fastest way to get Aether running. It requires only Go — no Redis, RabbitMQ, or PostgreSQL.

Build from Source

# Clone the repository
git clone https://github.com/scitrera/aether.git
cd aether/server

# Build the AetherLite binary
go build -o aetherlite ./cmd/aetherlite

# Start in development mode
# --insecure-admin requires AETHER_ALLOW_DEV_MODE=true
AETHER_ALLOW_DEV_MODE=true ./aetherlite --dev --insecure-admin

Verify Installation

# Check the binary is working
./aetherlite --version

# In another terminal, verify gRPC is listening
grpcurl -plaintext localhost:50051 list

The admin UI is available at http://localhost:31880.

See AetherLite for full configuration options.

---

Full Gateway (Docker)

The Docker image contains the gateway, migrate, cleanup, auth-proxy, and init-secrets binaries.

Pull or Build the Image

# Build from repository root
git clone https://github.com/scitrera/aether.git
cd aether
docker build -f server/Dockerfile -t scitrera/aether-gateway:latest .

Start External Services

# Redis (Valkey)
docker run -d --name aether-redis -p 6379:6379 valkey/valkey

# RabbitMQ with Streams plugin
docker run -d --name aether-rabbitmq \
  -p 5552:5552 -p 5672:5672 -p 15672:15672 \
  -e RABBITMQ_DEFAULT_USER=guest -e RABBITMQ_DEFAULT_PASS=guest \
  ghcr.io/scitrera/rabbitmq-stream:4-management

# PostgreSQL (optional — task/ACL/audit features)
docker run -d --name aether-postgres -p 5432:5432 \
  -e POSTGRES_DB=aether -e POSTGRES_USER=aether -e POSTGRES_PASSWORD=aether_dev \
  postgres:15-alpine

Run the Gateway

docker run -d --name aether-gateway \
  -p 50051:50051 -p 9090:9090 -p 31880:31880 \
  -e AETHER_ALLOW_DEV_MODE=true \
  -e REDIS_ADDR="host.docker.internal:6379" \
  -e STREAM_URL="rabbitmq-stream://guest:guest@host.docker.internal:5552" \
  -e AMQP_URL="amqp://guest:guest@host.docker.internal:5672/" \
  scitrera/aether-gateway:latest \
  --dev --insecure-admin

See the server repository’s deployment documentation for production configuration with config files, TLS, and Kubernetes.

---

Client SDKs

Go SDK

go get github.com/scitrera/aether/sdk/go

Minimum requirements: Go 1.25+, gRPC 1.78.0+

Quick usage:

import "github.com/scitrera/aether/sdk/go/aether"

client, err := aether.NewAgentClient(aether.AgentOptions{
    ClientOptions: aether.ClientOptions{
        ServerAddr: "localhost:50051",
    },
    Workspace:      "default",
    Implementation: "my-agent",
    Specifier:      "instance-1",
})

See Go SDK for the complete API reference.

Python SDK

pip install scitrera-aether-client

Minimum requirements: Python 3.11+, grpcio >= 1.76.0

Quick usage:

from scitrera_aether_client import AgentClient

client = AgentClient(
    workspace="default",
    implementation="my-agent",
    specifier="instance-1"
)
client.connect("localhost:50051")

See Python SDK for the complete API reference.

TypeScript SDK

npm install @scitrera/aether-client

Minimum requirements: Node.js 18+

Quick usage:

import { AgentClient } from "@scitrera/aether-client";

const agent = new AgentClient({
  address: "localhost:50051",
  workspace: "default",
  implementation: "my-agent",
  specifier: "instance-1",
});
await agent.connect();

See TypeScript SDK for the complete API reference.

---

Verify Your Installation

After installing a gateway (AetherLite or full) and an SDK, connect a minimal agent:

package main

import (
    "context"
    "fmt"
    "github.com/scitrera/aether/sdk/go/aether"
)

func main() {
    client, err := aether.NewAgentClient(aether.AgentOptions{
        ClientOptions: aether.ClientOptions{ServerAddr: "localhost:50051"},
        Workspace:      "test",
        Implementation: "verify",
        Specifier:      "001",
    })
    if err != nil {
        panic(err)
    }
    client.OnConnect(func(ctx context.Context, ack *aether.ConnectionAck) error {
        fmt.Printf("Connected with session %s\n", ack.SessionID)
        return nil
    })
    ctx := context.Background()
    if err := client.Connect(ctx); err != nil {
        panic(err)
    }
    fmt.Println("Installation verified.")
    client.Close()
}

You should see Connected with session <id> and Installation verified. — confirming the gateway and SDK are working.

Next Steps

• Follow the Quick Start to send your first message between two agents
• Read Architecture to understand how Aether works