Installation

Active Development

Aether is under rapid, active development. Installation steps and configuration options may change between releases.

This guide covers how to install and run Aether locally or in production using Docker Compose.

Prerequisites

Tool	Minimum Version	Required For
Docker	24.0+	Running all services
Docker Compose	2.0+	Orchestrating services
Git	Any	Cloning the repository
Go	1.24+	Local backend development only
Node.js	22+	Local frontend development only

Quick Start with Docker Compose

1. Clone the Repository

bash

git clone https://github.com/amansrivastava/hacky-automation.git
cd hacky-automation

2. Configure Environment

bash

cp goway/.env.example goway/.env

Edit goway/.env with at minimum:

LLM_BASE_URL, LLM_API_KEY, LLM_MODEL — your LLM settings
Any issue tracker tokens you plan to use (GitHub, GitLab, Jira, Plane)

See the Configuration Guide for all available options.

3. Start All Services

bash

docker-compose up --build -d

This starts and connects:

PostgreSQL (with pgvector) — primary database
Redis — short-term agent memory and rate limiting
NATS (with JetStream) — async event queue
LiteLLM — LLM proxy
goway — Go backend (HTTP :8000, gRPC :9090)
frontend — React UI (:3000)

Database migrations are applied automatically on startup.

4. Seed Initial Data

Seed the default agents, tasks, and event mappings:

bash

# Seed default agents (pm_sarah, ta_leo, qa_quinn, hub_system, dev_alex)
curl -X POST http://localhost:8000/api/agents/seed

# Seed task definitions (9 default tasks)
curl -X POST http://localhost:8000/api/tasks/seed

# Seed trigger → task mappings
curl -X POST http://localhost:8000/api/tasks/triggers/seed

# Seed source event → canonical trigger mappings
curl -X POST http://localhost:8000/api/tasks/sources/seed

All seed endpoints are idempotent — they skip entries that already exist and return {"created": N, "skipped": M}.

5. Verify Everything Is Running

bash

# Check all containers are up
docker-compose ps

# Backend health
curl http://localhost:8000/health

# List seeded agents
curl http://localhost:8000/api/agents

6. Access the Application

URL	Description
http://localhost:3000	React frontend
http://localhost:8000	Backend REST API
http://localhost:9090	gRPC Agent Gateway
http://localhost:4000	LiteLLM proxy
http://localhost:4222	NATS messaging

7. View Logs

bash

# All services
docker-compose logs -f

# Backend only
docker-compose logs -f goway

# Frontend only
docker-compose logs -f frontend

8. Stop Services

bash

# Stop containers (preserves data)
docker-compose down

# Stop and remove volumes (wipes database)
docker-compose down -v

Development Setup

For active development with hot reload:

Start Infrastructure Only

bash

# Start only the external services, not the backend/frontend
docker-compose up -d postgres redis nats litellm

Run the Backend Locally

bash

cd goway

# Copy and edit environment file
cp .env.example .env

# Run with air for hot reload (install air first)
go install github.com/cosmtrek/air@latest
air

# Or run directly
make run

Backend will be at http://localhost:8000.

Run the Frontend Locally

bash

cd web
npm install
npm run dev

Frontend will be at http://localhost:5173 with hot module replacement.

Useful Backend Commands

bash

cd goway
make run          # Run locally
make build        # Build binary to bin/server
make test         # Run all tests
make fmt          # Format code
make lint         # Run golangci-lint
make migrate-up   # Apply pending migrations
make migrate-down # Rollback last migration

LiteLLM Configuration

LiteLLM is configured via litellm_config.yaml in the repository root.

Using Ollama (Default)

The default setup expects a local Ollama instance:

bash

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh  # Linux

# Pull the phi4 model
ollama pull phi4

The litellm_config.yaml connects to http://host.docker.internal:11434 by default.

In goway/.env:

bash

LLM_MODEL=ollama/phi4

Using OpenAI

Edit litellm_config.yaml:

yaml

model_list:
  - model_name: gpt-4
    litellm_params:
      model: gpt-4
      api_key: os.environ/OPENAI_API_KEY

general_settings:
  master_key: sk-aether-litellm-key

