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.
prompts	PromptSource[]	no	—	Default prompt sources shared by all agents. An agent inherits these only when its own prompts array is empty.
mcps	McpSourceSpec[]	no	—	Default MCP sources shared by all agents. An agent inherits these only when its own mcps array is empty.
providers	Record<string, ProviderConnectionOverride>	no	—	Provider connection overrides (credentials, base URLs, inference profiles) applied to every agent unless overridden per-agent.
credentialsStore	CredentialsStoreConfig | null	no	—	Credential storage backend for OAuth tokens. Defaults to the OS keyring when unset.
telemetry	TelemetrySettings | null	no	—	OpenTelemetry GenAI telemetry configuration. Its presence enables telemetry.
agents	AgentConfig[]	yes	—	The agents defined for this project. At least one agent is required.

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
path	string | null	no	—	File path for the encrypted credential blob. Defaults to .aether/credentials.enc in the Aether home directory when unset.
passwordEnv	string | null	no	—	Environment variable name to read the passphrase from. Uses AETHER_CREDENTIALS_PASSWORD when unset.
type	"encryptedFile"	yes	—	—

DeferredToolRules

Field	Type	Required	Default	Description
include	string[]	no	—	Tool names to defer. An empty list includes every tool.
exclude	string[]	no	—	Tool names to keep model-visible. Exclude rules take precedence over include rules.

InMemoryServerConfig

Field	Type	Required	Default	Description
type	InMemoryType	yes	—	Transport discriminant; always in-memory.
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.
deferTools	ToolExposure	no	—	Controls which tools are deferred from the model-visible tool definitions.

InMemoryType

Enum. One of:

• "in-memory"

McpOAuthConfig

Field	Type	Required	Default	Description
clientId	string | null	no	—	—
clientMetadataUrl	string | null	no	—	—
callbackPort	integer | 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 explicit Authorization header bypasses OAuth entirely.

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

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
path	ResourcePath	yes	—	—
deferTools	boolean	no	—	—
optional	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
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.
maxTokens	integer | null	no	—	Upper bound on the number of tokens generated in the response.

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.
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.
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.
headers	Record<string, string>	no	—	—

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
path	ResourcePath	yes	—	Path to a prompt file, resolved as a resource path.
optional	boolean	no	—	When true, a missing file is skipped instead of raising an error.
type	"file"	yes	—	—

PromptSourceObject (type: glob)

Field	Type	Required	Default	Description
pattern	ResourcePath	yes	—	Glob pattern matching prompt files, resolved as a resource path.
optional	boolean	no	—	When true, a zero-match glob is skipped instead of raising an error.
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
url	string | null	no	—	Base URL override for the provider’s API endpoint.
auth	ProviderAuthMode | null	no	—	Authentication mode. default uses the provider’s normal credential chain; none disables auth, for local or unauthenticated servers.
requestModel	string | null	no	—	Provider-specific model or deployment target sent in requests without changing catalog identity.
inferenceProfileArn	string | null	no	—	AWS Bedrock application inference profile ARN to route requests through.

ReasoningEffort

Enum. One of:

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

RemoteServerConfig

Field	Type	Required	Default	Description
type	RemoteType	yes	—	Transport discriminant; http (streamable HTTP) or sse (Server-Sent Events).
url	string	yes	—	Base URL of the remote MCP server.
headers	Record<string, string>	no	{}	Extra HTTP headers sent with every request.
oauth	McpOAuthConfig | null	no	—	OAuth settings for a pre-registered public client.
deferTools	ToolExposure	no	—	Controls which tools are deferred from the model-visible tool definitions.

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
type	StdioType	no	"stdio"	Transport discriminant; always stdio.
command	string	yes	—	Executable launched to run the MCP server over stdio.
args	string[]	no	[]	Command-line arguments passed to the executable.
env	Record<string, string>	no	{}	Environment variables set for the server process.
deferTools	ToolExposure	no	—	Controls which tools are deferred from the model-visible tool definitions.

StdioType

Enum. One of:

• "stdio"

TelemetryContentSettings

Field	Type	Required	Default	Description
systemInstructions	boolean | null	no	—	Set gen_ai.system_instructions on chat spans.
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.
toolDefinitions	boolean | null	no	—	Set gen_ai.tool.definitions on chat spans.
toolCalls	boolean | null	no	—	Set gen_ai.tool.call.arguments / gen_ai.tool.call.result on tool 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
serviceName	string | null	no	—	service.name resource attribute. Defaults to aether.
sampleRatio	number | null	no	—	Trace sampling ratio between 0.0 and 1.0. Defaults to 1.0.
content	TelemetryContentSettings	no	—	Per-attribute content capture, mapping 1:1 onto the opt-in GenAI content attributes. All default to false.
traces	TelemetrySignalSettings	no	—	Trace signal toggle. Enabled by default.
metrics	TelemetrySignalSettings	no	—	Metric signal toggle. Enabled by default.
otlp	OtlpTelemetrySettings	no	—	—

TelemetrySignalSettings

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

ToolAnnotationMatcher

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

ToolExposure

Which of a server’s tools are model-visible or deferred for progressive discovery.

One of:

• boolean
• DeferredToolRules

ToolFilter

Filter for restricting which MCP tools an agent may discover and execute.

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

ToolMatcher

One of:

• string
• ToolAnnotationMatcher