AEGIS DOCS

Architecture Overview

Aegis is a local supervised AI agent harness. The dashboard, API, worker, runtime database, run workspaces, approvals, audit records, and artifacts live on the operator’s machine unless a configured provider or connector is called.

The default service listens on http://127.0.0.1:4317. Binding to a LAN address requires AGENT_HARNESS_TOKEN.

System Map

flowchart LR operator["Operator"] browser["Dashboard
Browser UI"] cli["CLI
npm run cli -- ..."] agentClient["Headless agent client
optional scoped token"] subgraph local["Local machine"] api["Control-plane API
127.0.0.1:4317"] worker["Worker runtime
AGENT_HARNESS_WORKER_MODE=api-worker"] service["Orchestrator
policy, approvals, traces"] db[("SQLite runtime DB
better-sqlite3")] workspaces["Run workspaces
artifacts, verifier output, audit data"] secrets["Secret material
local file-backed store"] workflows["Workflow and skill dirs
repo workflows / repo skills"] end subgraph external["External only when configured"] providers["Model providers
Codex, Ollama, OpenCode, other adapters"] connectors["Connectors and APIs
GitHub, GitLab, Gmail, webhooks, apps"] end operator --> browser operator --> cli browser --> api agentClient -. read and steer .-> api cli --> service api --> service service --> worker worker --> service service --> db service --> workspaces service --> secrets service --> workflows worker -. model calls .-> providers worker -. connector calls .-> connectors

What Runs Locally

Component Role Default
Dashboard Browser UI for chat, workflows, approvals, runs, artifacts, settings, and operational views. Served by the local API at http://127.0.0.1:4317/.
Control-plane API Local HTTP API for runs, workflows, providers, connectors, approvals, artifacts, audit exports, and headless-agent access. AGENT_HARNESS_HOST=127.0.0.1, AGENT_HARNESS_PORT=4317.
Worker runtime Executes queued work, verifier loops, maintenance hooks, and local run progression. AGENT_HARNESS_WORKER_MODE=api-worker, meaning the API process also owns worker cycles.
CLI Operator and runbook interface for creating runs, checking artifacts, approving or rejecting checkpoints, managing secrets, and exporting audit data. npm run cli -- <command>.
Runtime DB Durable records for runs, approvals, traces, tasks, workflows, automations, memory records, provider health, connector metadata, and audit state. SQLite through better-sqlite3.
Run workspaces Filesystem output for each run: goals, workflow snapshots, task output, verifier results, repo-write bundles, final summaries, and logs. <dataDir>/.agent-harness/runs/<run-id>/.
Secret store Raw secret material for provider keys, tokens, webhook secrets, and connector credentials. <dataDir>/.agent-harness-secrets/; the DB stores metadata, hashes, and redacted previews.

Storage Layout

AGENT_HARNESS_DATA_DIR is the canonical data root. The setup script defaults to ~/Aegis unless another path is selected.

Path Contents
<dataDir>/.agent-harness/agent-harness.db SQLite runtime database.
<dataDir>/.agent-harness/runs/ Per-run workspaces and artifacts.
<dataDir>/.agent-harness/uploads/ Uploaded inputs and attachments.
<dataDir>/.agent-harness/assets/ Local generated or imported assets.
<dataDir>/.agent-harness/projects/ Project-scoped local state.
<dataDir>/.agent-harness/logs/ Control-plane logs.
<dataDir>/.agent-harness-secrets/ Local secret material with restricted file permissions.

The runtime database is SQLite today. Aegis may expose separate retrieval or memory backends for specialized search/vector workflows, but those do not replace the core runtime database.

Request Flow

  1. The operator starts from the dashboard or CLI.
  2. The API validates the request, token, contract shape, and policy boundary.
  3. The orchestrator creates or updates durable run state in SQLite.
  4. The worker executes the next eligible step.
  5. Model providers or connectors are called only when the workflow and tool policy allow them.
  6. Outputs are written to the run workspace and indexed as artifacts.
  7. Verifier results, traces, approval checkpoints, and audit records are stored with the run.
  8. The dashboard, CLI, or headless-agent client reads the same durable state to inspect progress.

Network Boundary

Localhost is the default trust boundary. With no token and a localhost bind, the UI is served for local operator use. When AGENT_HARNESS_HOST binds beyond localhost, Aegis requires AGENT_HARNESS_TOKEN before the server starts.

AGENT_HARNESS_AGENT_TOKEN is optional and narrower. It allows headless agents to inspect approved state and add steering input through agent-readable and agent-steering operations. It does not approve high-risk checkpoints, mutate operator-owned configuration, read raw secrets, or call blocked/destructive operations.

Public HTTPS is not the default operating mode. Put Aegis behind a private network boundary unless the deployment plan explicitly handles authentication, TLS, device trust, backups, and audit review.

Key Environment Variables

Variable Purpose
AGENT_HARNESS_HOST API bind host. Defaults to 127.0.0.1.
AGENT_HARNESS_PORT API port. Defaults to 4317; PORT is also accepted by the config resolver.
AGENT_HARNESS_DATA_DIR Required data root for DB, workspaces, logs, assets, uploads, projects, and secret metadata.
AGENT_HARNESS_WORKFLOW_DIR Workflow definition directory. Defaults to <repo>/workflows.
AGENT_HARNESS_SKILL_DIR Skill definition directory. Defaults to <repo>/src/skills/manifests.
AGENT_HARNESS_WORKER_MODE api-worker or api-only.
AGENT_HARNESS_TOKEN Operator bearer token, required for non-localhost binds.
AGENT_HARNESS_AGENT_TOKEN Optional scoped token for headless-agent read and steering access.

Current Boundaries