AEGIS DOCS

Aegis State Migration Runbook

Use this when moving local Aegis state from the development machine to a dedicated local or private-network server.

Scope

This migrates durable Aegis state, not the application source tree:

Raw secret values are never written into backup manifests, audit exports, or replay packets. Copying .agent-harness-secrets/ moves local credential material and should be treated as sensitive.

1. Stop Writes

Stop the local service or avoid queueing new runs while copying state. SQLite WAL/SHM files can exist during active writes; the safest migration is an offline filesystem copy.

For launchd service installs:

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

For development servers, stop the npm run dev:api process.

2. Create A Backup Manifest

From the source checkout:

npm run cli -- backup-manifest /tmp/agent-harness-backup-manifest.json

Review warnings before copying:

cat /tmp/agent-harness-backup-manifest.json

Warnings about WAL files mean the service should be stopped or the database should be checkpointed before copy.

3. Copy State

Copy from the current data directory:

npm run copy:state -- \
  --source "${AGENT_HARNESS_DATA_DIR:-$PWD}" \
  --target /path/to/destination-data-dir \
  --manifest /tmp/agent-harness-backup-manifest.json

To migrate without local secret material:

npm run copy:state -- \
  --source "${AGENT_HARNESS_DATA_DIR:-$PWD}" \
  --target /path/to/destination-data-dir \
  --manifest /tmp/agent-harness-backup-manifest.json \
  --exclude-secrets

If the target directory already has expected bootstrap files, pass --force to merge into it.

The helper writes migration-copy-report.json into the target directory.

4. Verify Restore

Before starting the destination service:

npm run cli -- verify-restore /path/to/destination-data-dir \
  --manifest /path/to/destination-data-dir/backup-manifest.json

Expected status is passed or warning. A warning can be acceptable after migration when the manifest source dataDir differs from the destination path, the source snapshot included WAL/SHM files, or secrets were intentionally excluded. Failed manifest schema validation, unreadable database state, database hash mismatch without WAL/SHM context, missing run directories, missing artifacts, artifact size mismatch, and artifact hash mismatch are blockers.

5. Configure Destination Service

Set the destination env file:

AGENT_HARNESS_HOST=127.0.0.1
AGENT_HARNESS_PORT=4317
AGENT_HARNESS_DATA_DIR=/path/to/destination-data-dir
AGENT_HARNESS_WORKFLOW_DIR=/path/to/agent-harness/workflows
AGENT_HARNESS_SKILL_DIR=/path/to/agent-harness/src/skills/manifests
AGENT_HARNESS_WORKER_MODE=api-worker
AGENT_HARNESS_TOKEN=

When binding beyond localhost, set AGENT_HARNESS_TOKEN before changing AGENT_HARNESS_HOST.

6. Start And Smoke Check

Start the destination service, then check:

curl http://127.0.0.1:4317/health
curl http://127.0.0.1:4317/control-plane/status
curl http://127.0.0.1:4317/providers/health

Then run provider smoke for at least one ready provider:

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

7. Repair Expected Gaps