Configuration

Configuration is yaml, layered:

./aster.yaml            # project, wins
~/.aster/aster.yaml     # global
built-in defaults       # lose

Project values override global values override defaults, section by section. Precedence for the things that can also come from elsewhere: CLI flags > environment variables > aster.yaml > defaults. Keys never live in yaml. They go in .env files (~/.aster/.env global, .env in the repo local), loaded into the environment at startup.

Managing from the shell

aster config                          # form in a terminal, table when piped
aster config list | get KEY | set KEY VALUE [--global|--local] | unset KEY
aster config path | edit [--global|--local]
aster config providers | provider [ID --model M] | models [--capabilities] | model [ID]
aster config keys [--all] | key [VAR [VALUE]] [--local]

aster key list [--all] | get VAR | set VAR [VALUE] [--stdin] [--local] | unset VAR | path

aster provider list
aster provider use openai [--model gpt-5.5]   # endpoint and model together
aster model list [--capabilities] | use ID | recommended
aster model router [--tier cheap|balanced|strong]

aster config list prints each setting with the layer it came from, which is the fastest way to answer “why is this value what it is”.

Sections

`provider` and `model`

provider: openrouter        # any OpenAI-compatible endpoint id or base URL
model: anthropic/claude-sonnet-4.5
effort: medium              # off|low|medium|high|xhigh|max|ultra

Any OpenAI-compatible endpoint works: point provider at a base URL and set a key var named for it. A key var named for the endpoint (ANTHROPIC_API_KEY, OPENROUTER_API_KEY) beats the shared ASTER_API_KEY.

`permissions`

See Permissions for the full language.

permissions:
  mode: edit
  allow: ["Bash(cargo test:*)"]
  ask:   ["Bash(git push:*)"]
  deny:  ["Edit(infra/**)"]
  use_default_rules: true
  additional_directories: ["~/Downloads"]
  allow_credentials: ["gh:~/.config/gh"]

`agent`

agent:
  max_tool_rounds: 60            # ASTER_MAX_TOOL_ROUNDS
  command_timeout_secs: 300      # ASTER_COMMAND_TIMEOUT
  compact_budget_chars: 192000   # ASTER_COMPACT_BUDGET

`review`

See Review for every key.

`mcp`

See MCP servers for the full section.

mcp:
  servers: {}
  context_tokens: 100000
  inventory_percent: 1.5
  tools:
    allow: []
    deny: []

`schedules`

See Schedules.

schedules:
  - name: nightly-review
    cron: "0 9 * * *"
    agent: sentinel
    task: "review yesterday's commits on main"
    notify: true

`agents`

Sub-agent limits: max_concurrent, max_per_turn, agent_timeout_secs, collector_model. See Sub-agents.

`ui`

ui:
  theme: dark          # any built-in or custom theme name
  welcome: true        # session header on launch

`mom.yaml`: model routing per turn

A mom.yaml in the repo root or ~/.aster/ routes each turn to a model by intent. Entries describe intent (power, thinking, prefer), switch rules fire on conditions like planning, stuck, looping, model-down, and a cheap router judges the rest. Switches show as mom: notes in chat.

aster mom check                 # validate, show what each entry resolves to
aster mom route "refactor the auth module"   # which entry the router would pick

Spec: specs/mom.md in the main repository. Logs: ~/.aster/logs/mom-router.jsonl and mom-switches.jsonl.

Environment variables

See Environment variables for the full list. The two that outrank the yaml file: ASTER_MODEL and ASTER_BASE_URL, both reported by aster status when set.

Start

Using Aster

Extending

Automation

Workflows

Surfaces

Reference

Configuration

Managing from the shell

Sections

`provider` and `model`

`permissions`

`agent`

`review`

`mcp`

`schedules`

`agents`

`ui`

`mom.yaml`: model routing per turn

Environment variables

​Managing from the shell

​Sections

​provider and model

​permissions

​agent

​review

​mcp

​schedules

​agents

​ui

​mom.yaml: model routing per turn

​Environment variables

Managing from the shell

Sections

`provider` and `model`

`permissions`

`agent`

`review`

`mcp`

`schedules`

`agents`

`ui`

`mom.yaml`: model routing per turn

Environment variables