In goway/.env:

bash

OPENAI_API_KEY=sk-...
LLM_MODEL=gpt-4

Using Anthropic Claude

Edit litellm_config.yaml:

yaml

model_list:
  - model_name: claude-3-opus
    litellm_params:
      model: claude-3-opus-20240229
      api_key: os.environ/ANTHROPIC_API_KEY

general_settings:
  master_key: sk-aether-litellm-key

In goway/.env:

bash

ANTHROPIC_API_KEY=sk-ant-...
LLM_MODEL=claude-3-opus

After changing the LiteLLM config, restart:

bash

docker-compose restart litellm goway

Database Migrations

Migrations run automatically when the backend starts. The current schema has 42 migrations covering all entities.

Manual Migration Control

bash

cd goway

# Apply all pending migrations
make migrate-up

# Rollback the last migration
make migrate-down

# Create a new migration
migrate create -ext sql -dir migrations -seq your_migration_name

Reset Database

Destructive Operation

This deletes all data including agents, tasks, and configuration.

bash

docker-compose down -v
docker-compose up -d postgres
cd goway && make migrate-up

Troubleshooting Installation

Port Already in Use

bash

# Find what's on port 8000
lsof -i :8000

# Change the port in goway/.env
PORT=8001

Database Connection Refused

bash

# Check PostgreSQL container status
docker-compose ps postgres

# View database logs
docker-compose logs postgres

# Restart
docker-compose restart postgres

LiteLLM Not Responding

bash

docker-compose logs litellm

# Common cause: Ollama not running
curl http://localhost:11434/api/tags

# Restart after fixing
docker-compose restart litellm

Dirty Migration State

bash

# Connect to database
docker exec -it $(docker-compose ps -q postgres) psql -U postgres -d aether

# Check migration state
SELECT version, dirty FROM schema_migrations;

# If dirty=true, fix the version manually after resolving the migration
UPDATE schema_migrations SET dirty=false WHERE version=<version>;

Frontend Can't Reach Backend

Confirm backend is healthy: curl http://localhost:8000/health
Check CORS: the backend allows all origins in development by default
Verify the API base URL in web/src/services/api.ts

For more, see the Troubleshooting Guide.

Updating Aether

bash

git pull origin main
docker-compose down
docker-compose up --build -d
# Migrations apply automatically on startup

WARNING

Check for breaking changes in the commit history before upgrading in production. Aether is under active development and breaking changes may occur.

Uninstalling

bash

# Remove all containers and volumes (deletes all data)
docker-compose down -v

cd ..
rm -rf hacky-automation

Installation ​

Prerequisites ​

Quick Start with Docker Compose ​

1. Clone the Repository ​

2. Configure Environment ​

3. Start All Services ​

4. Seed Initial Data ​

5. Verify Everything Is Running ​

6. Access the Application ​

7. View Logs ​

8. Stop Services ​

Development Setup ​

Start Infrastructure Only ​

Run the Backend Locally ​

Run the Frontend Locally ​

Useful Backend Commands ​

LiteLLM Configuration ​

Using Ollama (Default) ​

Using OpenAI ​

Using Anthropic Claude ​

Database Migrations ​

Manual Migration Control ​

Reset Database ​

Troubleshooting Installation ​

Port Already in Use ​

Database Connection Refused ​

LiteLLM Not Responding ​

Dirty Migration State ​

Frontend Can't Reach Backend ​

Updating Aether ​

Uninstalling ​

Installation

Prerequisites

Quick Start with Docker Compose

1. Clone the Repository

2. Configure Environment

3. Start All Services

4. Seed Initial Data

5. Verify Everything Is Running

6. Access the Application

7. View Logs

8. Stop Services

Development Setup

Start Infrastructure Only

Run the Backend Locally

Run the Frontend Locally

Useful Backend Commands

LiteLLM Configuration

Using Ollama (Default)

Using OpenAI

Using Anthropic Claude

Database Migrations

Manual Migration Control

Reset Database

Troubleshooting Installation

Port Already in Use

Database Connection Refused

LiteLLM Not Responding

Dirty Migration State

Frontend Can't Reach Backend

Updating Aether

Uninstalling