Aether

Instant, deterministic, scenario-driven local API simulator.

Why

Frontend apps, mobile clients, and AI coding workflows all move faster when backend behavior is reproducible. Aether gives you a local backend with explicit state, deterministic route resolution, and portable scenario data.

Installation

Download a prebuilt binary from Releases.

Linux x64:

wget https://github.com/maiano/aether/releases/download/v0.1.0/aether-linux-amd64-v0.1.0.tar.gz
tar -xzf aether-linux-amd64-v0.1.0.tar.gz
cd aether-linux-amd64-v0.1.0
./aether start --config examples/ecommerce/aether.json

macOS Apple Silicon:

curl -LO https://github.com/maiano/aether/releases/download/v0.1.0/aether-macos-aarch64-v0.1.0.tar.gz
tar -xzf aether-macos-aarch64-v0.1.0.tar.gz
cd aether-macos-aarch64-v0.1.0
./aether start --config examples/ecommerce/aether.json

macOS Intel:

curl -LO https://github.com/maiano/aether/releases/download/v0.1.0/aether-macos-amd64-v0.1.0.tar.gz
tar -xzf aether-macos-amd64-v0.1.0.tar.gz
cd aether-macos-amd64-v0.1.0
./aether start --config examples/ecommerce/aether.json

Developer-only local bundles:

zig build release
ls release/0.1.0

Quickstart

The bundled example config includes:

• one base route: GET /api/me
• one scenario value: auth=expired
• one profile: auth-expired

Start the server and flip one scenario:

./aether start --config examples/ecommerce/aether.json
curl -s http://127.0.0.1:4545/api/me
curl -s -X PATCH http://127.0.0.1:4545/__control/scenario \
  -H "Content-Type: application/json" \
  -d '{"auth":"expired"}'
curl -i http://127.0.0.1:4545/api/me

Config

By default, Aether reads:

.aether/aether.json

Override it explicitly when needed:

./aether start --config examples/ecommerce/aether.json

Discover States

CLI discovery commands read the config file directly. The matching curl examples read the running server through the Control API.

List available scenario values:

./aether scenario list --config examples/ecommerce/aether.json
curl -s http://127.0.0.1:4545/__control/scenarios

Describe one scenario value:

./aether scenario describe auth=expired --json --config examples/ecommerce/aether.json
curl -s http://127.0.0.1:4545/__control/scenarios/auth/expired

List available profiles:

./aether profile list --config examples/ecommerce/aether.json
curl -s http://127.0.0.1:4545/__control/profiles

profile apply on the CLI validates the profile against config and prints the next active state. Runtime application is done through the Control API:

curl -s -X POST http://127.0.0.1:4545/__control/profile/apply \
  -H "Content-Type: application/json" \
  -d '{"profile":"auth-expired"}'

For Humans

Use Aether when you need a small local backend with deterministic states. The usual flow is: download a release binary, point it at your config, inspect scenario values or profiles, switch runtime state through the local Control API, and keep your frontend or client running against the same local server.

For AI Agents

Prefer the prebuilt release binary so nothing needs to be compiled first.

Typical flow:

./aether start --config examples/ecommerce/aether.json
./aether scenario list --config examples/ecommerce/aether.json
./aether scenario describe auth=expired --json --config examples/ecommerce/aether.json
curl -s http://127.0.0.1:4545/__control/scenario
curl -s -X PATCH http://127.0.0.1:4545/__control/scenario \
  -H "Content-Type: application/json" \
  -d '{"auth":"expired"}'

Portable fixture data is available through export commands:

./aether scenario export auth=expired --mode behavior --config examples/ecommerce/aether.json
./aether profile export auth-expired --config examples/ecommerce/aether.json

Recorded traffic can be asserted from the CLI:

./aether traffic assert --method GET --path /api/me --status 401
./aether traffic find --method GET --path /api/me --status 401

Core Idea

Routes describe endpoints. Scenarios describe backend reality.

Instead of mocking one endpoint at a time, Aether models state such as auth=expired or payment=timeout and resolves responses from that state in a deterministic way.

Current Features

• Single local binary
• Strict JSON config
• Exact and parameterized route matching
• Scenario switching through local HTTP Control API
• Scenario discovery through CLI and HTTP
• Scenario profiles as named active states
• Scenario and profile export/import
• NDJSON traffic logging
• Basic traffic assertions and filtered event lookup from recorded NDJSON logs
• Deterministic route resolution

Non-Goals

• Proxy mode
• Built-in UI
• JSON5 config
• Plugin runtime
• Embedded scripting runtime
• Multi-protocol simulation platform

Docs

• Configuration
• CLI Reference
• Control API
• Scenario Model
• Route Resolution
• Runtime State Model
• Configuration Validation
• Scenario Model Expansion
• Roadmap