Settings reference

AetherSettings

The root of an Aether settings file (.aether/settings.json). It selects the default agent and defines the agents, prompt sources, MCP servers, and provider overrides available to a project.

Basic Examples

A minimal project with a single user-invocable agent:

{
  "agent": "Build",
  "agents": [
    {
      "name": "Build",
      "description": "Builds features and fixes bugs",
      "model": "anthropic:claude-sonnet-4-5-20250929",
      "userInvocable": true
    }
  ]
}

A fuller setup with shared prompts, an MCP source, and a provider override:

{
  "agent": "Build",
  "prompts": ["AGENTS.md"],
  "mcps": [".aether/mcp.json"],
  "providers": {
    "anthropic": { "auth": "default" }
  },
  "agents": [
    {
      "name": "Build",
      "description": "Builds features and fixes bugs",
      "model": "anthropic:claude-sonnet-4-5-20250929",
      "reasoningEffort": "high",
      "userInvocable": true,
      "prompts": [".aether/BUILD.md", "AGENTS.md"]
    }
  ]
}

An encrypted file credential store using a passphrase from the environment:

{
  "credentialsStore": {
    "type": "encryptedFile",
    "passwordEnv": "PASSWORD_ENV_VAR_NAME"
  },
  "agents": [
    {
      "name": "Build",
      "description": "Builds features and fixes bugs",
      "model": "anthropic:claude-sonnet-4-5-20250929",
      "userInvocable": true
    }
  ]
}

OpenTelemetry

OpenTelemetry is enabled by adding a telemetry section to settings. User-level telemetry settings merge with project-level, with project-level taking priority. Prompt, response, reasoning, and tool argument content is not exported unless captureContent is explicitly set to true.

{
  "telemetry": {
    "serviceName": "aether",
    "sampleRatio": 1.0,
    "captureContent": false,
    "traces": { "enabled": true },
    "metrics": { "enabled": true },
    "otlp": {
      "endpoint": "http://localhost:4318"
    }
  },
  "agents": [
    {
      "name": "Build",
      "description": "Builds features and fixes bugs",
      "model": "anthropic:claude-sonnet-4-5-20250929",
      "userInvocable": true
    }
  ]
}

For an OTLP backend with exact signal URLs, set otlp.tracesEndpoint and otlp.metricsEndpoint. Aether sends each configured signal to its matching URL unchanged; an unconfigured signal uses the /v1/traces or /v1/metrics URL derived from otlp.endpoint.

Field	Type	Required	Default	Description
agent	string | null	no	—	Name of the agent to launch by default. Must match a name in agents. When unset, Aether falls back to the first user-invocable agent.
agents	AgentConfig[]	yes	—	The agents defined for this project. At least one agent is required.
credentialsStore	CredentialsStoreConfig | null	no	—	Credential storage backend for OAuth tokens. Defaults to the OS keyring when unset.
mcps	McpSourceSpec[]	no	—	Default MCP sources shared by all agents. An agent inherits these only when its own mcps array is empty.
prompts	PromptSource[]	no	—	Default prompt sources shared by all agents. An agent inherits these only when its own prompts array is empty.
providers	Record<string, ProviderConnectionOverride>	no	—	Provider connection overrides (credentials, base URLs, inference profiles) applied to every agent unless overridden per-agent.
telemetry	TelemetrySettings | null	no	—	OpenTelemetry GenAI telemetry configuration. Its presence enables telemetry.

AgentConfig

A single agent definition. Every agent must be invocable on at least one surface — set userInvocable, agentInvocable, or both.

A user-invocable agent with its own prompt and a read-only tool allowlist:

{
  "name": "Review",
  "description": "Reviews diffs and suggests changes",
  "model": "anthropic:claude-sonnet-4-5-20250929",
  "userInvocable": true,
  "prompts": [".aether/REVIEW.md"],
  "tools": { "allow": [{ "readOnly": true }, "plan__*"] }
}

A deterministic judge agent that pins sampling via modelSettings:

{
  "name": "Judge",
  "description": "Grades responses against a rubric",
  "model": "anthropic:claude-sonnet-4-5-20250929",
  "userInvocable": true,
  "modelSettings": { "temperature": 0, "maxTokens": 1024 }
}

A sub-agent (callable by other agents) that pins a Bedrock inference profile:

{
  "name": "Search",
  "description": "Answers questions about the codebase",
  "model": "anthropic.claude-sonnet-4-5-20250929-v1:0",
  "agentInvocable": true,
  "providers": {
    "bedrock": {
      "inferenceProfileArn": "arn:aws:bedrock:us-west-2:000000000000:application-inference-profile/abc"
    }
  }
}

Type: any

CredentialsStoreConfig

One of:

• CredentialsStoreConfig (type: keyring)
• CredentialsStoreConfig (type: memory)
• CredentialsStoreConfig (type: encryptedFile)

CredentialsStoreConfig (type: keyring)

Field	Type	Required	Default	Description
type	"keyring"	yes	—	—

CredentialsStoreConfig (type: memory)

