astra.yml Schema Reference

Complete field reference for every key in astra.yml. All fields are optional unless marked required. Fields not specified fall back to defaults.

settings

Field	Type	Default	Description
`defaultProvider`	string	`openai`	Provider used when agent doesn't specify one
`defaultModel`	string	`gpt-4o`	Model ID used when agent doesn't specify one
`maxContextTokens`	number	`128000`	Default max context window
`maxOutputTokens`	number	`4096`	Default max output tokens
`temperature`	number	`0.7`	Default sampling temperature (0–2)
`logLevel`	string	`info`	`debug` \| `info` \| `warn` \| `error`
`timezone`	string	`UTC`	IANA timezone (e.g. `America/New_York`)
`embeddingModel`	string	`text-embedding-3-small`	Embedding model for memory indexing

quotas

Field	Type	Default	Description
`tokens.maxPerHour`	number	`200000`	Max tokens per agent per hour
`tokens.maxPerDay`	number	`1000000`	Max tokens per agent per day
`cost.maxPerDay`	number	`10.00`	Max USD spend per agent per day
`spawn.maxConcurrent`	number	`5`	Max simultaneously running sub-agents
`spawn.maxDepth`	number	`2`	Max spawn nesting depth (max 3)

approval

Field	Type	Default	Description
`requireApproval`	array	`[]`	List of `{tool: name}` or `{agent: id}` rules
`timeoutMs`	number	`300000`	Milliseconds to wait for approval
`defaultOnTimeout`	string	`deny`	`deny` \| `allow`

selfHealing

Field	Type	Default	Description
`enabled`	boolean	`true`	Enable auto-restart on failure
`maxConsecutiveFailures`	number	`3`	Failures before agent is paused
`restartDelayMs`	number	`2000`	Initial restart backoff in ms
`compactionThreshold`	number	`0.85`	Context fill ratio to trigger compaction (0–1)

agents[*]

Field	Type	Required	Description
`id`	string	Yes	Unique agent identifier (kebab-case)
`displayName`	string	No	Human-readable name
`tier`	string	No	`free` \| `standard` \| `premium`
`model.provider`	string	Yes	Provider ID
`model.modelId`	string	Yes	Model identifier
`model.maxContextTokens`	number	No	Override context window
`model.maxOutputTokens`	number	No	Override max output tokens
`model.temperature`	number	No	Override temperature (0–2)
`systemPromptTemplate`	string	No	Handlebars template for system prompt
`skills`	string[]	No	Skill IDs to activate
`tools.allow`	string[]	No	Allowed tool names
`tools.deny`	string[]	No	Denied tool names (always wins)
`spawn.enabled`	boolean	No	Allow this agent to spawn sub-agents
`spawn.allowedTargets`	string[]	No	Agent IDs this agent can spawn
`spawn.maxDepth`	number	No	Max spawn depth override
`fileAccess.restricted`	boolean	No	Restrict file access to allowedPaths
`fileAccess.allowedPaths`	string[]	No	Allowed file system paths
`fallback.provider`	string	No	Fallback provider if primary fails
`fallback.modelId`	string	No	Fallback model ID

Full example

yaml

settings:
  defaultProvider: openai
  defaultModel: gpt-4o
  timezone: America/New_York

quotas:
  tokens:
    maxPerHour: 200000
    maxPerDay: 2000000
  cost:
    maxPerDay: 20.00

selfHealing:
  enabled: true
  maxConsecutiveFailures: 3
  compactionThreshold: 0.85

channels:
  telegram:
    enabled: true
    defaultAgent: assistant

agents:
  - id: assistant
    displayName: Astra Assistant
    tier: standard
    model:
      provider: openai
      modelId: gpt-4o
    systemPromptTemplate: |
      You are Astra. Today is {{date}}.
    skills: [git_ops, web_search]
    spawn:
      enabled: true
      allowedTargets: [researcher]
      maxDepth: 2

  - id: researcher
    model:
      provider: claude
      modelId: claude-opus-4-6
    skills: [web_research]
    spawn:
      enabled: false