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.

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
    }
  ]
}

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.

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 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"
    }
  }
}

Field	Type	Required	Default	Description
agentInvocable	boolean	no	false	Exposes the agent to the subagents MCP server so other agents can spawn it.
contextWindow	integer | null	no	—	Override for the model’s context window, in tokens. Defaults to the model’s advertised window.
description	string	yes	—	Human-readable description shown in UIs and sub-agent listings.
mcps	McpSourceSpec[]	no	—	Agent-specific MCP sources. A non-empty array replaces the top-level mcps.
model	string	yes	—	Model spec for this agent, in provider:model-id form. Accepts a comma-separated alloy of specs to round-robin across turns.
name	string	yes	—	Agent identifier. Names are trimmed for merge and lookup.
prompts	PromptSource[]	no	—	Agent-specific prompt sources. A non-empty array replaces the top-level prompts.
providers	Record<string, ProviderConnectionOverride>	no	—	Per-agent provider overrides, merged over the top-level providers.
reasoningEffort	ReasoningEffort | null	no	—	Optional thinking budget for providers that support extended reasoning.
tools	ToolFilter	no	—	Per-agent MCP tool filter (allow/deny lists).
userInvocable	boolean	no	false	Exposes the agent as a user-selectable mode.

Constraint: at least one of userInvocable, agentInvocable must be set.

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	—	—

HttpServerConfig

Field	Type	Required	Default	Description
headers	Record<string, string>	no	{}	Extra HTTP headers sent with every request.
proxy	boolean	no	—	Expose this server’s tools through Aether’s tool proxy.
type	HttpType	yes	—	Transport discriminant; always http.
url	string	yes	—	Base URL of the streamable HTTP MCP server.

HttpType

Enum. One of:

• "http"

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"

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:

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

One of:

• StdioServerConfig
• HttpServerConfig
• SseServerConfig
• 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	—	—

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" }

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.
url	string | null	no	—	Base URL override for the provider’s API endpoint.

ReasoningEffort

Enum. One of:

• "low"
• "medium"
• "high"
• "xhigh"

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

SseServerConfig

Field	Type	Required	Default	Description
headers	Record<string, string>	no	{}	Extra HTTP headers sent with every request.
proxy	boolean	no	—	Expose this server’s tools through Aether’s tool proxy.
type	SseType	yes	—	Transport discriminant; always sse.
url	string	yes	—	Base URL of the Server-Sent Events MCP server.

SseType

Enum. One of:

• "sse"

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"

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