AEGIS DOCS

Local macOS Service

This is the first deployment target for Aegis as a local Mac service. It runs on this Mac, binds to localhost by default, and uses a stable data directory outside the repository.

Defaults

The service is local-only unless AGENT_HARNESS_HOST is changed. If the host is changed beyond localhost, AGENT_HARNESS_TOKEN must be set before the server will start.

One-Time Setup

scripts/install-launchd-service.sh

The installer runs the storage setup helper when needed. It prompts for one canonical data directory, shows the derived database, run workspace, upload, asset, project, log, and secret paths, writes the env file, creates the storage marker, builds the TypeScript output, writes the launchd plist, and loads the service.

To run setup directly:

npm run setup:storage

Startup refuses to create a fallback database if the configured storage directory is missing. Restore the configured storage or intentionally rerun setup to create a new empty install.

Check Status

curl http://127.0.0.1:4317/health
curl http://127.0.0.1:4317/control-plane/status
launchctl list local.agent-harness.control-plane
tail -f "<data-directory>/.agent-harness/logs/control-plane.out.log"
tail -f "<data-directory>/.agent-harness/logs/control-plane.err.log"

Check Provider Execution

Use the provider smoke harness after install, after credential refresh, or after changing provider/model configuration. These checks call live providers, so they are intentionally separate from npm test.

AGENT_HARNESS_ALLOW_LIVE_MODEL_SMOKE=1 npm run smoke:providers -- --provider codex
AGENT_HARNESS_ALLOW_LIVE_MODEL_SMOKE=1 npm run smoke:providers -- --provider opencode-zen
AGENT_HARNESS_ALLOW_LIVE_MODEL_SMOKE=1 npm run smoke:providers -- --provider opencode-go

Ollama depends on the local Ollama API and model availability:

AGENT_HARNESS_ALLOW_LIVE_MODEL_SMOKE=1 npm run smoke:providers -- --provider ollama

The System Health panel also reports provider health from non-generating catalog/API checks plus recent provider failures observed by the harness.

GET /control-plane/status is the operator health contract. It includes server config and log tail links, worker state, aggregate and per-run queue state, recent failures, provider catalog health, credential readiness, and policy boundary enforcement for high-risk classes. GET /providers/health returns the provider health map directly. Provider catalog checks do not generate model output; they only inspect local CLI catalogs or the Ollama tags endpoint.

The API worker also owns periodic local maintenance. AGENT_HARNESS_MAINTENANCE_INTERVAL_MS defaults to 15 minutes. Each maintenance cycle scans enabled schedule automations and runs non-destructive memory maintenance. Set it to 0 to disable those hooks.

For an end-to-end service check from the browser, create a Provider Smoke Check run in the UI. It verifies API queueing, the background worker, the selected model gateway, model-call trace metadata, and smoke artifacts. It does not validate research citations or coding quality.

Stop Or Remove

launchctl unload ~/Library/LaunchAgents/local.agent-harness.control-plane.plist

scripts/uninstall-launchd-service.sh

The uninstall script removes the launchd plist. It does not delete the configured data directory, because that directory contains durable run state, secrets, and logs.

Later LAN Mode

When the network server or LAN access is ready, update the env file:

AGENT_HARNESS_HOST=0.0.0.0
AGENT_HARNESS_TOKEN=replace-with-a-long-random-token
AGENT_HARNESS_AGENT_TOKEN=optional-agent-only-token

Then reload the service:

launchctl unload ~/Library/LaunchAgents/local.agent-harness.control-plane.plist
launchctl load ~/Library/LaunchAgents/local.agent-harness.control-plane.plist

API calls must include:

Authorization: Bearer replace-with-a-long-random-token

AGENT_HARNESS_TOKEN is the operator token. AGENT_HARNESS_AGENT_TOKEN is optional and limited to the readable/steering operations listed by GET /agent-client/contract.

For the browser UI, open the page once with the token query parameter:

http://<host>:4317/?token=replace-with-a-long-random-token

The UI stores that token in browser local storage and uses it for API calls. Rotate the token by changing AGENT_HARNESS_TOKEN, reloading launchd, and opening the UI with the new ?token= value.

Public HTTPS remains a later deployment layer behind a reverse proxy or private access layer.