Edge Config Reference

This page is the canonical reference for edge-daemon configuration. It covers the cluster.edge block, the on-disk layout under ~/.aegis/edge/, the bootstrap prompt matrix used by aegis edge enroll, and the matching Relay Coordinator config.

For broader configuration context, see configuration and node config reference.

File location

The edge daemon reads a single merged config from ~/.aegis/edge/aegis-config.yaml by default. The path is overridable via --config <path> on every daemon-side command.

The merged config is the result of layering, in order:

1. The daemon's bundled defaults.
2. ~/.aegis/config.yaml (user-level shared config, if present).
3. ~/.aegis/edge/aegis-config.yaml (edge-specific config).
4. PushConfig deltas pushed from the controller during the active stream.

Lower layers override higher layers. The final merged result is what the daemon evaluates.

The cluster.edge block

Required when cluster.role: edge. The validator rejects edge configs that omit it.

cluster:
  enabled: true
  role: edge
  controller:
    endpoint: relay.example.com:443
    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
        gpu: rtx-4090

Field reference

Validator behavior

On-disk layout

~/.aegis/edge/
├── aegis-config.yaml          # this file
├── node.key                   # Ed25519 private key (mode 0600)
├── node.key.pub               # Ed25519 public key
├── node.token                 # NodeSecurityToken (issued at enrollment)
├── enrollment.jwt             # consumed once; deleted on success
├── logs/                      # service-manager log destination
├── secrets/                   # local KV store (mode 0700)
└── archive/                   # rotated keys retained during overlap window

Permission expectations

aegis edge enroll enforces these on bootstrap. The daemon also re-checks at startup; if any file is too permissive it logs a warning and chmods to the expected mode.

Bootstrap prompt matrix

aegis edge enroll runs a BootstrapPlan before contacting the server. For each artifact, the CLI either creates it (if missing), prompts (if present and ambiguous), or proceeds non-interactively (with --force / --keep-existing / --non-interactive).

Non-interactive flag matrix

Auto-generated template fields

When aegis edge enroll writes a fresh aegis-config.yaml, it fills the following fields automatically based on host inspection:

Minimal template (--minimal):

cluster:
  enabled: true
  role: edge
  controller:
    endpoint: relay.example.com:443
    tls: { enabled: true }
  edge:
    tenant_id: <filled-by-enroll>

Defaults are filled at runtime; only the minimum required fields appear on disk.

Relay Coordinator config

For the SaaS-side process:

cluster:
  enabled: true
  role: relay-coordinator
  cluster_grpc_port: 50056
  ingress:
    public_endpoint: relay.example.com # advertised in enrollment tokens (cep claim)

The Relay does not require mcp_servers, builtin_dispatchers, or security_contexts — it does not execute tools, only relays them.

Common configuration recipes

Daemon behind a corporate proxy

cluster:
  edge:
    proxy:
      https_proxy: http://corp-proxy.example.com:3128
      no_proxy: 127.0.0.1,localhost,*.example.internal

Or set HTTPS_PROXY / NO_PROXY environment variables in the service unit's Environment= directives.

Daemon with restricted mount points

cluster:
  edge:
    capabilities:
      mount_points: ["/srv/aegis-workspace"]

The daemon's filesystem operations are bounded by the SecurityContext, but mount_points is the daemon-advertised list visible in selectors and helps you reason about reachability.

Daemon with extended labels for fine-grained selectors

cluster:
  edge:
    capabilities:
      custom_labels:
        environment: production
        region: us-east-1
        availability_zone: us-east-1a
        gpu: rtx-4090
        cuda_version: "12.2"

These labels are queryable in any selector via labels=Equals(k,v), labels=Exists(k), or labels=In(k,v1,v2).

What's next

• Edge CLI Reference — every command that reads or writes this config.
• Edge Host Setup — Zaru SaaS guided walk-through that exercises the bootstrap matrix.
• Edge Daemon Installation — service-manager templates that consume this config.
• Edge REST API — REST endpoints for issuing enrollment tokens and managing hosts.
• Configuration — the broader aegis-config.yaml reference.
• Node Configuration — the broader cluster role schema (Controller / Worker / Hybrid / Edge / RelayCoordinator).