Aegis Orchestrator
Deployment

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.yaml

Config Discovery Order

The daemon searches for a config file in the following order. The first match wins:

  1. --config <path> CLI flag
  2. AEGIS_CONFIG_PATH environment variable
  3. ./aegis-config.yaml (working directory)
  4. ~/.aegis/config.yaml
  5. /etc/aegis/config.yaml (Linux/macOS)

Credential Resolution

Any string value in the config file can use a credential prefix instead of a literal:

PrefixResolution
env:VAR_NAMERead from the daemon process environment at startup.
secret:path/to/secretResolved 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: false

Section Reference

spec.node

Required. Identifies this node within the AEGIS cluster.

KeyTypeRequiredDefaultDescription
idstring✅—Unique stable node identifier. UUID recommended. Fails validation if empty.
typeenum✅—edge | orchestrator | hybrid
regionstring❌nullGeographic region (e.g., "us-east-1")
tagsstring[]❌[]Capability tags matched against execution_targets in agent manifests
resources.cpu_coresu32❌—Available CPU cores
resources.memory_gbu32❌—Available RAM in GB
resources.disk_gbu32❌—Available disk in GB
resources.gpubool❌falseGPU available

spec.image_tag

Optional. Docker image tag for AEGIS-owned services.

KeyTypeDefaultDescription
image_tagstring<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.

KeyTypeRequiredDefaultDescription
namestring✅—Unique provider name
typeenum✅—openai | anthropic | gemini | ollama | openai-compatible
endpointstring✅—API endpoint URL
api_keystring❌nullAPI key. Supports env: and secret:.
headersmap❌nullHeader name to value, sent on every request beside Authorization (openai and openai-compatible only). A header named authorization is refused. See Request Headers.
enabledbool❌trueWhether this provider is active
models[].aliasstring✅—Alias referenced in agent manifests
models[].modelstring✅—Provider-side model identifier
models[].capabilitiesstring[]✅—chat | embedding | reasoning | vision | code | image_generation
models[].context_windowu32✅—Max context window in tokens
models[].cost_per_1k_tokensf64❌0.0Cost per 1K tokens (0.0 for free/local)
models[].fallback_aliasstring❌—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.