Field	Type	Required	Default	Description
type	"memory"	yes	—	—

CredentialsStoreConfig (type: encryptedFile)

Field	Type	Required	Default	Description
passwordEnv	string | null	no	—	Environment variable name to read the passphrase from. Uses AETHER_CREDENTIALS_PASSWORD when unset.
path	string | null	no	—	File path for the encrypted credential blob. Defaults to .aether/credentials.enc in the Aether home directory when unset.
type	"encryptedFile"	yes	—	—

InMemoryServerConfig

Field	Type	Required	Default	Description
args	string[]	no	[]	Arguments passed to the built-in (in-process) server.
input	any	no	null	Optional JSON input passed to the built-in server at startup.
proxy	boolean	no	—	Expose this server’s tools through Aether’s tool proxy.
type	InMemoryType	yes	—	Transport discriminant; always in-memory.

InMemoryType

Enum. One of:

• "in-memory"

McpOAuthConfig

Field	Type	Required	Default	Description
callbackPort	integer	yes	—	—
clientId	string	yes	—	—

McpServerConfig

A single MCP server. The type field selects the transport; stdio is the default and may be omitted.

A local stdio server launched as a subprocess:

{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": { "GITHUB_TOKEN": "ghp_..." }
}

A remote streamable-HTTP server using a pre-registered public OAuth client:

{
  "type": "http",
  "url": "https://mcp.slack.com/mcp",
  "oauth": {
    "clientId": "1601185624273.8899143856786",
    "callbackPort": 3118
  }
}

When oauth is omitted, Aether uses dynamic client registration and a random loopback callback port. When present, Aether binds the configured callback port and advertises http://localhost:<callbackPort>/, which must match the redirect URI registered for the OAuth client.

A remote server using a bearer token:

{
  "type": "http",
  "url": "https://mcp.example.com",
  "headers": { "Authorization": "Bearer ..." }
}

One of:

• StdioServerConfig
• RemoteServerConfig
• InMemoryServerConfig

McpSourceSpec

MCP config source — either a file path string or an inline server definition.

Point at a JSON file of servers:

".aether/mcp.json"

Reference a file with options:

{ "type": "file", "path": ".aether/mcp.json", "optional": true }

Or define servers inline:

