Configuration

Active Development

Configuration options are evolving. New environment variables may be added and existing ones may change between releases.

All Aether configuration is done through environment variables in goway/.env. Start from the example:

bash

cp goway/.env.example goway/.env

Core System

Required Variables

bash

# PostgreSQL connection string
DATABASE_URL=postgres://postgres:postgres@localhost:5432/aether?sslmode=disable

# NATS message queue
NATS_URL=nats://localhost:4222

# Redis (required for memory and rate limiting)
REDIS_URL=redis://localhost:6379

Optional Core Variables

bash

# HTTP server port (default: 8000)
PORT=8000

# Allowed CORS origins for the frontend (comma-separated)
# Default: allows all origins in development
FRONTEND_ORIGINS=http://localhost:3000,http://localhost:5173

# Enable database-backed watchdog logging (default: false)
WATCHDOG_ENABLED=true

# Enable/disable posting responses back to issue trackers (default: true)
TRACKER_UPDATES_ENABLED=true

# Encryption key for storing dynamic integration credentials
# Required if using dynamic integrations (agent-specific credentials)
ENCRYPTION_KEY=your-32-char-secret-key-here

LLM Configuration

Aether communicates with all LLMs through a LiteLLM proxy.

bash

# URL of your LiteLLM proxy
LLM_BASE_URL=http://localhost:4000

# API key configured in litellm_config.yaml
LLM_API_KEY=sk-aether-litellm-key

# Model name as defined in LiteLLM (must match litellm_config.yaml)
LLM_MODEL=ollama/phi4

# Maximum tool call iterations per request (default: 5)
LLM_MAX_TOOL_ROUNDS=5

Supported Models

Any model that LiteLLM supports can be used. Common examples:

`LLM_MODEL` value	Provider
`ollama/phi4`	Local Ollama (default)
`ollama/llama3.1`	Local Ollama
`gpt-4o`	OpenAI
`gpt-4-turbo`	OpenAI
`claude-3-5-sonnet-20241022`	Anthropic
`claude-3-opus-20240229`	Anthropic
`gemini/gemini-1.5-pro`	Google

Issue Tracker Integrations

Configure any combination of trackers. Unused trackers can be left unconfigured.

GitHub

bash

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Required scopes: repo, admin:repo_hook

How to create: GitHub Settings → Developer Settings → Personal access tokens → Generate new token

GitLab

bash

# GitLab instance URL (use https://gitlab.com for GitLab.com)
GITLAB_URL=https://gitlab.com

# Personal or project access token with `api` scope
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Works with GitLab.com and self-hosted GitLab instances.

Jira Cloud

bash

JIRA_URL=https://yourcompany.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-api-token
JIRA_IS_CLOUD=true

How to create an API token: https://id.atlassian.com/manage-profile/security/api-tokens

Jira Server / Data Center

bash

JIRA_URL=https://jira.yourcompany.com
JIRA_EMAIL=your-username        # Username, not email
JIRA_API_TOKEN=your-password    # Password or personal access token
JIRA_IS_CLOUD=false

Plane

bash

PLANE_API_URL=https://api.plane.so/api/v1
PLANE_API_KEY=plane_api_xxxxxxxxxxxxxxxxxxxx
PLANE_WORKSPACE_SLUG=your-workspace-slug

How to get: Plane Settings → API Tokens. Find your workspace slug in the URL: app.plane.so/your-slug/.

Agent Gateway (gRPC)

The gRPC Agent Gateway allows external agents to connect and receive tasks.

bash

# Enable the gRPC server (default: false)
AGENT_GATEWAY_ENABLED=true

# gRPC listen port (default: 9090)
AGENT_GATEWAY_PORT=9090

# How often agents must send heartbeats, in seconds (default: 30)
AGENT_HEARTBEAT_INTERVAL=30

# How long before an inactive session expires, in seconds (default: 120)
AGENT_SESSION_TIMEOUT=120

See Agent Runtime Protocol for details on connecting external agents.

Rate Limiting

Redis-backed rate limiting for the Agent Gateway. Limits are per-agent based on their trust level.

bash

# Enable rate limiting (default: false)
RATE_LIMIT_ENABLED=true

# LLM calls per hour per trust level
RATE_LIMIT_DEFAULT_LLM_CALLS_PER_HOUR=20
RATE_LIMIT_TRUSTED_LLM_CALLS_PER_HOUR=100
RATE_LIMIT_PRIVILEGED_LLM_CALLS_PER_HOUR=500

Memory & Embeddings

Controls the vector embedding model used for semantic memory search.

bash

