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 content is not exported unless the matching telemetry.content flag is explicitly set to true.

{
  "telemetry": {
    "serviceName": "aether",
    "sampleRatio": 1.0,
    "content": {
      "systemInstructions": false,
      "inputMessages": false,
      "outputMessages": false,
      "toolDefinitions": false,
      "toolCalls": 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
    }
  ]
}

All content flags default to false; enable only the content attributes appropriate for your collector and its access controls. See the website telemetry reference for the complete attribute mapping.

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 }, "review__review_artifact"] }
}

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 credentials.enc in the Aether home directory when unset.
type	"encryptedFile"	yes	—	—

InMemoryServerConfig

Field	Type	Required	Default	Description
args	string[]	no	[]	—
deferTools	ToolExposureConfig	no	—	—
type	InMemoryType	yes	—	—

InMemoryType

Enum. One of:

• "in-memory"

McpOAuthConfig

Field	Type	Required	Default	Description
callbackPort	integer | null	no	—	—
clientId	string | null	no	—	—
clientMetadataUrl	string | null	no	—	—

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 a remote HTTP server returns an OAuth challenge, Aether uses its first-party Client ID Metadata Document at https://aether-agent.io/oauth/client-metadata.json and listens on 127.0.0.1:3118, advertising the exact redirect URI http://localhost:3118/. If port 3118 is occupied, authentication fails until the port is available.

The oauth object is optional. Set clientMetadataUrl for a custom CIMD, or clientId for a pre-registered public client; a configured clientId takes priority. callbackPort defaults to 3118 and must exactly match the client’s registered redirect URI. If the authorization server does not advertise CIMD, Aether falls back to deprecated Dynamic Client Registration. An Authorization header on its own turns off OAuth.

A server can configure one of oauth, sigv4, or an Authorization header. For example:

{
  "type": "http",
  "url": "https://abc123.execute-api.us-east-1.amazonaws.com/mcp",
  "sigv4": { "service": "execute-api", "region": "us-east-1", "profile": "dev" }
}

A remote server using a bearer token:

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

Set "deferTools": true to omit every tool on this server from the model-visible tool definitions and make it available through progressive aether mcp discovery. For selective deferral, set deferTools to an object with include and exclude lists. Entries match either an exact MCP-local tool name or a prefix ending in *:

{
  "type": "in-memory",
  "deferTools": {
    "include": ["*"],
    "exclude": ["bash", "lsp_*"]
  }
}

One of:

• StdioServerConfig
• RemoteServerConfig
• InMemoryServerConfig

McpSigV4Config

Field	Type	Required	Default	Description
profile	string | null	no	—	—
region	string	yes	—	—
service	string	yes	—	—

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:

• ResourcePath
• McpSourceSpecObject

McpSourceSpecObject

One of:

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

McpSourceSpecObject (type: file)

Field	Type	Required	Default	Description
deferTools	boolean	no	—	—
optional	boolean	no	—	—
path	ResourcePath	yes	—	—
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:

• ResourcePath
• 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.

Give a slow local model more time to produce its first token. A request fails with a retryable timeout once the provider has been silent for idleTimeoutSecs (default 300), before responding or between stream events:

{ "idleTimeoutSecs": 900 }

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.
idleTimeoutSecs	integer | null	no	—	—
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:

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

RemoteServerConfig

Field	Type	Required	Default	Description
deferTools	ToolExposureConfig	no	—	—
headers	Record<string, string>	no	{}	—
oauth	McpOAuthConfig | null	no	—	—
sigv4	McpSigV4Config | null	no	—	—
type	RemoteType	yes	—	—
url	string	yes	—	—

RemoteType

Enum. One of:

• "http"

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	string	yes	—	—
deferTools	ToolExposureConfig	no	—	—
env	Record<string, string>	no	{}	—
type	StdioType	no	"stdio"	—

StdioType

Enum. One of:

• "stdio"

TelemetryContentSettings

Field	Type	Required	Default	Description
inputMessages	boolean | null	no	—	Set gen_ai.input.messages on turn and chat spans.
outputMessages	boolean | null	no	—	Set gen_ai.output.messages on turn and chat spans.
systemInstructions	boolean | null	no	—	Set gen_ai.system_instructions on chat spans.
toolCalls	boolean | null	no	—	Set gen_ai.tool.call.arguments / gen_ai.tool.call.result on tool spans.
toolDefinitions	boolean | null	no	—	Set gen_ai.tool.definitions on chat spans.

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
content	TelemetryContentSettings	no	—	Per-attribute content capture, mapping 1:1 onto the opt-in GenAI content attributes. All default 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	—	—

ToolExposureConfig

One of:

• boolean
• ToolExposureConfig variant 1

ToolExposureConfig variant 1

Field	Type	Required	Default	Description
exclude	ToolMatcher[]	no	—	—
include	ToolMatcher[]	no	—	—

ToolFilter

Field	Type	Required	Default	Description
allow	ToolMatcher[]	no	—	—
deny	ToolMatcher[]	no	—	—

ToolMatcher

One of:

• string
• ToolAnnotationMatcher