{
  "type": "inline",
  "servers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

One of:

• string
• McpSourceSpecObject

McpSourceSpecObject

One of:

• McpSourceSpecObject (type: file)
• McpSourceSpecObject (type: inline)

McpSourceSpecObject (type: file)

Field	Type	Required	Default	Description
optional	boolean	no	—	—
path	ResourcePath	yes	—	—
proxy	boolean	no	—	—
type	"file"	yes	—	—

McpSourceSpecObject (type: inline)

Field	Type	Required	Default	Description
servers	Record<string, McpServerConfig>	yes	—	—
type	"inline"	yes	—	—

ModelSettings

Field	Type	Required	Default	Description
maxTokens	integer | null	no	—	Upper bound on the number of tokens generated in the response.
temperature	number | null	no	—	Sampling temperature. Lower is more deterministic (e.g. 0 for grading).
topP	number | null	no	—	Nucleus sampling: the probability mass to sample from.

OtlpTelemetrySettings

Field	Type	Required	Default	Description
endpoint	string | null	no	—	Base URL for an OTLP/HTTP collector. Aether appends /v1/traces or /v1/metrics for the respective signal.
headers	Record<string, string>	no	—	—
metricsEndpoint	string | null	no	—	Exact OTLP/HTTP metric export URL. Overrides the metrics URL derived from endpoint, for providers that require a signal-specific endpoint.
tracesEndpoint	string | null	no	—	Exact OTLP/HTTP trace export URL. Overrides the traces URL derived from endpoint, for providers that require a signal-specific endpoint.

PromptSource

Authored description of a prompt source — either a file path string or a typed text, file, or glob object.

A file path (the most common form):

"AGENTS.md"

Inline text:

{ "type": "text", "text": "You are a careful, concise engineer." }

A glob that loads every matching file:

{ "type": "glob", "pattern": ".aether/prompts/*.md", "optional": true }

One of:

• string
• PromptSourceObject

PromptSourceObject

One of:

• PromptSourceObject (type: text)
• PromptSourceObject (type: file)
• PromptSourceObject (type: glob)

PromptSourceObject (type: text)

Field	Type	Required	Default	Description
text	string	yes	—	Literal prompt text included verbatim.
type	"text"	yes	—	—

PromptSourceObject (type: file)

Field	Type	Required	Default	Description
optional	boolean	no	—	When true, a missing file is skipped instead of raising an error.
path	ResourcePath	yes	—	Path to a prompt file, resolved as a resource path.
type	"file"	yes	—	—

PromptSourceObject (type: glob)

Field	Type	Required	Default	Description
optional	boolean	no	—	When true, a zero-match glob is skipped instead of raising an error.
pattern	ResourcePath	yes	—	Glob pattern matching prompt files, resolved as a resource path.
type	"glob"	yes	—	—

ProviderAuthMode

Enum. One of:

• "default"
• "none"

ProviderConnectionOverride

Per-provider connection settings, merged over the built-in defaults.

Force first-party auth (e.g. an OAuth store) for a provider:

{ "auth": "default" }

Point a provider at a custom base URL with auth disabled:

{ "url": "https://gateway.internal/v1", "auth": "none" }

Request-target routing keeps the catalog model identity and its capabilities while sending a different provider-specific model or deployment name on the wire:

{ "requestModel": "production-coding-deployment" }

Use url for providers with resource-specific endpoints, such as Microsoft Foundry. A trailing slash is normalized before /chat/completions is appended. A provider with requestModel cannot appear more than once in an alloy because the target would be ambiguous.

Pin a Bedrock application inference profile:

{ "inferenceProfileArn": "arn:aws:bedrock:us-west-2:000000000000:application-inference-profile/abc" }

Field	Type	Required	Default	Description
auth	ProviderAuthMode | null	no	—	Authentication mode. default uses the provider’s normal credential chain; none disables auth, for local or unauthenticated servers.
inferenceProfileArn	string | null	no	—	AWS Bedrock application inference profile ARN to route requests through.
requestModel	string | null	no	—	Provider-specific model or deployment target sent in requests without changing catalog identity.
url	string | null	no	—	Base URL override for the provider’s API endpoint.

ReasoningEffort

Enum. One of:

• "minimal"
• "low"
• "medium"
• "high"
• "xhigh"
• "max"

RemoteServerConfig

Field	Type	Required	Default	Description
headers	Record<string, string>	no	{}	Extra HTTP headers sent with every request.
oauth	McpOAuthConfig | null	no	—	OAuth settings for a pre-registered public client.
proxy	boolean	no	—	Expose this server’s tools through Aether’s tool proxy.
type	RemoteType	yes	—	Transport discriminant; http (streamable HTTP) or sse (Server-Sent Events).
url	string	yes	—	Base URL of the remote MCP server.

RemoteType

Enum. One of:

• "http"
• "sse"

ResourcePath

A path with optional $VAR / ${VAR} expansion. ${WORKSPACE} resolves to the workspace root; other names fall through to process env. Plain relative paths resolve against the workspace root at use time.

Type: string

StdioServerConfig

Field	Type	Required	Default	Description
args	string[]	no	[]	Command-line arguments passed to the executable.
command	string	yes	—	Executable launched to run the MCP server over stdio.
env	Record<string, string>	no	{}	Environment variables set for the server process.
proxy	boolean	no	—	Expose this server’s tools through Aether’s tool proxy.
type	StdioType	no	"stdio"	Transport discriminant; always stdio.

StdioType

Enum. One of:

• "stdio"

TelemetrySettings

One settings layer’s OpenTelemetry configuration. Every field is optional: a field left unset inherits the value from lower-precedence settings layers and falls back to its documented default when no layer sets it. Read resolved values through the accessor methods.

Field	Type	Required	Default	Description
captureContent	boolean | null	no	—	Whether prompt, response, reasoning, and tool argument content is exported. Defaults to false.
metrics	TelemetrySignalSettings	no	—	Metric signal toggle. Enabled by default.
otlp	OtlpTelemetrySettings	no	—	—
sampleRatio	number | null	no	—	Trace sampling ratio between 0.0 and 1.0. Defaults to 1.0.
serviceName	string | null	no	—	service.name resource attribute. Defaults to aether.
traces	TelemetrySignalSettings	no	—	Trace signal toggle. Enabled by default.

TelemetrySignalSettings

Field	Type	Required	Default	Description
enabled	boolean | null	no	—	—

ToolAnnotationMatcher

Field	Type	Required	Default	Description
destructive	boolean | null	no	—	—
idempotent	boolean | null	no	—	—
openWorld	boolean | null	no	—	—
readOnly	boolean | null	no	—	—

ToolFilter

Filter for restricting which tools an agent can use.

Supports allow (allowlist) and deny (blocklist) with name patterns and MCP annotation matchers. If both are set, allow is applied first, then deny removes from the result. An empty filter (the default) allows all tools.

Allow specific tools by name:

{ "allow": ["read_file", "grep", "find"] }

Allow tools annotated as read-only by their MCP server:

{ "allow": [{ "readOnly": true }] }

Combine tool matchers with exact or trailing-* name patterns:

{ "allow": [{ "readOnly": true }, "plan__*"], "deny": ["coding__web_*"] }

Deny always wins over allow:

{ "allow": [{ "readOnly": true }], "deny": [{ "openWorld": true }] }

Annotation matcher fields are readOnly, destructive, idempotent, and openWorld. Missing tool annotations or missing annotation fields do not receive default boolean values and do not match.

Field	Type	Required	Default	Description
allow	ToolMatcher[]	no	—	If non-empty, only tools matching these patterns or annotations are allowed.
deny	ToolMatcher[]	no	—	Tools matching these patterns or annotations are removed.

ToolMatcher

One of:

• string
• ToolAnnotationMatcher