# Embedding model (must be configured in LiteLLM or use a local model)
EMBEDDING_MODEL=text-embedding-3-small

# Vector dimension - must match the embedding model's output
# text-embedding-3-small: 1536, text-embedding-3-large: 3072
EMBEDDING_DIMENSION=1536

# Maximum results returned by semantic memory search (default: 10)
MEMORY_SEARCH_LIMIT=10

Seeding

bash

# Automatically seed from YAML files on startup (default: false)
SEED_ON_STARTUP=true

# Path to YAML seed files (default: goway/seeding)
SEED_DATA_PATH=./seeding

When SEED_ON_STARTUP=true, Aether will run all seed operations at startup. All seeds are idempotent.

Manual Seeding

You can also trigger seeding via the API at any time:

bash

# Seed default agents (from agents.yaml)
curl -X POST http://localhost:8000/api/agents/seed

# Seed task definitions (from tasks.yaml)
curl -X POST http://localhost:8000/api/tasks/seed

# Seed trigger → task mappings (from trigger_task_mappings.yaml)
curl -X POST http://localhost:8000/api/tasks/triggers/seed

# Seed source event → canonical trigger mappings (from source_event_mappings.yaml)
curl -X POST http://localhost:8000/api/tasks/sources/seed

Seeding YAML Format

goway/seeding/tasks.yaml — Task definitions:

yaml

- id: pm_analyze
  name: "PM: Analyze Issue"
  description: "Product Manager analyzes the issue"
  actor_id: pm_sarah
  actor_fallback: "You are a Product Manager. Analyze this issue."

goway/seeding/trigger_task_mappings.yaml — Canonical trigger → task:

yaml

- canonical_trigger: issue.created
  task_id: pm_analyze

- canonical_trigger: issue.created
  task_id: ta_technical_review

goway/seeding/source_event_mappings.yaml — Source event → canonical trigger:

yaml

- source: github
  event_name: issues
  action: opened
  canonical_trigger: issue.created

- source: jira
  event_name: "jira:issue_created"
  action: null
  canonical_trigger: issue.created

Webhook Configuration

All webhooks are received at a single unified endpoint:

POST http://your-aether-host:8000/webhook/:slug

The :slug identifies the source. For static integrations, the slug matches the source name.

GitHub

Repository Settings → Webhooks → Add webhook
Payload URL: http://your-aether-host:8000/webhook/github
Content type: application/json
Secret: (optional, used for HMAC-SHA256 verification — recommended)
Events: Issues, Pull requests, and any other events you want to handle

GitLab

Project Settings → Webhooks → Add new webhook
URL: http://your-aether-host:8000/webhook/gitlab
Secret token: (optional)
Triggers: Issues events, Merge request events, etc.

Jira

Jira Administration → System → WebHooks → Create a WebHook
URL: http://your-aether-host:8000/webhook/jira
Events: Issue created, Issue updated, etc.

Plane

Project Settings → Members & Settings → Webhooks
URL: http://your-aether-host:8000/webhook/plane
Events: issue.created, issue.updated, etc.

LiteLLM Proxy Configuration

litellm_config.yaml in the repository root configures the LiteLLM proxy:

Single Model (Ollama)

yaml

model_list:
  - model_name: phi4
    litellm_params:
      model: ollama/phi4
      api_base: http://host.docker.internal:11434

general_settings:
  master_key: sk-aether-litellm-key

Multiple Providers

yaml

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

  - model_name: claude-3-5-sonnet
    litellm_params:
      model: claude-3-5-sonnet-20241022
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: local
    litellm_params:
      model: ollama/phi4
      api_base: http://host.docker.internal:11434

general_settings:
  master_key: sk-aether-litellm-key

Switch between models by changing LLM_MODEL in goway/.env and restarting.

Database Connection Options

postgres://username:password@host:port/database?options

Option	Description
`sslmode=disable`	No SSL (local development)
`sslmode=require`	Require SSL (production)
`sslmode=verify-full`	Require SSL with cert verification
`connect_timeout=10`	Connection timeout in seconds
`pool_max_conns=25`	Maximum connections in pool

Examples:

bash

# Local development
DATABASE_URL=postgres://postgres:postgres@localhost:5432/aether?sslmode=disable

# Production with SSL
DATABASE_URL=postgres://user:pass@db.example.com:5432/aether?sslmode=require

# AWS RDS
DATABASE_URL=postgres://user:pass@instance.region.rds.amazonaws.com:5432/aether?sslmode=require

Production Security Checklist