KeyTypeDefaultDescription
strategyenumprefer-localprefer-local | prefer-cloud | cost-optimized | latency-optimized
default_providerstringnullMust 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_providerstringnullProvider 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_retriesu323Maximum retry attempts on LLM failure. An answer with no text and no tool call counts as a failed attempt.
retry_delay_msu641000Delay between retries in milliseconds
llm_overall_timeout_secsu6430Wall-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_secsu64absent (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.

KeyTypeDefaultDescription
bootstrap_scriptstringassets/bootstrap.pyPath to bootstrap script relative to orchestrator binary
default_isolationenuminheritdocker | podman | firecracker | inherit | process
container_socket_pathstring(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_modestringnullContainer network name for agent containers
orchestrator_urlstringhttp://localhost:8088Callback URL reachable from inside agent containers
nfs_server_hoststringnullCritical for volume mounts. NFS server host as seen by the Docker daemon host OS. See platform table below.
nfs_portu162049NFS server port
nfs_mountportu162049NFS mountd port

nfs_server_host by environment:

EnvironmentValue
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.

KeyTypeDefaultDescription
bind_addressstring127.0.0.1Network interface to bind all listeners. Defaults to loopback; binding a non-loopback address requires either tls configured or allow_insecure_bind: true.
portu168088HTTP REST API port
grpc_portu1650051gRPC API port
orchestrator_endpointstringnullWebSocket URL for edge → orchestrator connection (edge nodes only)
heartbeat_interval_secondsu6430Health check ping interval
tls.cert_pathstring—TLS certificate path
tls.key_pathstring—TLS private key path
tls.ca_pathstringnullCA certificate path (optional)
allow_insecure_bindboolfalseOperator-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 WARN entry 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.

KeyTypeRequiredDefaultDescription
enabledbool❌falseEnable cluster mode.
roleenum✅hybridNode role: controller | worker | hybrid
controller_endpointstring❌—gRPC endpoint of the controller node. Required for role: worker.
cluster_grpc_portu16❌50056Port for NodeClusterService (controllers/hybrids)
peersstring[]❌[]Static list of peer controller addresses
node_keypair_pathstring✅—Path to the persistent Ed25519 keypair file for node identity
heartbeat_interval_secsu64❌30Interval in seconds for worker heartbeats
token_refresh_margin_secsu64❌120Token re-attestation margin in seconds
tls.enabledbool❌trueEnable TLS for cluster communication
tls.cert_pathstring❌—Path to node TLS certificate
tls.key_pathstring❌—Path to node TLS private key
tls.ca_certstring❌—Path to CA certificate for peer verification

spec.storage

Optional. Defaults to the local_host backend.

KeyTypeDefaultDescription
backendenumlocal_hostseaweedfs | local_host
fallback_to_localbooltrueGracefully fall back to local storage when SeaweedFS is unreachable
nfs_portu162049NFS Server Gateway listen port
seaweedfs.filer_urlstringhttp://localhost:8888SeaweedFS Filer endpoint
seaweedfs.mount_pointstring/var/lib/aegis/storageHost filesystem mount point
seaweedfs.default_ttl_hoursu3224Default TTL for ephemeral volumes (hours)
seaweedfs.default_size_limit_mbu641000Default per-volume size quota (MB)
seaweedfs.max_size_limit_mbu6410000Hard ceiling on volume size (MB)
seaweedfs.gc_interval_minutesu3260Expired volume GC interval (minutes)
seaweedfs.s3_endpointstringnullOptional SeaweedFS S3 gateway endpoint
seaweedfs.s3_regionstringus-east-1S3 gateway region
local_host.base_pathstring/var/lib/aegis/local-volumesBase directory for local volume storage
local_host.default_ttl_hoursu3224Default TTL for ephemeral volumes (hours)
local_host.default_size_limit_mbu641000Default per-volume quota (MB)
local_host.max_size_limit_mbu6410000Hard ceiling on volume size (MB)

spec.deploy_builtins

Optional. Default: false.

KeyTypeDefaultDescription
deploy_builtinsboolfalseDeploy 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.

KeyTypeDefaultDescription
namestring—Unique server name on this node
enabledbooltrueWhether to start this server
executablestring—Executable path
argsstring[][]Command-line arguments
capabilitiesstring[][]Tool names this server provides (used for routing)
credentialsmap{}API keys/tokens injected as env vars. Values support secret:.
environmentmap{}Non-secret env vars for the server process
health_check.interval_secondsu6460Health check interval
health_check.timeout_secondsu645Health check timeout
health_check.methodstringtools/listMCP method used to health-check the server
resource_limits.cpu_millicoresu321000CPU limit (1000 = 1 core)
resource_limits.memory_mbu32512Memory limit (MB)

spec.seal

Optional. Enables cryptographic agent authorization via SEAL. Required in production.

KeyTypeDefaultDescription
private_key_pathstring—Path to RSA private key PEM for signing SecurityToken JWTs
public_key_pathstring—Path to RSA public key PEM for verifying SecurityToken JWTs
issuerstringaegis-orchestratorJWT iss claim
audiencesstring[][aegis-agents]JWT aud claims
token_ttl_secondsu643600SecurityToken lifetime in seconds

spec.security_contexts

Optional array. Named permission boundaries assigned to agents at execution time.

Each entry (SecurityContextDefinition):

KeyTypeDefaultDescription
namestring—Unique context name, referenced in agent manifests
descriptionstring""Human-readable description
capabilitiesarray[]Tool permissions granted by this context
deny_liststring[][]Explicit tool deny list; overrides any matching capability

Each capabilities entry (CapabilityDefinition):

KeyTypeDescription
tool_patternstringTool name pattern (e.g., "fs.*", "cmd.run", "web.fetch", "*")
path_allowliststring[]Allowed filesystem path prefixes (for fs.* tools)
subcommand_allowlistobjectMap of base command → allowed first positional arguments (for cmd.run). Example: {cargo: ["build","test"]}.
domain_allowliststring[]Allowed network domain suffixes (for web.* tools)
rate_limit.callsu32Number of calls allowed per window
rate_limit.per_secondsu32Window size in seconds
max_response_sizeu64Max 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.

KeyTypeDefaultDescription
cmd.enabledbooltrueEnable cmd.run dispatch
cmd.default_timeout_secsu6460Default subprocess timeout
cmd.max_timeout_ceiling_secsu64300Maximum timeout an agent manifest may request
cmd.max_output_bytesu64524288Max stdout + stderr per subprocess (512 KB)
cmd.max_concurrent_per_executionu321Max concurrent subprocesses per execution
cmd.global_env_denyliststring[](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).

KeyTypeDefaultDescription
realms[].slugstring—Realm name matching the Keycloak configuration
realms[].issuer_urlstring—OIDC issuer URL
realms[].jwks_uristring—JWKS endpoint for JWT signature verification
realms[].audiencestring—Expected aud claim in tokens from this realm
realms[].kindenum—system | consumer | tenant
jwks_cache_ttl_secondsu32300JWKS key cache TTL; refreshed automatically to support key rotation
claims.zaru_tierstringzaru_tierKeycloak claim name carrying ZaruTier
claims.aegis_rolestringaegis_roleKeycloak claim name carrying AegisRole
operator_escalation.ttl_secondsu641800Seconds an operator escalation lasts from its redemption. See Operator Escalation
operator_escalation.code_validity_secondsu64300Seconds a generated escalation code stays redeemable
operator_escalation.code_max_failed_attemptsu325Failed redemptions by a user's keys that invalidate that user's live codes
keycloak_admin.hoststring—Keycloak base URL for its Admin REST API; supports env:VAR
keycloak_admin.admin_usernamestring—Admin user of the master realm; supports env:VAR
keycloak_admin.admin_passwordstring—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.

KeyTypeDefaultDescription
max_continuationsu323Continuation rounds granted at most per goal
lifetime_secondsu641800Seconds a goal stays open from its creation; must be above 0
met_min_scoref640.85A verdict meets the goal at this score or above
met_min_confidencef640.75…and at this confidence or above
cannot_be_met_max_feasibilityf640.2A 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.

KeyTypeDefaultDescription
enabledbooltrueEnforce JWT validation on gRPC methods
exempt_methodsstring[][/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.

KeyTypeDefaultDescription
backend.addressstring—OpenBao server URL
backend.auth_methodstringapproleAuthentication method. Only approle is currently supported.
backend.approle.role_idstring—AppRole Role ID (public; safe to commit)
backend.approle.secret_id_env_varstringOPENBAO_SECRET_IDName of the environment variable containing the AppRole Secret ID. Never commit the actual Secret ID.
backend.namespacestring—OpenBao namespace (maps 1:1 to an IAM realm)
backend.tls.ca_certstringnullCA certificate path
backend.tls.client_certstringnullmTLS client certificate path
backend.tls.client_keystringnullmTLS 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).

KeyTypeDefaultDescription
urlstring—PostgreSQL connection URL. Supports env: and secret:.
max_connectionsu325Maximum connections in the pool
connect_timeout_secondsu645Connection timeout

spec.temporal

Optional. Temporal workflow engine configuration for durable workflow execution. If omitted, workflow orchestration features are unavailable.

KeyTypeDefaultDescription
addressstringtemporal:7233Temporal gRPC server address
worker_http_endpointstringhttp://localhost:3000HTTP endpoint for Temporal worker callbacks. Supports env:.
worker_secretstringnullShared secret for authenticating worker callbacks. Supports env: and secret:.
namespacestringdefaultTemporal namespace
task_queuestringaegis-agentsTemporal task queue name
max_connection_retriesi3230Maximum 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.

KeyTypeDefaultDescription
grpc_urlstringnullCortex gRPC service URL. Supports env:.
api_keystringnullAPI 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.

KeyTypeRequiredDefaultDescription
stripe_secret_keystringYes—Stripe API secret key (server-side only). Supports env: and secret: prefixes.
stripe_webhook_secretstringNo—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_KEY is 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.

KeyTypeDefaultDescription
urlstringnullgRPC 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.

KeyTypeDefaultDescription
max_execution_list_limitusize1000Maximum number of executions returned by a single list_executions request. Protects against excessive memory usage.

spec.observability

Optional.

logging

KeyTypeDefaultEnv OverrideDescription
logging.levelenuminfoRUST_LOGerror | warn | info | debug | trace
logging.formatenumjsonAEGIS_LOG_FORMATjson | text
logging.filestringnull—Log file path. Omit to write to stdout.
logging.otlp_endpointstringnullAEGIS_OTLP_ENDPOINTOTLP collector endpoint. Setting this enables OTLP log export.
logging.otlp_protocolenumgrpcAEGIS_OTLP_PROTOCOLgrpc | http
logging.otlp_headersmap{}AEGIS_OTLP_HEADERSKey-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_levelstringinfoAEGIS_OTLP_LOG_LEVELMinimum log level forwarded to OTLP (does not affect stdout).
logging.otlp_service_namestringaegis-orchestratorAEGIS_OTLP_SERVICE_NAMEservice.name resource attribute
logging.otlp_batch.max_queue_sizeu322048—Maximum buffered records before export
logging.otlp_batch.scheduled_delay_msu645000—Batch flush interval (ms)
logging.otlp_batch.max_export_batch_sizeu32512—Records per export RPC
logging.otlp_batch.export_timeout_msu6410000—Per-call timeout (ms)
logging.otlp_tls.verifybooltrue—Verify OTLP endpoint TLS certificate
logging.otlp_tls.ca_cert_pathstringnull—Custom CA certificate for self-signed backends

metrics

KeyTypeDefaultDescription
metrics.enabledbooltrueEnable Prometheus metrics
metrics.portu169091Prometheus metrics exposition port
metrics.pathstring/metricsHTTP path for scraping

tracing

KeyTypeDefaultDescription
tracing.enabledboolfalseEnable 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 }
KeyTypeDefaultDescription
cluster.edge.tenant_idstring—Immutable post-enrollment. Mirrors the tid claim on the NodeSecurityToken.
cluster.edge.enrollment_token_pathpath~/.aegis/edge/enrollment.jwtOne-time enrollment token; consumed atomically.
cluster.edge.node_security_token_pathpath~/.aegis/edge/node.tokenPersistent NodeSecurityToken.
cluster.edge.stream_reconnect_backoff_secsarray<int>[1, 2, 5, 15, 60]Exponential backoff schedule on stream loss.
cluster.edge.capabilities.local_toolsarray<string>host-detectedWhich built-in tools the daemon can serve.
cluster.edge.capabilities.mount_pointsarray<string>["/"]Filesystem roots the daemon may operate against (subject to SecurityContext).
cluster.edge.capabilities.custom_labelsmap<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.

On this page