Configuration Reference
Full annotated aegis-config.yaml with all supported keys, types, defaults, and descriptions.
Daemon Configuration
The AEGIS daemon is configured via a single YAML file, by default aegis-config.yaml in the working directory. Pass a custom path with --config:
aegis daemon start --config /etc/aegis/config.yamlConfig Discovery Order
The daemon searches for a config file in the following order. The first match wins:
--config <path>CLI flagAEGIS_CONFIG_PATHenvironment variable./aegis-config.yaml(working directory)~/.aegis/config.yaml/etc/aegis/config.yaml(Linux/macOS)
Credential Resolution
Any string value in the config file can use a credential prefix instead of a literal:
| Prefix | Resolution |
|---|---|
env:VAR_NAME | Read from the daemon process environment at startup. |
secret:path/to/secret | Resolved from OpenBao at runtime (requires spec.secrets.backend configured). |
| (literal) | Plaintext. Avoid for secrets. |
The recommended production pattern is secret: references for all API keys and credentials. Use env: as a fallback when OpenBao is not available.
Multi-Node Cluster Topology
AEGIS supports a distributed Controller-Worker topology for high availability and horizontal scaling. Nodes can be configured as controllers (scheduling and management), workers (agent execution), or hybrid nodes.
Key features of the cluster topology include:
- Distributed Scheduling: Controllers route agent executions to the most suitable available workers.
- Node Identity: Each node maintains a stable identity via a persistent Ed25519 keypair, used for secure attestation and SealNodeEnvelope signing.
- Secure Communication: Inter-node traffic is protected by mTLS and SEAL-derived security tokens.
- Seamless Scaling: New workers can be added to the cluster by pointing them at the controller endpoint and providing valid certificates.
Manifest Envelope
All aegis-config.yaml files use the Kubernetes-style manifest envelope:
apiVersion: 100monkeys.ai/v1
kind: NodeConfig
metadata:
name: "my-aegis-node" # required
version: "1.0.0" # optional
labels: # optional
environment: "production"
spec:
# All configuration sections documented below sit under spec:The sections documented below all belong under the top-level spec: key.
Full Annotated Configuration
apiVersion: 100monkeys.ai/v1
kind: NodeConfig
metadata:
name: "aegis-node"
spec:
# ─── Node Identity ────────────────────────────────────────────────────────────
node:
# Unique stable node identifier. UUID recommended. Required.
id: "env:AEGIS_NODE_ID"
# Node type. Options: edge | orchestrator | hybrid. Required.
type: orchestrator
# Geographic region, e.g. "us-east-1". Optional.
region: "us-east-1"
# Capability tags used to match agent manifest execution_targets. Optional.
tags:
- gpu
- high-memory
# Physical resources available on this node. Optional.
resources:
cpu_cores: 8
memory_gb: 32
disk_gb: 500
gpu: false
# ─── Image Tag ────────────────────────────────────────────────────────────────
# Docker image tag for all AEGIS-owned service containers.
# Written by `aegis init --tag <TAG>` and updated by `aegis update`.
# When absent, both commands default to the version of the aegis binary.
image_tag: "1.0.1-beta"
# ─── LLM Providers ────────────────────────────────────────────────────────────
# Array of LLM provider configurations. At least one entry is required.
llm_providers:
- name: openai-primary # Unique provider name on this node. Required.
type: openai # openai | anthropic | gemini | ollama | openai-compatible. Required.
endpoint: "https://api.openai.com/v1" # API endpoint URL. Required.
api_key: "env:OPENAI_API_KEY" # Supports env: and secret: prefixes.
enabled: true # Default: true
models: # Must have at least one entry. Required.
- alias: default # Alias referenced in agent manifests. Required.
model: gpt-4o # Provider-side model name. Required.
capabilities: # chat | embedding | reasoning | vision | code | image_generation. Required.
- chat
- code
- reasoning
context_window: 128000 # Max context window in tokens. Required.
cost_per_1k_tokens: 0.005 # Default: 0.0 (free/local)
- alias: fast
model: gpt-4o-mini
capabilities: [chat, code]
context_window: 128000
cost_per_1k_tokens: 0.00015
- name: anthropic-primary
type: anthropic
endpoint: "https://api.anthropic.com/v1"
api_key: "secret:aegis-system/llm/anthropic-api-key"
enabled: true
models:
- alias: smart
model: claude-sonnet-4-5
capabilities: [chat, code, reasoning]
context_window: 200000
cost_per_1k_tokens: 0.003
- name: ollama-local
type: ollama
endpoint: "http://localhost:11434"
enabled: true
models:
- alias: local
model: qwen2.5-coder:32b
capabilities: [chat, code]
context_window: 32000
cost_per_1k_tokens: 0.0
# ─── LLM Selection Strategy ───────────────────────────────────────────────────
# Optional. Controls how the orchestrator picks providers at runtime.
llm_selection:
# prefer-local | prefer-cloud | cost-optimized | latency-optimized
# Default: prefer-local
strategy: prefer-local
# Must name a provider in llm_providers. It does not choose a provider:
# each alias is resolved by strategy. Default: null.
default_provider: openai-primary
# Tried once after an alias's retries fail or a provider's time limit, for an alias naming no fallback_alias. Default: null.
fallback_provider: ollama-local
# Maximum retry attempts on LLM failure. Default: 3
max_retries: 3
# Delay between retries in milliseconds. Default: 1000
retry_delay_ms: 1000
# ─── Execution Limits ────────────────────────────────────────────────────────
# Optional. Protects list_executions from returning unbounded result sets. Defaults to 1000 when omitted.
max_execution_list_limit: 1000
# ─── Runtime ──────────────────────────────────────────────────────────────────
# Optional. Has safe defaults for Docker.
runtime:
# Path to the agent bootstrap script, relative to the orchestrator binary.
# Default: assets/bootstrap.py
bootstrap_script: "assets/bootstrap.py"
# Default isolation level for executions that do not specify one.
# Options: docker | podman | firecracker | inherit | process
# Default: inherit (uses the node's compiled-in default)
default_isolation: docker
# Container runtime socket path. Omit to use the platform default:
# Docker on Linux/macOS: /var/run/docker.sock
# Podman rootless: /run/user/<UID>/podman/podman.sock
# Podman system (root): /run/podman/podman.sock
# Can also be set via CONTAINER_HOST or DOCKER_HOST env vars (see below).
container_socket_path: "/var/run/docker.sock"
# Container network name for agent containers. Must be a separate network
# from the platform pods (aegis-network) to prevent container lifecycle
# churn from disrupting platform pod routing via Podman/netavark.
# Supports env: prefix. Example: "env:AEGIS_CONTAINER_NETWORK"
container_network_mode: "aegis-exec-network"
# URL that agent containers use to call back to the orchestrator.
# Must be reachable from inside containers, not from the host.
# Default: http://localhost:8088
orchestrator_url: "env:AEGIS_ORCHESTRATOR_URL"
# ── Container Host Environment Variables ──────────────────────────────────
# The container socket can also be configured via environment variables.
# These override container_socket_path when set:
#
# CONTAINER_HOST=unix:///run/user/1000/podman/podman.sock
# DOCKER_HOST=unix:///var/run/docker.sock
#
# CONTAINER_HOST takes precedence over DOCKER_HOST when both are set.
# Podman users should set CONTAINER_HOST to point to the Podman socket.
# ── NFS Storage Gateway (required when spec.storage.backend: seaweedfs) ───
# Hostname/IP of the NFS server. Must resolve from the HOST OS where the
# Docker daemon runs — NOT from inside agent containers.
# Supports env: prefix.
#
# Platform-specific values:
# WSL2 / Linux native: "127.0.0.1"
# Docker Desktop (Win/Mac): "host.docker.internal"
# Linux bridge network: "172.17.0.1" (Docker bridge gateway)
# Remote / VM host: "<physical host IP>"
nfs_server_host: "env:AEGIS_NFS_HOST"
# NFS server listen port. Default: 2049
nfs_port: 2049
# NFS mountd port. Default: 2049
nfs_mountport: 2049
# ─── Network ──────────────────────────────────────────────────────────────────
# Optional. Has safe defaults.
network:
# Bind address for all listeners. Default: 127.0.0.1 (loopback).
# Binding a non-loopback address requires either `tls` configured below or
# `allow_insecure_bind: true` (operator-acknowledged opt-out — see below).
bind_address: "127.0.0.1"
# HTTP REST API port. Default: 8088
port: 8088
# gRPC API port (inner-loop transport, Temporal workers). Default: 50051
grpc_port: 50051
# WebSocket URL for edge-node → orchestrator connection. Omit on orchestrator nodes.
orchestrator_endpoint: null
# Health check ping interval in seconds. Default: 30
heartbeat_interval_seconds: 30
# Optional TLS. Omit for plaintext (dev only; never in production).
tls:
cert_path: "/etc/aegis/tls/server.crt"
key_path: "/etc/aegis/tls/server.key"
ca_path: null # Optional CA certificate path
# Operator-acknowledged opt-out of the non-loopback-without-TLS startup gate.
# Default: false (fail-closed — pod refuses to start with a non-loopback bind
# and no TLS).
#
# Set true ONLY when TLS is terminated UPSTREAM of this pod by a
# trusted-network ingress (e.g. Caddy in the same Podman pod-network) AND the
# bound endpoint is reachable only from inside that trusted network. The
# validator emits a WARN log on every boot when the override is engaged so the
# decision is visible in startup logs and audit trails. NEVER set this on a
# publicly-exposed host — every external request would transit cleartext.
allow_insecure_bind: false
# ─── Cluster ──────────────────────────────────────────────────────────────────
# Optional. Configures the node's role in the multi-node cluster topology.
cluster:
# Enable cluster mode. Default: false.
enabled: true
# Node role in cluster. Options: controller | worker | hybrid. Default: hybrid.
# - controller: Manages routing and registration; does not run executions.
# - worker: Runs agent executions; does not perform routing decisions.
# - hybrid: Both controller and worker duties (default).
role: worker
# Controller settings (required for workers)
controller:
# gRPC endpoint of the controller node.
endpoint: "grpc://aegis-controller:50056"
# Bootstrap token for initial attestation (Step 0).
token: "env:AEGIS_CLUSTER_TOKEN"
# Port for NodeClusterService (controllers/hybrids). Default: 50056.
cluster_grpc_port: 50056
# Static list of peer controller addresses. Default: [].
peers: []
# Path to the persistent Ed25519 keypair file for node identity.
# Generated automatically on first startup if missing.
node_keypair_path: "/etc/aegis/node_keypair.pem"
# Interval in seconds for worker heartbeats to the controller. Default: 30.
heartbeat_interval_secs: 30
# Re-attest this many seconds before the security token expires. Default: 120.
token_refresh_margin_secs: 120
# TLS configuration for secure inter-node cluster communication (mTLS).
tls:
enabled: true
cert_path: "/etc/aegis/certs/node.crt"
key_path: "/etc/aegis/certs/node.key"
ca_cert: "/etc/aegis/certs/ca.crt"
# ─── Storage ──────────────────────────────────────────────────────────────────
# Optional. Defaults to local_host backend.
storage:
# Storage backend. Options: seaweedfs | local_host. Default: local_host
backend: seaweedfs
# Gracefully fall back to local storage when SeaweedFS is unreachable.
# Default: true
fallback_to_local: true
# NFS Server Gateway listen port. Default: 2049
nfs_port: 2049
# SeaweedFS backend config. Required when backend: seaweedfs.
seaweedfs:
# SeaweedFS Filer endpoint.
# Default: http://localhost:8888
filer_url: "http://localhost:8888"
# Host filesystem mount point.
# Default: /var/lib/aegis/storage
mount_point: "/var/lib/aegis/storage"
# Default TTL for ephemeral volumes in hours. Default: 24
default_ttl_hours: 24
# Default per-volume size quota in MB. Default: 1000
default_size_limit_mb: 1000
# Hard ceiling on any single volume size in MB. Default: 10000
max_size_limit_mb: 10000
# GC interval for expired volumes in minutes. Default: 60
gc_interval_minutes: 60
# Optional S3 gateway endpoint (e.g., for direct object uploads).
s3_endpoint: null
# S3 gateway region. Default: us-east-1
s3_region: "us-east-1"
# Local storage config. Used when backend: local_host, or as the fallback target.
local_host:
# Base directory for local volume storage.
# Default: /var/lib/aegis/local-volumes
base_path: "/var/lib/aegis/local-volumes"
# Default TTL for ephemeral volumes in hours. Default: 24
default_ttl_hours: 24
# Default per-volume size quota in MB. Default: 1000
default_size_limit_mb: 1000
# Hard ceiling on any single volume size in MB. Default: 10000
max_size_limit_mb: 10000
# ── FUSE Daemon (rootless Podman deployments) ──────────────────────────────
# When set, the orchestrator uses the host-side FUSE daemon for agent
# container volume mounts instead of NFS. Required for rootless Podman.
# Omit both fields to use NFS (default for rootful Docker).
# Host directory under which per-volume FUSE mountpoints are created.
# Default: /tmp/aegis-fuse
fuse_mount_prefix: "/tmp/aegis-fuse"
# Address of the external FUSE daemon's FuseMountService gRPC endpoint.
# This is the gRPC service exposed by the host-side FUSE daemon process,
# not the internal FSAL (filesystem abstraction) service.
# When set, enables FUSE transport for agent workspace mounts.
# When absent, the orchestrator falls back to in-process FUSE, which requires
# the orchestrator itself to run on the host with /dev/fuse access (not
# suitable for rootless Podman deployments).
# Default: null (in-process FUSE / NFS mode)
fuse_daemon_address: "127.0.0.1:50053"
# ─── Deploy Built-In Templates ───────────────────────────────────────────────
# Deploy vendored built-in agent and workflow templates on startup.
# Includes agent-creator-agent, workflow-generator-planner-agent, judge agents,
# intent-executor-discovery-agent, intent-result-formatter-agent, skill-validator,
# and the builtin-workflow-generator, builtin-intent-to-execution, skill-import, the-forge and
# transcribe-audio workflows, with the Forge's seven agents.
# Required for aegis.agent.generate, aegis.workflow.generate, and aegis.execute.intent to function.
# Default: false
deploy_builtins: false
# ─── Force Deploy Built-In Templates ─────────────────────────────────────────
# Force re-registration of all built-in agents and workflows on startup, even if
# already registered. Use after a platform upgrade when built-in agent UUIDs or
# definitions have changed and stale registrations need to be flushed.
# Accepts: "true" | "false" | "env:VAR_NAME". Optional. Default: disabled.
force_deploy_builtins: "false"
# ─── MCP Tool Servers ─────────────────────────────────────────────────────────
# External MCP server processes. Optional array.
mcp_servers:
- name: web-search # Unique server name on this node. Required.
enabled: true # Default: true
# Executable path (absolute or relative to /usr/local/bin). Required.
executable: "node"
# Command-line arguments. Default: []
args:
- "/opt/aegis-tools/web-search/index.js"
# Tool capabilities this server provides (used for routing). Default: []
capabilities:
- web.search
- web.fetch
# API keys and tokens — resolved via env: or secret: prefixes.
# Values are injected as environment variables into the server process.
credentials:
SEARCH_API_KEY: "secret:aegis-system/tools/search-api-key"
# Non-secret environment variables for the server process. Default: {}
environment:
LOG_LEVEL: "info"
# Health check configuration.
health_check:
interval_seconds: 60 # Default: 60
timeout_seconds: 5 # Default: 5
method: "tools/list" # MCP method used for health check. Default: tools/list
# Resource limits for the server process.
resource_limits:
cpu_millicores: 1000 # 1000 = 1 CPU core
memory_mb: 512
# ─── SEAL (Signed Envelope Attestation Layer) ────────────────────────────────────
# Optional. Required in production to enable cryptographic agent authorization.
seal:
# RSA private key PEM used to sign SecurityToken JWTs issued at attestation.
private_key_path: "/etc/aegis/seal/private.pem"
# RSA public key PEM used to verify SecurityToken JWTs on tool calls.
public_key_path: "/etc/aegis/seal/public.pem"
# JWT iss claim. Default: aegis-orchestrator
issuer: "aegis-orchestrator"
# JWT aud claim values. Default: [aegis-agents]
audiences:
- "aegis-agents"
# SecurityToken lifetime in seconds. Default: 3600 (1 hour)
token_ttl_seconds: 3600
# ─── Security Contexts ────────────────────────────────────────────────────────
# Named permission boundaries controlling what tools agents may invoke.
# Referenced by name in agent manifests and in spec.iam ZaruTier mappings.
security_contexts:
- name: coder-default
description: "Standard coder context — filesystem + commands + safe package registries"
capabilities:
- tool_pattern: "fs.*" # ← tool_pattern, not tool
path_allowlist:
- /workspace
- /agent
- tool_pattern: "cmd.run"
subcommand_allowlist:
git: [clone, add, commit, push, pull, status, diff, stash]
cargo: [build, test, fmt, clippy, check, run]
npm: [install, run, test, build, ci]
python: ["-m"]
- tool_pattern: "web.fetch"
domain_allowlist:
- pypi.org
- crates.io
- npmjs.com
rate_limit:
calls: 30 # ← object with calls + per_seconds, not "30/minute"
per_seconds: 60
# Explicit deny list — overrides any matching capability above.
deny_list: []
- name: zaru-free
description: "Public consumer tier. Curated safe tools including workspace volumes, git repositories, and saved scripts. Rate-limited, limited persistent storage. 1 git binding, 5 saved scripts."
capabilities:
- tool_pattern: "web.search"
- tool_pattern: "web.fetch"
- tool_pattern: "mail.list"
- tool_pattern: "mail.read"
- tool_pattern: "mail.attachment"
- tool_pattern: "mail.label"
- tool_pattern: "mail.draft"
- tool_pattern: "mail.send"
- tool_pattern: "mail.reply"
- tool_pattern: "mail.delete"
- tool_pattern: "mail.archive"
- tool_pattern: "mail.forward"
- tool_pattern: "calendar.calendars"
- tool_pattern: "calendar.list"
- tool_pattern: "calendar.read"
- tool_pattern: "calendar.create"
- tool_pattern: "calendar.update"
- tool_pattern: "calendar.delete"
- tool_pattern: "calendar.respond"
- tool_pattern: "aegis.schema.get"
- tool_pattern: "aegis.schema.validate"
- tool_pattern: "aegis.agent.list"
- tool_pattern: "aegis.agent.search"
- tool_pattern: "aegis.agent.export"
- tool_pattern: "aegis.agent.generate"
- tool_pattern: "aegis.workflow.list"
- tool_pattern: "aegis.workflow.search"
- tool_pattern: "aegis.workflow.export"
- tool_pattern: "aegis.workflow.run"
- tool_pattern: "aegis.workflow.generate"
- tool_pattern: "aegis.task.execute"
- tool_pattern: "aegis.task.status"
- tool_pattern: "aegis.task.list"
- tool_pattern: "aegis.task.wait"
- tool_pattern: "aegis.task.cancel"
- tool_pattern: "aegis.task.logs"
- tool_pattern: "aegis.approval.status"
- tool_pattern: "aegis.goal.create"
- tool_pattern: "aegis.goal.evaluate"
- tool_pattern: "aegis.goal.status"
- tool_pattern: "aegis.goal.cancel"
- tool_pattern: "aegis.document.render"
# The remote tool servers, one pattern each: listed to a person's agent
# only when they hold a connection granted to it, and only by the exact
# names the agent declares. carbon-forge was formerly named nuclear-notes;
# the former name is still accepted for at least 90 days from 21 October
# 2026, and a call under it is matched by the carbon-forge pattern.
- tool_pattern: "carbon-forge.*"
- tool_pattern: "github.*"
- tool_pattern: "aegis.execute.intent"
- tool_pattern: "aegis.execute.status"
- tool_pattern: "aegis.execute.wait"
- tool_pattern: "aegis.execution.file"
- tool_pattern: "aegis.file.list"
- tool_pattern: "aegis.file.read"
- tool_pattern: "aegis.file.write"
- tool_pattern: "aegis.file.delete"
- tool_pattern: "aegis.file.mkdir"
- tool_pattern: "aegis.volume.create"
- tool_pattern: "aegis.volume.list"
- tool_pattern: "aegis.volume.delete"
- tool_pattern: "aegis.volume.quota"
- tool_pattern: "aegis.git.clone"
- tool_pattern: "aegis.git.list"
- tool_pattern: "aegis.git.status"
- tool_pattern: "aegis.git.refresh"
- tool_pattern: "aegis.git.delete"
- tool_pattern: "aegis.git.commit"
- tool_pattern: "aegis.git.push"
- tool_pattern: "aegis.git.diff"
- tool_pattern: "aegis.workflow.logs"
- tool_pattern: "aegis.workflow.cancel"
- tool_pattern: "aegis.workflow.wait"
- tool_pattern: "aegis.workflow.signal"
- tool_pattern: "aegis.workflow.create"
- tool_pattern: "aegis.workflow.update"
- tool_pattern: "aegis.agent.logs"
- tool_pattern: "aegis.agent.wait"
- tool_pattern: "aegis.tools.list"
- tool_pattern: "aegis.tools.search"
- tool_pattern: "aegis.script.save"
- tool_pattern: "aegis.script.list"
- tool_pattern: "aegis.script.get"
- tool_pattern: "aegis.script.update"
- tool_pattern: "aegis.script.delete"
- tool_pattern: "aegis.runtime.list"
# A person's schedules: runs started later or on a recurrence, as that
# person. Never admitted by aegis-system-agent-runtime, so a run cannot
# schedule runs.
- tool_pattern: "aegis.schedule.create"
- tool_pattern: "aegis.schedule.list"
- tool_pattern: "aegis.schedule.get"
- tool_pattern: "aegis.schedule.update"
- tool_pattern: "aegis.schedule.pause"
- tool_pattern: "aegis.schedule.resume"
- tool_pattern: "aegis.schedule.delete"
- tool_pattern: "aegis.schedule.runs"
deny_list: []
- name: zaru-pro
description: "Individual paid tier. Full consumer tool surface including workflow signals, git repositories (auto-refresh, sparse checkout), canvas workspaces, and saved scripts."
capabilities:
- tool_pattern: "web.search"
- tool_pattern: "web.fetch"
- tool_pattern: "mail.list"
- tool_pattern: "mail.read"
- tool_pattern: "mail.attachment"
- tool_pattern: "mail.label"
- tool_pattern: "mail.draft"
- tool_pattern: "mail.send"
- tool_pattern: "mail.reply"
- tool_pattern: "mail.delete"
- tool_pattern: "mail.archive"
- tool_pattern: "mail.forward"
- tool_pattern: "calendar.calendars"
- tool_pattern: "calendar.list"
- tool_pattern: "calendar.read"
- tool_pattern: "calendar.create"
- tool_pattern: "calendar.update"
- tool_pattern: "calendar.delete"
- tool_pattern: "calendar.respond"
- tool_pattern: "aegis.schema.get"
- tool_pattern: "aegis.schema.validate"
- tool_pattern: "aegis.agent.list"
- tool_pattern: "aegis.agent.search"
- tool_pattern: "aegis.agent.export"
- tool_pattern: "aegis.agent.generate"
- tool_pattern: "aegis.workflow.list"
- tool_pattern: "aegis.workflow.search"
- tool_pattern: "aegis.workflow.export"
- tool_pattern: "aegis.workflow.run"
- tool_pattern: "aegis.workflow.generate"
- tool_pattern: "aegis.task.execute"
- tool_pattern: "aegis.task.status"
- tool_pattern: "aegis.task.list"
- tool_pattern: "aegis.task.wait"
- tool_pattern: "aegis.task.cancel"
- tool_pattern: "aegis.task.logs"
- tool_pattern: "aegis.approval.status"
- tool_pattern: "aegis.goal.create"
- tool_pattern: "aegis.goal.evaluate"
- tool_pattern: "aegis.goal.status"
- tool_pattern: "aegis.goal.cancel"
- tool_pattern: "aegis.document.render"
# The remote tool servers, one pattern each: listed to a person's agent
# only when they hold a connection granted to it, and only by the exact
# names the agent declares.
- tool_pattern: "carbon-forge.*"
- tool_pattern: "github.*"
- tool_pattern: "aegis.execute.intent"
- tool_pattern: "aegis.execute.status"
- tool_pattern: "aegis.execute.wait"
- tool_pattern: "aegis.execution.file"
- tool_pattern: "aegis.file.list"
- tool_pattern: "aegis.file.read"
- tool_pattern: "aegis.file.write"
- tool_pattern: "aegis.file.delete"
- tool_pattern: "aegis.file.mkdir"
- tool_pattern: "aegis.volume.create"
- tool_pattern: "aegis.volume.list"
- tool_pattern: "aegis.volume.delete"
- tool_pattern: "aegis.volume.quota"
- tool_pattern: "aegis.git.clone"
- tool_pattern: "aegis.git.list"
- tool_pattern: "aegis.git.status"
- tool_pattern: "aegis.git.refresh"
- tool_pattern: "aegis.git.delete"
- tool_pattern: "aegis.git.commit"
- tool_pattern: "aegis.git.push"
- tool_pattern: "aegis.git.diff"
- tool_pattern: "aegis.workflow.logs"
- tool_pattern: "aegis.workflow.cancel"
- tool_pattern: "aegis.workflow.wait"
- tool_pattern: "aegis.workflow.signal"
- tool_pattern: "aegis.workflow.create"
- tool_pattern: "aegis.workflow.update"
- tool_pattern: "aegis.agent.logs"
- tool_pattern: "aegis.agent.wait"
- tool_pattern: "aegis.tools.list"
- tool_pattern: "aegis.tools.search"
- tool_pattern: "aegis.script.save"
- tool_pattern: "aegis.script.list"
- tool_pattern: "aegis.script.get"
- tool_pattern: "aegis.script.update"
- tool_pattern: "aegis.script.delete"
- tool_pattern: "aegis.runtime.list"
# A person's schedules: runs started later or on a recurrence, as that
# person. Never admitted by aegis-system-agent-runtime, so a run cannot
# schedule runs.
- tool_pattern: "aegis.schedule.create"
- tool_pattern: "aegis.schedule.list"
- tool_pattern: "aegis.schedule.get"
- tool_pattern: "aegis.schedule.update"
- tool_pattern: "aegis.schedule.pause"
- tool_pattern: "aegis.schedule.resume"
- tool_pattern: "aegis.schedule.delete"
- tool_pattern: "aegis.schedule.runs"
deny_list: []
# zaru-business and zaru-enterprise admit the same tools as zaru-pro.
# aegis-system-agent-runtime runs the orchestrator's own sub-executions (agent and
# workflow generation, aegis.task.execute, execute-mode pipelines) and scheduled runs.
# The orchestrator reads it from security_contexts like every other context, so
# declare it here. The tools below are the ones it admits on a reference deployment.
- name: aegis-system-agent-runtime
description: "Execution context for orchestrator-spawned agent containers. Grants filesystem access scoped to /workspace, shell execution, web access, and the full aegis platform tool surface including agent and workflow authoring tools."
capabilities:
- tool_pattern: "fs.*"
path_allowlist:
- /workspace
- tool_pattern: "cmd.run"
- tool_pattern: "web.search"
- tool_pattern: "web.fetch"
- tool_pattern: "mail.list"
- tool_pattern: "mail.read"
- tool_pattern: "mail.attachment"
- tool_pattern: "mail.label"
- tool_pattern: "mail.draft"
- tool_pattern: "mail.send"
- tool_pattern: "mail.reply"
- tool_pattern: "mail.delete"
- tool_pattern: "mail.archive"
- tool_pattern: "mail.forward"
- tool_pattern: "calendar.calendars"
- tool_pattern: "calendar.list"
- tool_pattern: "calendar.read"
- tool_pattern: "calendar.create"
- tool_pattern: "calendar.update"
- tool_pattern: "calendar.delete"
- tool_pattern: "calendar.respond"
- tool_pattern: "aegis.schema.get"
- tool_pattern: "aegis.schema.validate"
- tool_pattern: "aegis.agent.create"
- tool_pattern: "aegis.agent.update"
- tool_pattern: "aegis.agent.list"
- tool_pattern: "aegis.agent.search"
- tool_pattern: "aegis.agent.generate"
- tool_pattern: "aegis.agent.export"
- tool_pattern: "aegis.agent.logs"
- tool_pattern: "aegis.agent.wait"
- tool_pattern: "aegis.workflow.list"
- tool_pattern: "aegis.workflow.search"
- tool_pattern: "aegis.workflow.export"
- tool_pattern: "aegis.workflow.logs"
- tool_pattern: "aegis.workflow.cancel"
- tool_pattern: "aegis.workflow.wait"
- tool_pattern: "aegis.task.execute"
- tool_pattern: "aegis.task.status"
- tool_pattern: "aegis.task.list"
- tool_pattern: "aegis.task.wait"
- tool_pattern: "aegis.task.cancel"
- tool_pattern: "aegis.task.logs"
- tool_pattern: "aegis.approval.status"
- tool_pattern: "aegis.execute.intent"
- tool_pattern: "aegis.execute.status"
- tool_pattern: "aegis.execute.wait"
- tool_pattern: "aegis.execution.file"
- tool_pattern: "aegis.file.list"
- tool_pattern: "aegis.file.read"
- tool_pattern: "aegis.file.write"
- tool_pattern: "aegis.file.delete"
- tool_pattern: "aegis.file.mkdir"
- tool_pattern: "aegis.volume.create"
- tool_pattern: "aegis.volume.list"
- tool_pattern: "aegis.volume.delete"
- tool_pattern: "aegis.volume.quota"
- tool_pattern: "aegis.git.clone"
- tool_pattern: "aegis.git.list"
- tool_pattern: "aegis.git.status"
- tool_pattern: "aegis.git.refresh"
- tool_pattern: "aegis.git.delete"
- tool_pattern: "aegis.git.commit"
- tool_pattern: "aegis.git.push"
- tool_pattern: "aegis.git.diff"
- tool_pattern: "aegis.tools.list"
- tool_pattern: "aegis.tools.search"
- tool_pattern: "aegis.script.save"
- tool_pattern: "aegis.script.list"
- tool_pattern: "aegis.script.get"
- tool_pattern: "aegis.script.update"
- tool_pattern: "aegis.script.delete"
- tool_pattern: "aegis.runtime.list"
- tool_pattern: "aegis.attachment.read"
# A remote tool server's tools, reached only through a connection the
# person chose for the run.
- tool_pattern: "carbon-forge.*"
deny_list: []
- name: aegis-system-operator
description: "Platform operator — all safe tools plus destructive and orchestrator commands"
capabilities:
- tool_pattern: "fs.*"
path_allowlist:
- /workspace
- /agent
- /shared
- tool_pattern: "cmd.run"
subcommand_allowlist:
git: [clone, add, commit, push, pull, status, diff, stash]
cargo: [build, test, fmt, clippy, check, run]
npm: [install, run, test, build, ci]
python: ["-m"]
- tool_pattern: "web.*"
# Destructive commands (operator-only)
- tool_pattern: "aegis.agent.delete"
- tool_pattern: "aegis.workflow.delete"
- tool_pattern: "aegis.task.remove"
# Orchestrator commands (operator-only)
- tool_pattern: "aegis.system.info"
- tool_pattern: "aegis.system.config"
deny_list: []
# ─── Builtin Dispatchers ──────────────────────────────────────────────────────
# Configuration for the in-process Dispatch Protocol handler.
# The cmd dispatcher is NOT an MCP server — it runs subprocesses inside agent
# containers via the bidirectional bootstrap channel.
builtin_dispatchers:
cmd:
# Enable cmd.run dispatch. Default: true
enabled: true
# Default per-subprocess timeout in seconds. Default: 60
default_timeout_secs: 60
# Ceiling timeout an agent manifest may request. Default: 300
max_timeout_ceiling_secs: 300
# Maximum stdout + stderr captured per subprocess in bytes. Default: 524288 (512 KB)
max_output_bytes: 524288
# Maximum concurrent subprocesses per execution. Default: 1
max_concurrent_per_execution: 1
# Environment variables that must never be forwarded to agent subprocesses.
global_env_denylist:
- AEGIS_TOKEN
- OPENAI_API_KEY
- ANTHROPIC_API_KEY
- SEAL_PRIVATE_KEY
- AWS_SECRET_ACCESS_KEY
- GOOGLE_API_KEY
# ─── IAM (OIDC) ───────────────────────────────────────────────────────────────
# Optional. Omit to disable JWT validation (dev only; never in production).
# Configures Keycloak as the trusted OIDC issuer for all
# human and service-account identities.
iam:
# Array of Keycloak realms trusted by this node.
realms:
- slug: "aegis-system" # Realm name matching Keycloak config. Required.
issuer_url: "https://auth.myzaru.com/realms/aegis-system" # OIDC issuer URL. Required.
jwks_uri: "https://auth.myzaru.com/realms/aegis-system/protocol/openid-connect/certs" # Required.
audience: "aegis-orchestrator" # Expected aud claim. Required.
kind: system # system | consumer | tenant. Required.
- slug: "zaru-consumer"
issuer_url: "https://auth.myzaru.com/realms/zaru-consumer"
jwks_uri: "https://auth.myzaru.com/realms/zaru-consumer/protocol/openid-connect/certs"
audience: "aegis-orchestrator"
kind: consumer
# JWKS key refresh interval in seconds. Supports live key rotation.
# Default: 300
jwks_cache_ttl_seconds: 300
# Custom claim names injected by Keycloak attribute mappers.
claims:
zaru_tier: "zaru_tier" # Claim carrying ZaruTier (Free | Pro | Business | Enterprise)
aegis_role: "aegis_role" # Claim carrying AegisRole in aegis-system realm
tenant_id: "tenant_id" # Claim carrying per-user tenant slug (u-{uuid}) for consumer users
# Operator escalation over MCP. Omit for these defaults.
operator_escalation:
ttl_seconds: 1800 # Seconds an escalation lasts from its redemption
code_validity_seconds: 300 # Seconds a generated code stays redeemable
code_max_failed_attempts: 5 # Failed redemptions that invalidate the user's live codes
# ─── Goals ───────────────────────────────────────────────────────────────────
# Optional. A goal's bounds and the thresholds its judge's verdict is read by.
# Omit for these defaults.
goals:
max_continuations: 3 # Continuation rounds granted at most per goal
lifetime_seconds: 1800 # Seconds a goal stays open from its creation
met_min_score: 0.85 # A verdict meets the goal at this score or above
met_min_confidence: 0.75 # ...and at this confidence or above
cannot_be_met_max_feasibility: 0.2 # Not met, feasibility at or below this: cannot be met
# ─── gRPC Auth ────────────────────────────────────────────────────────────────
# Optional. Controls IAM/OIDC JWT enforcement on the gRPC endpoint.
# Requires spec.iam to be configured.
grpc_auth:
# Enable JWT validation on all gRPC methods. Default: true
enabled: true
# gRPC method full paths exempt from auth.
# The inner-loop bootstrap channel must always be exempt.
exempt_methods:
- "/aegis.v1.InnerLoop/Generate"
# ─── Secrets (OpenBao) ────────────────────────────────────────────────────────
# Optional. Omit to rely solely on env: references.
# Follows the Keymaster Pattern: only the orchestrator accesses
# OpenBao — agents never receive secret backend credentials directly.
secrets:
backend:
# OpenBao server address.
address: "https://openbao.internal:8200"
# Authentication method. Currently only approle is supported.
auth_method: "approle"
approle:
# AppRole Role ID — public, can be committed to config.
role_id: "env:OPENBAO_ROLE_ID"
# Name of the environment variable containing the AppRole Secret ID.
# The Secret ID itself must never be committed to config files.
secret_id_env_var: "OPENBAO_SECRET_ID"
# OpenBao namespace for multi-tenancy. Maps 1:1 to a Keycloak realm.
namespace: "aegis-system"
# Optional mTLS to OpenBao.
tls:
ca_cert: "/etc/aegis/openbao-ca.pem"
client_cert: null # Optional mTLS client cert
client_key: null # Optional mTLS client key
# ─── Database ─────────────────────────────────────────────────────────────────
# Optional. If omitted the daemon uses InMemory repositories (dev only).
database:
# PostgreSQL connection URL. Supports env: and secret: prefixes.
url: "env:AEGIS_DATABASE_URL"
# Maximum connections in the pool. Default: 5
max_connections: 10
# Connection timeout in seconds. Default: 5
connect_timeout_seconds: 5
# ─── Temporal ─────────────────────────────────────────────────────────────────
# Optional. If omitted workflow orchestration is unavailable.
temporal:
# Temporal gRPC server address. Default: temporal:7233
address: "temporal:7233"
# HTTP endpoint for Temporal worker callbacks. Default: http://localhost:3000
worker_http_endpoint: "http://aegis-runtime:3000"
# Shared secret for authenticating worker callbacks. Supports env:.
worker_secret: "env:TEMPORAL_WORKER_SECRET"
# Temporal namespace. Default: default
namespace: "default"
# Temporal task queue. Default: aegis-agents
task_queue: "aegis-agents"
# Maximum number of connection retries when establishing the Temporal client.
# If omitted, a default of 30 retries is used.
max_connection_retries: 30
# ─── Cortex ───────────────────────────────────────────────────────────────────
# Optional. If omitted or grpc_url is null the daemon runs in memoryless mode.
# When configured, discovery (aegis.agent.search, aegis.workflow.search) is
# available automatically — no separate discovery section is required.
cortex:
# Cortex gRPC service URL. Supports env:.
grpc_url: "env:CORTEX_GRPC_URL"
# API key for 100monkeys hosted Cortex (Zaru SaaS). Supports env: and secret:.
# Omit for local or open cortex deployments (connects without authentication).
api_key: "env:CORTEX_API_KEY"
# ─── Billing ──────────────────────────────────────────────────────────────────
# Optional. Omit for self-hosted deployments where billing is not required.
# When stripe_secret_key is absent, all /v1/billing/* endpoints return
# 501 Not Implemented.
# Note: STRIPE_PUBLISHABLE_KEY is a frontend-only env var passed directly to
# the zaru-client container — it is NOT part of NodeConfig and does not belong here.
# Pricing is dynamic — prices are fetched live from Stripe via GET /v1/billing/prices.
billing:
# Stripe API secret key (server-side only). Supports env: and secret: prefixes.
stripe_secret_key: "env:STRIPE_SECRET_KEY"
# Webhook signing secret for verifying Stripe webhook event signatures.
stripe_webhook_secret: "env:STRIPE_WEBHOOK_SECRET"
# ─── External SEAL Tooling Gateway ─────────────────────────────────
# Optional. Omit to keep external tool routing disabled.
seal_gateway:
# gRPC endpoint URL for aegis-seal-gateway.
url: "http://aegis-seal-gateway:50055"
# ─── Observability ────────────────────────────────────────────────────────────
# Optional.
observability:
logging:
# Log level: error | warn | info | debug | trace. Default: info
level: info
# Output format: json | text. Default: json
format: json
# Log file path. Omit to write to stdout.
file: null
# ── OTLP Log Export ──────────────────────────────────────────────
# Set to ship logs to Grafana Cloud, Datadog, or a self-hosted OTEL Collector.
# Omit (or null) to disable. Override with AEGIS_OTLP_ENDPOINT.
# otlp_endpoint: "http://otel-collector:4317" # gRPC
# otlp_endpoint: "https://otlp-gateway.grafana.net/v1/logs" # HTTP
# otlp_protocol: grpc # grpc (default) | http. Override: AEGIS_OTLP_PROTOCOL
# otlp_headers: # auth headers; values support env: / secret:
# Authorization: "env:OTLP_AUTH_TOKEN"
# otlp_min_level: info # min level exported. Override: AEGIS_OTLP_LOG_LEVEL
# otlp_service_name: aegis-orchestrator # service.name attr. Override: AEGIS_OTLP_SERVICE_NAME
# batch:
# max_queue_size: 2048
# scheduled_delay_ms: 5000
# max_export_batch_size: 512
# export_timeout_ms: 10000
# tls:
# verify: true
# ca_cert_path: null
metrics:
# Enable Prometheus metrics exposition. Default: true
enabled: true
# Prometheus metrics exposition port. Default: 9091
port: 9091
# HTTP path for scraping. Default: /metrics
path: "/metrics"
tracing:
# Enable distributed tracing via OpenTelemetry. Default: false
enabled: falseSection Reference
spec.node
Required. Identifies this node within the AEGIS cluster.
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | ✅ | — | Unique stable node identifier. UUID recommended. Fails validation if empty. |
type | enum | ✅ | — | edge | orchestrator | hybrid |
region | string | ❌ | null | Geographic region (e.g., "us-east-1") |
tags | string[] | ❌ | [] | Capability tags matched against execution_targets in agent manifests |
resources.cpu_cores | u32 | ❌ | — | Available CPU cores |
resources.memory_gb | u32 | ❌ | — | Available RAM in GB |
resources.disk_gb | u32 | ❌ | — | Available disk in GB |
resources.gpu | bool | ❌ | false | GPU available |
spec.image_tag
Optional. Docker image tag for AEGIS-owned services.
| Key | Type | Default | Description |
|---|---|---|---|
image_tag | string | <binary version> | Tag applied to all AEGIS-owned Docker images. Written by aegis init --tag and updated by aegis update. When absent, defaults to the version string embedded in the aegis binary. |
spec.llm_providers
Required array. At least one entry with at least one model is required.
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | ✅ | — | Unique provider name |
type | enum | ✅ | — | openai | anthropic | gemini | ollama | openai-compatible |
endpoint | string | ✅ | — | API endpoint URL |
api_key | string | ❌ | null | API key. Supports env: and secret:. |
headers | map | ❌ | null | Header name to value, sent on every request beside Authorization (openai and openai-compatible only). A header named authorization is refused. See Request Headers. |
enabled | bool | ❌ | true | Whether this provider is active |
models[].alias | string | ✅ | — | Alias referenced in agent manifests |
models[].model | string | ✅ | — | Provider-side model identifier |
models[].capabilities | string[] | ✅ | — | chat | embedding | reasoning | vision | code | image_generation |
models[].context_window | u32 | ✅ | — | Max context window in tokens |
models[].cost_per_1k_tokens | f64 | ❌ | 0.0 | Cost per 1K tokens (0.0 for free/local) |
models[].fallback_alias | string | ❌ | — | Another alias, tried once after the provider's time limit on this alias's model, with that alias's options. Must be mapped by an enabled provider, must not be this alias, and must not itself name a fallback. See Fallback Alias |
spec.llm_selection
Optional. Controls runtime provider selection strategy.
| Key | Type | Default | Description |
|---|---|---|---|
strategy | enum | prefer-local | prefer-local | prefer-cloud | cost-optimized | latency-optimized |
default_provider | string | null | Must name a provider in spec.llm_providers, or the configuration is refused. It does not choose a provider: each alias is resolved by strategy |
fallback_provider | string | null | Provider tried once, on its first model and with the caller's options, after an alias's last failed retry or after a provider's time limit (HTTP 408 with code 3046), for an alias whose model entry names no fallback_alias. Must name a provider in spec.llm_providers, or the configuration is refused |
max_retries | u32 | 3 | Maximum retry attempts on LLM failure. An answer with no text and no tool call counts as a failed attempt. |
retry_delay_ms | u64 | 1000 | Delay between retries in milliseconds |
llm_overall_timeout_secs | u64 | 30 | Wall-clock budget in seconds for one chat call on an alias, such as each model call of an agent's inner loop, covering every retry and the one fallback attempt, on the alias's fallback_alias or on fallback_provider; when it elapses the call fails with upstream timeout after <n>s. A single-prompt generation is not bounded by it, only each of its attempts by llm_attempt_timeout_secs |
llm_attempt_timeout_secs | u64 | absent (no bound) | Bound in seconds on one attempt of a model call. An attempt with no answer when it elapses is abandoned and retried like an HTTP 408, counted against max_retries and inside llm_overall_timeout_secs. Must be positive and not above llm_overall_timeout_secs. A provider's HTTP 400 is never retried: the call fails at once with the provider's message |
spec.runtime
Optional. Controls how agent containers are launched.
| Key | Type | Default | Description |
|---|---|---|---|
bootstrap_script | string | assets/bootstrap.py | Path to bootstrap script relative to orchestrator binary |
default_isolation | enum | inherit | docker | podman | firecracker | inherit | process |
container_socket_path | string | (platform default) | Container runtime socket path. Docker: /var/run/docker.sock. Podman rootless: /run/user/<UID>/podman/podman.sock. Podman system: /run/podman/podman.sock. Can be overridden via CONTAINER_HOST or DOCKER_HOST env vars. |
container_network_mode | string | null | Container network name for agent containers |
orchestrator_url | string | http://localhost:8088 | Callback URL reachable from inside agent containers |
nfs_server_host | string | null | Critical for volume mounts. NFS server host as seen by the Docker daemon host OS. See platform table below. |
nfs_port | u16 | 2049 | NFS server port |
nfs_mountport | u16 | 2049 | NFS mountd port |
nfs_server_host by environment:
| Environment | Value |
|---|---|
| WSL2 / Linux native | "127.0.0.1" |
| Docker Desktop (macOS) | "host.docker.internal" |
| Linux bridge network | "172.17.0.1" (Docker bridge gateway) |
| Remote / VM host | <physical host IP> |
| Via env var | "env:AEGIS_NFS_HOST" |
spec.network
Optional. Configures ports and TLS.
| Key | Type | Default | Description |
|---|---|---|---|
bind_address | string | 127.0.0.1 | Network interface to bind all listeners. Defaults to loopback; binding a non-loopback address requires either tls configured or allow_insecure_bind: true. |
port | u16 | 8088 | HTTP REST API port |
grpc_port | u16 | 50051 | gRPC API port |
orchestrator_endpoint | string | null | WebSocket URL for edge → orchestrator connection (edge nodes only) |
heartbeat_interval_seconds | u64 | 30 | Health check ping interval |
tls.cert_path | string | — | TLS certificate path |
tls.key_path | string | — | TLS private key path |
tls.ca_path | string | null | CA certificate path (optional) |
allow_insecure_bind | bool | false | Operator-acknowledged opt-out of the non-loopback-without-TLS startup gate. Set true ONLY when TLS is terminated upstream by a trusted-network ingress. See callout below. |
allow_insecure_bind is an opt-out, not a default. AEGIS refuses to start when bind_address is a non-loopback address (e.g. 0.0.0.0) and tls is not configured — every public request would otherwise transit cleartext.
Set allow_insecure_bind: true only when all of the following are true:
- TLS is terminated upstream of this pod by a trusted-network ingress (Caddy, nginx, or an equivalent reverse proxy in the same Podman pod-network).
- The pod's bind endpoint is reachable only from inside that trusted network — never from the public internet.
- You accept the audit-trail consequence: a
WARNentry is emitted on every boot recording that the override is engaged.
The reference pod architecture and Caddy edge proxy deployments use this opt-out because Caddy fronts the backend pods on a private Podman network. Setting allow_insecure_bind: true on a publicly-exposed host is a serious security regression.
spec.cluster
Optional. Configures the node's role in the multi-node cluster topology.
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
enabled | bool | ❌ | false | Enable cluster mode. |
role | enum | ✅ | hybrid | Node role: controller | worker | hybrid |
controller_endpoint | string | ❌ | — | gRPC endpoint of the controller node. Required for role: worker. |
cluster_grpc_port | u16 | ❌ | 50056 | Port for NodeClusterService (controllers/hybrids) |
peers | string[] | ❌ | [] | Static list of peer controller addresses |
node_keypair_path | string | ✅ | — | Path to the persistent Ed25519 keypair file for node identity |
heartbeat_interval_secs | u64 | ❌ | 30 | Interval in seconds for worker heartbeats |
token_refresh_margin_secs | u64 | ❌ | 120 | Token re-attestation margin in seconds |
tls.enabled | bool | ❌ | true | Enable TLS for cluster communication |
tls.cert_path | string | ❌ | — | Path to node TLS certificate |
tls.key_path | string | ❌ | — | Path to node TLS private key |
tls.ca_cert | string | ❌ | — | Path to CA certificate for peer verification |
spec.storage
Optional. Defaults to the local_host backend.
| Key | Type | Default | Description |
|---|---|---|---|
backend | enum | local_host | seaweedfs | local_host |
fallback_to_local | bool | true | Gracefully fall back to local storage when SeaweedFS is unreachable |
nfs_port | u16 | 2049 | NFS Server Gateway listen port |
seaweedfs.filer_url | string | http://localhost:8888 | SeaweedFS Filer endpoint |
seaweedfs.mount_point | string | /var/lib/aegis/storage | Host filesystem mount point |
seaweedfs.default_ttl_hours | u32 | 24 | Default TTL for ephemeral volumes (hours) |
seaweedfs.default_size_limit_mb | u64 | 1000 | Default per-volume size quota (MB) |
seaweedfs.max_size_limit_mb | u64 | 10000 | Hard ceiling on volume size (MB) |
seaweedfs.gc_interval_minutes | u32 | 60 | Expired volume GC interval (minutes) |
seaweedfs.s3_endpoint | string | null | Optional SeaweedFS S3 gateway endpoint |
seaweedfs.s3_region | string | us-east-1 | S3 gateway region |
local_host.base_path | string | /var/lib/aegis/local-volumes | Base directory for local volume storage |
local_host.default_ttl_hours | u32 | 24 | Default TTL for ephemeral volumes (hours) |
local_host.default_size_limit_mb | u64 | 1000 | Default per-volume quota (MB) |
local_host.max_size_limit_mb | u64 | 10000 | Hard ceiling on volume size (MB) |
spec.deploy_builtins
Optional. Default: false.
| Key | Type | Default | Description |
|---|---|---|---|
deploy_builtins | bool | false | Deploy vendored built-in agent and workflow templates on startup. Includes agent-creator-agent, workflow-generator-planner-agent, judge agents (among them goal-judge, which judges goals), intent-executor-discovery-agent, intent-result-formatter-agent, skill-validator, and the builtin-workflow-generator, builtin-intent-to-execution, skill-import, the-forge and transcribe-audio workflows, with the Forge's seven agents (requirements-analyst, architect-agent, tester-agent, coder-agent, code-reviewer-agent, critic-agent, security-auditor-agent). Each is registered under aegis-system with global scope. Required for aegis.agent.generate, aegis.workflow.generate, aegis.execute.intent and aegis.goal.evaluate to function, and for the Forge. |
spec.mcp_servers
Optional array. Each entry defines an external MCP Tool Server process.
| Key | Type | Default | Description |
|---|---|---|---|
name | string | — | Unique server name on this node |
enabled | bool | true | Whether to start this server |
executable | string | — | Executable path |
args | string[] | [] | Command-line arguments |
capabilities | string[] | [] | Tool names this server provides (used for routing) |
credentials | map | {} | API keys/tokens injected as env vars. Values support secret:. |
environment | map | {} | Non-secret env vars for the server process |
health_check.interval_seconds | u64 | 60 | Health check interval |
health_check.timeout_seconds | u64 | 5 | Health check timeout |
health_check.method | string | tools/list | MCP method used to health-check the server |
resource_limits.cpu_millicores | u32 | 1000 | CPU limit (1000 = 1 core) |
resource_limits.memory_mb | u32 | 512 | Memory limit (MB) |
spec.seal
Optional. Enables cryptographic agent authorization via SEAL. Required in production.
| Key | Type | Default | Description |
|---|---|---|---|
private_key_path | string | — | Path to RSA private key PEM for signing SecurityToken JWTs |
public_key_path | string | — | Path to RSA public key PEM for verifying SecurityToken JWTs |
issuer | string | aegis-orchestrator | JWT iss claim |
audiences | string[] | [aegis-agents] | JWT aud claims |
token_ttl_seconds | u64 | 3600 | SecurityToken lifetime in seconds |
spec.security_contexts
Optional array. Named permission boundaries assigned to agents at execution time.
Each entry (SecurityContextDefinition):
| Key | Type | Default | Description |
|---|---|---|---|
name | string | — | Unique context name, referenced in agent manifests |
description | string | "" | Human-readable description |
capabilities | array | [] | Tool permissions granted by this context |
deny_list | string[] | [] | Explicit tool deny list; overrides any matching capability |
Each capabilities entry (CapabilityDefinition):
| Key | Type | Description |
|---|---|---|
tool_pattern | string | Tool name pattern (e.g., "fs.*", "cmd.run", "web.fetch", "*") |
path_allowlist | string[] | Allowed filesystem path prefixes (for fs.* tools) |
subcommand_allowlist | object | Map of base command → allowed first positional arguments (for cmd.run). Example: {cargo: ["build","test"]}. |
domain_allowlist | string[] | Allowed network domain suffixes (for web.* tools) |
rate_limit.calls | u32 | Number of calls allowed per window |
rate_limit.per_seconds | u32 | Window size in seconds |
max_response_size | u64 | Max response size in bytes |
spec.builtin_dispatchers
Optional. Configures the cmd Dispatch Protocol handler. This is an in-process handler — it is not an MCP server process.
| Key | Type | Default | Description |
|---|---|---|---|
cmd.enabled | bool | true | Enable cmd.run dispatch |
cmd.default_timeout_secs | u64 | 60 | Default subprocess timeout |
cmd.max_timeout_ceiling_secs | u64 | 300 | Maximum timeout an agent manifest may request |
cmd.max_output_bytes | u64 | 524288 | Max stdout + stderr per subprocess (512 KB) |
cmd.max_concurrent_per_execution | u32 | 1 | Max concurrent subprocesses per execution |
cmd.global_env_denylist | string[] | (see sample) | Env vars that must never be forwarded to agent subprocesses |
spec.iam
Optional. Configures IAM/OIDC as the trusted JWT issuer. Omit to disable JWT validation (dev only; never in production).
| Key | Type | Default | Description |
|---|---|---|---|
realms[].slug | string | — | Realm name matching the Keycloak configuration |
realms[].issuer_url | string | — | OIDC issuer URL |
realms[].jwks_uri | string | — | JWKS endpoint for JWT signature verification |
realms[].audience | string | — | Expected aud claim in tokens from this realm |
realms[].kind | enum | — | system | consumer | tenant |
jwks_cache_ttl_seconds | u32 | 300 | JWKS key cache TTL; refreshed automatically to support key rotation |
claims.zaru_tier | string | zaru_tier | Keycloak claim name carrying ZaruTier |
claims.aegis_role | string | aegis_role | Keycloak claim name carrying AegisRole |
operator_escalation.ttl_seconds | u64 | 1800 | Seconds an operator escalation lasts from its redemption. See Operator Escalation |
operator_escalation.code_validity_seconds | u64 | 300 | Seconds a generated escalation code stays redeemable |
operator_escalation.code_max_failed_attempts | u32 | 5 | Failed redemptions by a user's keys that invalidate that user's live codes |
keycloak_admin.host | string | — | Keycloak base URL for its Admin REST API; supports env:VAR |
keycloak_admin.admin_username | string | — | Admin user of the master realm; supports env:VAR |
keycloak_admin.admin_password | string | — | That user's password; supports env:VAR |
Omit operator_escalation for these defaults. An unknown key inside it refuses the configuration. keycloak_admin provisions a tenant for a newly signed-up user and lets the orchestrator read an escalated operator's role again; without it, or without a realm of kind: system, every escalation redemption answers 503 and every escalated call is refused.
spec.goals
Optional. The bounds of a goal and the thresholds its judge's verdict is read by (see aegis.goal.evaluate). Omit for these defaults.
| Key | Type | Default | Description |
|---|---|---|---|
max_continuations | u32 | 3 | Continuation rounds granted at most per goal |
lifetime_seconds | u64 | 1800 | Seconds a goal stays open from its creation; must be above 0 |
met_min_score | f64 | 0.85 | A verdict meets the goal at this score or above |
met_min_confidence | f64 | 0.75 | …and at this confidence or above |
cannot_be_met_max_feasibility | f64 | 0.2 | A verdict that does not meet the goal and whose feasibility signal scores at or below this closes it as cannot be met |
Each threshold must be between 0.0 and 1.0, and an unknown key inside the block refuses the configuration. A sweep every ten minutes closes goals open past lifetime_seconds. The judge is the built-in agent goal-judge, deployed with the built-in templates (spec.deploy_builtins) and run on the judge alias. Zaru Web sets goals only for callers whose security context admits the four goal tools; the reference deployment adds them to each zaru-* context's capabilities:
- tool_pattern: "aegis.goal.create"
- tool_pattern: "aegis.goal.evaluate"
- tool_pattern: "aegis.goal.status"
- tool_pattern: "aegis.goal.cancel"spec.grpc_auth
Optional. Controls IAM/OIDC JWT enforcement on the gRPC endpoint. Requires spec.iam to be configured.
| Key | Type | Default | Description |
|---|---|---|---|
enabled | bool | true | Enforce JWT validation on gRPC methods |
exempt_methods | string[] | [/aegis.v1.InnerLoop/Generate] | gRPC method full paths exempt from auth. The inner-loop bootstrap channel must always be exempt. |
spec.secrets
Optional. Configures OpenBao as the secrets backend. Follows the Keymaster Pattern — agents never access OpenBao directly.
| Key | Type | Default | Description |
|---|---|---|---|
backend.address | string | — | OpenBao server URL |
backend.auth_method | string | approle | Authentication method. Only approle is currently supported. |
backend.approle.role_id | string | — | AppRole Role ID (public; safe to commit) |
backend.approle.secret_id_env_var | string | OPENBAO_SECRET_ID | Name of the environment variable containing the AppRole Secret ID. Never commit the actual Secret ID. |
backend.namespace | string | — | OpenBao namespace (maps 1:1 to an IAM realm) |
backend.tls.ca_cert | string | null | CA certificate path |
backend.tls.client_cert | string | null | mTLS client certificate path |
backend.tls.client_key | string | null | mTLS client key path |
spec.database
Optional. PostgreSQL connection for persistent state (executions, patterns, workflows). If omitted, the daemon uses in-memory repositories (development mode only).
| Key | Type | Default | Description |
|---|---|---|---|
url | string | — | PostgreSQL connection URL. Supports env: and secret:. |
max_connections | u32 | 5 | Maximum connections in the pool |
connect_timeout_seconds | u64 | 5 | Connection timeout |
spec.temporal
Optional. Temporal workflow engine configuration for durable workflow execution. If omitted, workflow orchestration features are unavailable.
| Key | Type | Default | Description |
|---|---|---|---|
address | string | temporal:7233 | Temporal gRPC server address |
worker_http_endpoint | string | http://localhost:3000 | HTTP endpoint for Temporal worker callbacks. Supports env:. |
worker_secret | string | null | Shared secret for authenticating worker callbacks. Supports env: and secret:. |
namespace | string | default | Temporal namespace |
task_queue | string | aegis-agents | Temporal task queue name |
max_connection_retries | i32 | 30 | Maximum number of connection retries when establishing the Temporal client. |
spec.cortex
Optional. Cortex memory and learning service configuration. If omitted or grpc_url is null, the daemon runs in memoryless mode — patterns are simply not stored.
| Key | Type | Default | Description |
|---|---|---|---|
grpc_url | string | null | Cortex gRPC service URL. Supports env:. |
api_key | string | null | API key for 100monkeys hosted Cortex (Zaru SaaS). Supports env: and secret: prefixes. When absent, the orchestrator connects without authentication (local/open cortex). |
spec.discovery
Discovery — Semantic agent and workflow search (aegis.agent.search, aegis.workflow.search) is powered by the Cortex service. When spec.cortex is configured with a valid grpc_url and api_key, discovery is available automatically. No separate spec.discovery configuration is required.
spec.billing
Optional. Configures Stripe billing integration. Omit this section for self-hosted deployments where billing is not required. When stripe_secret_key is absent, all /v1/billing/* endpoints return 501 Not Implemented.
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
stripe_secret_key | string | Yes | — | Stripe API secret key (server-side only). Supports env: and secret: prefixes. |
stripe_webhook_secret | string | No | — | Webhook signing secret for verifying Stripe event signatures (HMAC-SHA256). Supports env: and secret: prefixes. |
All fields support env: and secret: credential prefixes (see Credential Resolution).
Pricing is dynamic — the orchestrator fetches available tiers and prices directly from Stripe at runtime via GET /v1/billing/prices. No price IDs are configured in NodeConfig.
Note:
STRIPE_PUBLISHABLE_KEYis a frontend-only environment variable configured on the Zaru client container, not in the orchestrator config.
spec.seal_gateway
Optional. Configures forwarding of external tool invocations to the standalone SEAL tooling gateway.
| Key | Type | Default | Description |
|---|---|---|---|
url | string | null | gRPC endpoint URL of aegis-seal-gateway (example: http://aegis-seal-gateway:50055). |
If omitted, orchestrator does not forward unknown/external tools to the gateway and continues with built-in routing only.
spec.max_execution_list_limit
Optional. Upper bound on executions returned by a single list_executions request.
| Key | Type | Default | Description |
|---|---|---|---|
max_execution_list_limit | usize | 1000 | Maximum number of executions returned by a single list_executions request. Protects against excessive memory usage. |
spec.observability
Optional.
logging
| Key | Type | Default | Env Override | Description |
|---|---|---|---|---|
logging.level | enum | info | RUST_LOG | error | warn | info | debug | trace |
logging.format | enum | json | AEGIS_LOG_FORMAT | json | text |
logging.file | string | null | — | Log file path. Omit to write to stdout. |
logging.otlp_endpoint | string | null | AEGIS_OTLP_ENDPOINT | OTLP collector endpoint. Setting this enables OTLP log export. |
logging.otlp_protocol | enum | grpc | AEGIS_OTLP_PROTOCOL | grpc | http |
logging.otlp_headers | map | {} | AEGIS_OTLP_HEADERS | Key-value headers sent with every OTLP export RPC. Values support env: and secret: prefixes. Env var uses comma-separated key=value pairs. |
logging.otlp_min_level | string | info | AEGIS_OTLP_LOG_LEVEL | Minimum log level forwarded to OTLP (does not affect stdout). |
logging.otlp_service_name | string | aegis-orchestrator | AEGIS_OTLP_SERVICE_NAME | service.name resource attribute |
logging.otlp_batch.max_queue_size | u32 | 2048 | — | Maximum buffered records before export |
logging.otlp_batch.scheduled_delay_ms | u64 | 5000 | — | Batch flush interval (ms) |
logging.otlp_batch.max_export_batch_size | u32 | 512 | — | Records per export RPC |
logging.otlp_batch.export_timeout_ms | u64 | 10000 | — | Per-call timeout (ms) |
logging.otlp_tls.verify | bool | true | — | Verify OTLP endpoint TLS certificate |
logging.otlp_tls.ca_cert_path | string | null | — | Custom CA certificate for self-signed backends |
metrics
| Key | Type | Default | Description |
|---|---|---|---|
metrics.enabled | bool | true | Enable Prometheus metrics |
metrics.port | u16 | 9091 | Prometheus metrics exposition port |
metrics.path | string | /metrics | HTTP path for scraping |
tracing
| Key | Type | Default | Description |
|---|---|---|---|
tracing.enabled | bool | false | Enable distributed tracing via OpenTelemetry |
cluster.edge — edge daemon configuration
When cluster.role: edge, the daemon requires a cluster.edge block. The block is populated automatically by aegis edge enroll; tenant_id is written at enrollment and is immutable thereafter.
cluster:
enabled: true
role: edge
controller:
endpoint: relay.example.com:443 # SaaS default; OSS overrides to local controller
tls: { enabled: true }
node_keypair_path: ~/.aegis/edge/node.key
heartbeat_interval_secs: 30
edge:
tenant_id: u-... # written by `aegis edge enroll`, immutable
enrollment_token_path: ~/.aegis/edge/enrollment.jwt
node_security_token_path: ~/.aegis/edge/node.token
stream_reconnect_backoff_secs: [1, 2, 5, 15, 60]
capabilities:
local_tools: [shell, docker, kubectl]
mount_points: ["/", "/home/jeshua"]
custom_labels: { region: home }| Key | Type | Default | Description |
|---|---|---|---|
cluster.edge.tenant_id | string | — | Immutable post-enrollment. Mirrors the tid claim on the NodeSecurityToken. |
cluster.edge.enrollment_token_path | path | ~/.aegis/edge/enrollment.jwt | One-time enrollment token; consumed atomically. |
cluster.edge.node_security_token_path | path | ~/.aegis/edge/node.token | Persistent NodeSecurityToken. |
cluster.edge.stream_reconnect_backoff_secs | array<int> | [1, 2, 5, 15, 60] | Exponential backoff schedule on stream loss. |
cluster.edge.capabilities.local_tools | array<string> | host-detected | Which built-in tools the daemon can serve. |
cluster.edge.capabilities.mount_points | array<string> | ["/"] | Filesystem roots the daemon may operate against (subject to SecurityContext). |
cluster.edge.capabilities.custom_labels | map<string,string> | {} | Daemon-advertised labels — queryable in selectors. |
Validator behavior: role: edge rejects cluster_grpc_port (the daemon does not bind a server) and requires the cluster.edge block. role: relay-coordinator requires cluster.cluster_grpc_port and cluster.ingress.public_endpoint.
For the full edge config reference, see edge config.