[ ] Use strong, unique database password
[ ] Enable sslmode=require for database connections
[ ] Set a strong, random ENCRYPTION_KEY (min 32 chars) for dynamic integrations
[ ] Use HTTPS for all webhook endpoints (put Aether behind nginx or Caddy)
[ ] Configure webhook secrets in GitHub/GitLab for HMAC verification
[ ] Use dedicated service accounts for GitHub/GitLab/Jira/Plane tokens
[ ] Rotate API tokens regularly
[ ] Enable RATE_LIMIT_ENABLED=true when using the Agent Gateway
[ ] Restrict FRONTEND_ORIGINS to your actual frontend domain

Full Environment Variable Reference

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	PostgreSQL connection string
`NATS_URL`	Yes	—	NATS server URL
`REDIS_URL`	Yes	—	Redis URL for memory and rate limiting
`PORT`	No	`8000`	HTTP server listen port
`FRONTEND_ORIGINS`	No	`*`	CORS allowed origins
`LLM_BASE_URL`	Yes	—	LiteLLM proxy URL
`LLM_API_KEY`	Yes	—	LiteLLM API key
`LLM_MODEL`	Yes	—	Model name
`LLM_MAX_TOOL_ROUNDS`	No	`5`	Max tool call iterations
`TRACKER_UPDATES_ENABLED`	No	`true`	Post responses to issue trackers
`ENCRYPTION_KEY`	No*	—	*Required for dynamic integrations
`WATCHDOG_ENABLED`	No	`false`	Enable database watchdog logging
`SEED_ON_STARTUP`	No	`false`	Auto-seed on startup
`SEED_DATA_PATH`	No	`./seeding`	Path to YAML seed files
`GITHUB_TOKEN`	No	—	GitHub personal access token
`GITLAB_URL`	No	—	GitLab instance URL
`GITLAB_TOKEN`	No	—	GitLab access token
`JIRA_URL`	No	—	Jira instance URL
`JIRA_EMAIL`	No	—	Jira username or email
`JIRA_API_TOKEN`	No	—	Jira API token or password
`JIRA_IS_CLOUD`	No	`true`	`false` for Jira Server/DC
`PLANE_API_URL`	No	—	Plane API URL
`PLANE_API_KEY`	No	—	Plane API key
`PLANE_WORKSPACE_SLUG`	No	—	Plane workspace slug
`AGENT_GATEWAY_ENABLED`	No	`false`	Enable gRPC Agent Gateway
`AGENT_GATEWAY_PORT`	No	`9090`	gRPC server port
`AGENT_HEARTBEAT_INTERVAL`	No	`30`	Heartbeat interval (seconds)
`AGENT_SESSION_TIMEOUT`	No	`120`	Session timeout (seconds)
`RATE_LIMIT_ENABLED`	No	`false`	Enable rate limiting
`RATE_LIMIT_DEFAULT_LLM_CALLS_PER_HOUR`	No	`20`	Default trust level
`RATE_LIMIT_TRUSTED_LLM_CALLS_PER_HOUR`	No	`100`	Trusted agent level
`RATE_LIMIT_PRIVILEGED_LLM_CALLS_PER_HOUR`	No	`500`	Privileged agent level
`EMBEDDING_MODEL`	No	—	Embedding model for semantic search
`EMBEDDING_DIMENSION`	No	`1536`	Vector dimension
`MEMORY_SEARCH_LIMIT`	No	`10`	Max semantic search results

Configuration ​

Core System ​

Required Variables ​

Optional Core Variables ​

LLM Configuration ​

Supported Models ​

Issue Tracker Integrations ​

GitHub ​

GitLab ​

Jira Cloud ​

Jira Server / Data Center ​

Plane ​

Agent Gateway (gRPC) ​

Rate Limiting ​

Memory & Embeddings ​

Seeding ​

Manual Seeding ​

Seeding YAML Format ​

Webhook Configuration ​

GitHub ​

GitLab ​

Jira ​

Plane ​

LiteLLM Proxy Configuration ​

Single Model (Ollama) ​

Multiple Providers ​

Database Connection Options ​

Production Security Checklist ​

Full Environment Variable Reference ​

Configuration

Core System

Required Variables

Optional Core Variables

LLM Configuration

Supported Models

Issue Tracker Integrations

GitHub

GitLab

Jira Cloud

Jira Server / Data Center

Plane

Agent Gateway (gRPC)

Rate Limiting

Memory & Embeddings

Seeding

Manual Seeding

Seeding YAML Format

Webhook Configuration

GitHub

GitLab

Jira

Plane

LiteLLM Proxy Configuration

Single Model (Ollama)

Multiple Providers

Database Connection Options

Production Security Checklist

Full Environment Variable Reference