Build, run, and verify AEGIS locally — from a quick CLI smoke test to a full Docker-based Temporal workflow integration.

Local & Integration Testing

This guide covers two complementary testing approaches:

Local CLI testing — build the orchestrator, deploy demo agents, and run tasks directly against the daemon.
Integration testing — spin up the full Docker stack (Temporal, PostgreSQL, TypeScript worker, Rust gRPC server) and exercise the complete workflow engine end-to-end.

Example Manifests

Agent manifests, workflow definitions, and judge configurations referenced throughout this guide are all available in the aegis-examples repository. Clone it alongside aegis-orchestrator before following any of the steps below.

git clone https://github.com/100monkeys-ai/aegis-examples.git

Part 1: Local CLI Testing

Prerequisites: Rust toolchain (stable), an AEGIS API key configured in the environment.

Quick Smoke Test

The shortest path to a working end-to-end run:

pkill aegis || true && \
cargo build -p aegis-orchestrator && \
target/debug/aegis daemon start && \
target/debug/aegis daemon status && \
target/debug/aegis agent deploy ./agents/echo/agent.yaml --output json && \
target/debug/aegis task execute echo --input "Hello Daemon" --output json && \
target/debug/aegis agent logs echo

This single chain:

Kills any existing aegis processes
Builds the CLI in debug mode
Starts the daemon
Confirms the daemon is healthy
Deploys the echo demo agent (manifest from aegis-examples)
Runs a task against it
Tails the agent logs

Build Reference

Goal	Command
Debug build (fast)	`cargo build -p aegis-orchestrator`
Release build (optimised)	`cargo build --release -p aegis-orchestrator`
Full workspace	`cargo build`
Lint check only	`cargo check`
Specific crate	`cargo check -p aegis-orchestrator`

Clean between major changes:

cargo clean
cargo build -p aegis-orchestrator

Deploying Demo Agents

All demo manifests live under agents/ in aegis-examples. Start the daemon first, then deploy any or all:

target/debug/aegis daemon start
target/debug/aegis daemon status

target/debug/aegis agent deploy ./agents/echo/agent.yaml --output json
target/debug/aegis agent deploy ./agents/greeter/agent.yaml --output json
target/debug/aegis agent deploy ./agents/coder/agent.yaml --output json
target/debug/aegis agent deploy ./agents/debater/agent.yaml --output json
target/debug/aegis agent deploy ./agents/poet/agent.yaml --output json
target/debug/aegis agent deploy ./agents/piglatin/agent.yaml --output json

target/debug/aegis agent list

Running Tests Against Each Agent

Agent	Command	Expected behaviour
`echo`	`target/debug/aegis task execute echo --input "Hello Daemon" --output json`	Echoes the input verbatim
`greeter`	`target/debug/aegis task execute greeter --input "Jeshua" --output json`	Returns a personalised greeting
`coder`	`target/debug/aegis task execute coder --input "What are the advantages of using this language?" --output json`	Provides Rust code examples & explanations
`debater`	`target/debug/aegis task execute debater --input "Sushi is delicious." --output json`	Returns a counter-argument
`poet`	`target/debug/aegis task execute poet --input "Tell me about the stars" --output json`	Generates creative, poetic text
`piglatin`	`target/debug/aegis task execute piglatin --input "How are you doing today my friend?" --output json`	Translates the input to Pig Latin

View logs per agent and list all executions:

target/debug/aegis agent logs <agent-name>
target/debug/aegis task list --output json
target/debug/aegis task logs <execution-id>

Automated Test Scripts

Linux / macOS — `test-aegis.sh`

#!/bin/bash
set -e

echo "=== AEGIS Build and Test ==="

pkill aegis || true
sleep 2

cargo build -p aegis-orchestrator

target/debug/aegis daemon start
sleep 3
target/debug/aegis daemon status

for agent in echo greeter coder debater poet piglatin; do
    echo "  Deploying $agent..."
    target/debug/aegis agent deploy ./agents/$agent/agent.yaml
done

target/debug/aegis agent list --output json

target/debug/aegis task execute echo    --input "Hello Daemon"
target/debug/aegis task execute greeter --input "Jeshua"
target/debug/aegis task execute coder   --input "What are the advantages of using this language?"
target/debug/aegis task execute debater --input "Sushi is delicious."
target/debug/aegis task execute poet    --input "Tell me about the stars"
target/debug/aegis task execute piglatin --input "How are you doing today my friend?"

for agent in echo greeter coder debater poet piglatin; do
    echo "--- Logs for $agent ---"
    target/debug/aegis agent logs $agent | head -20
done

target/debug/aegis task list --output json

echo "=== Test Complete ==="

chmod +x test-aegis.sh && ./test-aegis.sh

Debugging the Daemon

View daemon logs:

# Linux / macOS
tail -f /tmp/aegis.out
tail -f /tmp/aegis.err

Enable debug logging:

export AEGIS_LOG_LEVEL=debug
target/debug/aegis daemon start
# or pass inline
target/debug/aegis --log-level debug daemon start

Verify config:

target/debug/aegis config show
target/debug/aegis config validate

Performance Profiling

# Cold-start time
target/debug/aegis agent deploy ./agents/echo/agent.yaml
time target/debug/aegis task execute echo --input "test"

# 10 concurrent tasks
for i in {1..10}; do
    target/debug/aegis task execute echo --input "Test $i" &
done
wait
target/debug/aegis task list --limit 20

# Daemon memory
ps aux | grep aegis

Cleanup

target/debug/aegis daemon stop

for agent_id in $(target/debug/aegis agent list --output json | jq -r '.[].id'); do
    target/debug/aegis agent remove $agent_id
done

cargo clean

Part 2: Docker Integration Testing

Prerequisites: Docker (or Podman), Docker Compose (or podman-compose), Rust toolchain.

Podman as a drop-in replacement -- podman-compose can be used in place of docker compose throughout this section. All docker compose commands below work identically as podman compose (or podman-compose). If using Podman in rootless mode, ensure your user has a valid subuid/subgid mapping and that the Podman socket is active (systemctl --user start podman.socket). For production-style deployment testing with Podman pods, see the aegis-platform-deployment repository.

This section tests the complete Temporal workflow integration: YAML workflow → Rust registration → TypeScript worker → Temporal → gRPC → Rust execution service.

Architecture Overview

YAML Workflow → RegisterWorkflowUseCase (Rust)
                        ↓
              TemporalWorkflowMapper
                        ↓
              PostgreSQL (workflows table)
                        ↓
              TypeScript Worker HTTP API (:3000/register-workflow)
                        ↓
              createWorkflowFromDefinition() (TypeScript)
                        ↓
              Temporal Worker (.workflows object)
                        ↓
              Temporal Client starts workflow
                        ↓
              Activities → gRPC calls to Rust (:50051)
                        ↓
              Results streamed back via Temporal

Pre-flight: Start the Stack

cd aegis-orchestrator/docker
docker compose build       # or: podman compose build
docker compose down -v     # or: podman compose down -v  (remove stale state)
docker compose up -d       # or: podman compose up -d
docker compose ps          # or: podman compose ps

Expected services:

Service	Port(s)
`postgres`	5432
`temporal`	7233
`temporal-ui`	8233
`temporal-worker`	3000
`aegis-runtime`	50051, 8088

Health checks:

docker exec -it aegis-postgres pg_isready   # or: podman exec -it aegis-postgres pg_isready
curl http://localhost:8233          # Temporal UI
curl http://localhost:3000/health   # TypeScript worker
grpcurl -plaintext localhost:50051 list

Hybrid Local/Docker Setup (For Debugging)

Keep Temporal, PostgreSQL, and the TypeScript worker in Docker while running the Orchestrator locally under cargo run:

cd docker
docker compose build               # or: podman compose build
docker compose up -d               # or: podman compose up -d  (everything inc. orchestrator)
# Then stop just the Rust runtime if you want a local binary instead:
# docker compose stop aegis-runtime   (or: podman compose stop aegis-runtime)

Database Verification

psql -h localhost -U aegis -d aegis -c "\dt"
# Expected tables: workflows, workflow_executions, agents, executions, workflow_definitions

psql -h localhost -U aegis -d aegis -c "\dv"
# Expected views: active_workflow_executions, agent_success_rates

Workflow Test Scenarios

All workflow YAML files referenced below are available in the aegis-examples repository under agents/workflows/.

Scenario 1: Echo Workflow (Basic Connectivity)

Tests basic workflow registration and execution.

Register:

cargo run --bin aegis -- --port 8088 workflow deploy agents/workflows/echo-workflow.yaml
# or via HTTP
curl -X POST http://localhost:8088/v1/workflows/register \
  -H "Content-Type: application/yaml" \
  --data-binary @agents/workflows/echo-workflow.yaml

Run:

cargo run --bin aegis -- --port 8088 workflow run echo-test --param message="Hello World!"
# or via Temporal CLI
temporal workflow start \
  --task-queue aegis-task-queue \
  --type aegis_workflow_echo_test \
  --workflow-id test-echo-001 \
  --input '{}'

temporal workflow show --workflow-id test-echo-001

Verification:

Temporal UI at http://localhost:8233 shows a COMPLETED workflow.
DB: SELECT id, name, version FROM workflows WHERE name = 'echo-test';

Scenario 2: Agent Execution (gRPC Bridge)

Tests the Orchestrator → Activity → gRPC → Orchestrator round-trip.

Deploy agent + workflow (manifests in aegis-examples):

cargo run --bin aegis -- --port 8088 agent deploy agents/greeter/agent.yaml
cargo run --bin aegis -- --port 8088 workflow deploy agents/workflows/agent-workflow.yaml

Run:

temporal workflow start \
  --task-queue aegis-task-queue \
  --type aegis_workflow_agent_test \
  --workflow-id test-agent-001 \
  --input '{}'

temporal workflow show --workflow-id test-agent-001 --follow

Expected event sequence:

WorkflowExecutionStarted
ActivityTaskScheduled: executeAgentActivity
ActivityTaskStarted
ExecutionStarted (gRPC stream)
IterationStarted (iteration 1)
IterationCompleted (iteration 1)
ExecutionCompleted
ActivityTaskCompleted
ActivityTaskScheduled: executeSystemCommandActivity
ActivityTaskCompleted
WorkflowExecutionCompleted

Tests the complete iterative refinement loop: generate → execute → validate → refine.

Deploy agents and workflow (manifests in aegis-examples):

cargo run --bin aegis -- --port 8088 agent deploy agents/coder/agent.yaml
cargo run --bin aegis -- --port 8088 agent deploy agents/judges/basic-judge.yaml
cargo run --bin aegis -- --port 8088 workflow deploy agents/workflows/100monkeys-classic.yaml

Run:

cargo run --bin aegis -- --port 8088 workflow run 100monkeys-classic \
  --input '{"agent_id":"coder","task":"Create a fibonacci function in Python","command":"python fib.py"}'

temporal workflow show --workflow-id <WORKFLOW_ID> --follow

Expected iteration flow:

Iteration	Phase	Notes
1	GENERATE	Agent writes initial code (may have bugs)
1	EXECUTE	Runs code; captures exit code + output
1	VALIDATE	Judge scores 0.0–1.0
1	REFINE	If score < 0.70 → loop back to GENERATE
2	GENERATE	Agent incorporates previous error context
2	VALIDATE	Score ≥ 0.70 → transition to COMPLETE

Scenario 4: Multi-Judge Consensus

Tests parallel agent execution and weighted consensus validation. Manifest: agents/workflows/multi-judge.yaml in aegis-examples.

Run:

curl -X POST http://localhost:8088/v1/workflows/register \
  -H "Content-Type: application/yaml" \
  --data-binary @agents/workflows/multi-judge.yaml

temporal workflow start \
  --task-queue aegis-task-queue \
  --type aegis_workflow_multi_judge_test \
  --workflow-id test-multi-judge-001 \
  --input '{}'

temporal workflow show --workflow-id test-multi-judge-001 --follow

What to verify:

Three judge activities run in parallel.
Weighted consensus is calculated: (w1·s1 + w2·s2 + w3·s3) / Σw.
Workflow branches to APPROVED or REJECTED based on threshold.

Scenario 5: Human-in-the-Loop

Tests signal-based human input. Manifest: agents/workflows/human-approval.yaml in aegis-examples.

temporal workflow start \
  --task-queue aegis-task-queue \
  --type aegis_workflow_human_approval_test \
  --workflow-id test-human-001 \
  --input '{}'

# Workflow pauses at REQUEST_APPROVAL state; send a signal to unblock it
temporal workflow signal \
  --workflow-id test-human-001 \
  --name humanInput \
  --input '"yes"'

temporal workflow show --workflow-id test-human-001

Scenario 6: Volume Management & File System Handoff

Tests shared-volume multi-agent workflows via the SeaweedFS-backed NFS gateway. Manifest: agents/workflows/volume-handoff-test.yaml in aegis-examples.

Verify SeaweedFS is healthy:

docker compose ps | grep seaweedfs             # or: podman compose ps | grep seaweedfs
curl -f http://localhost:8888/ && echo "✓ Filer healthy"
curl http://localhost:9333/cluster/status | jq

Run the workflow:

cargo run --bin aegis -- --port 8088 workflow deploy agents/workflows/volume-handoff-test.yaml

temporal workflow start \
  --task-queue aegis-task-queue \
  --type aegis_workflow_volume_handoff_test \
  --workflow-id test-volume-handoff-001 \
  --input '{}'

temporal workflow show --workflow-id test-volume-handoff-001 --follow

What to verify (in order):

VolumeManager creates workspace volume; metadata appears in PostgreSQL.
SeaweedFS directory created under /aegis/volumes/{tenant_id}/{volume_id}.
CODER agent mounts the volume via NFS and writes calculator.py.
TESTER agent re-attaches the same volume and reads CODER's output.
After completion, volume marked for cleanup; VolumeExpired / VolumeDeleted events appear in domain_events.

Volume lifecycle DB queries:

psql -h localhost -U aegis -d aegis -c \
  "SELECT id, name, remote_path, status, expires_at FROM volumes ORDER BY created_at DESC LIMIT 5;"

psql -h localhost -U aegis -d aegis -c \
  "SELECT event_type, event_data->>'volume_id', created_at FROM domain_events WHERE event_type LIKE 'Volume%' ORDER BY created_at DESC LIMIT 10;"

Scenario 7: Cortex Pattern Learning

Verifies that the Holographic Cortex captures pattern-discovery events during a validation-heavy workflow.

Run 100monkeys-classic with a task that forces at least one refinement:

cargo run --bin aegis -- --port 8088 workflow run 100monkeys-classic \
  --input '{"agent_id":"coder","task":"Write a Python function to calculate factorial","command":"python factorial.py"}'

Watch for Cortex events in the output:

[2026-02-14 12:00:02] Cortex Event: PatternDiscovered { pattern_id: "...", execution_id: "...", ... }

Or subscribe to the raw event stream:

curl -N http://localhost:8088/v1/executions/<AGENT_EXECUTION_ID>/events

Expected Outcomes

Infrastructure ✅

All Docker (or Podman) containers healthy.
Temporal UI accessible at http://localhost:8233.
TypeScript worker logs: "Worker is running".
Rust gRPC logs: "gRPC server listening on :50051".

Database ✅

5 tables: workflows, workflow_executions, agents, executions, workflow_definitions.
2 views: active_workflow_executions, agent_success_rates.

Execution ✅

Temporal shows workflows as COMPLETED.
workflow_executions DB rows have non-null completed_at.
Blackboard contains state-level outputs.
Cortex events logged for any iteration that required refinement.

Performance Targets

Metric	Target	Acceptable
Workflow registration	< 500 ms	< 1 s
Simple workflow execution	< 5 s	< 10 s
Agent execution (1 iteration)	< 30 s	< 60 s
Multi-judge consensus	< 90 s	< 180 s
100monkeys loop (2 iterations)	< 120 s	< 300 s
Volume creation	< 2 s	< 5 s
Multi-agent file handoff	< 10 s	< 30 s

Troubleshooting

Temporal worker not connecting

docker ps | grep temporal                          # or: podman ps | grep temporal
telnet localhost 7233
cd docker && docker compose restart temporal       # or: podman compose restart temporal
docker exec aegis-temporal-worker env | grep TEMPORAL  # or: podman exec ...

gRPC connection refused (port 50051)

grpcurl -plaintext localhost:50051 list
docker logs aegis-runtime | grep gRPC              # or: podman logs aegis-runtime | grep gRPC
grpcurl -plaintext -d '{"command":"echo test"}' \
  localhost:50051 aegis.runtime.v1.AegisRuntime/ExecuteSystemCommand

Workflow registration returns 500

psql -h localhost -U aegis -d aegis -c "SELECT 1;"
docker logs aegis-temporal-worker              # or: podman logs aegis-temporal-worker
psql -h localhost -U aegis -d aegis -c "\dt workflow_definitions"

Agent execution times out

psql -h localhost -U aegis -d aegis -c \
  "SELECT name, status FROM agents WHERE name = 'coder';"
curl http://localhost:8088/health
# Increase timeout in workflow YAML: timeout: 120s

Blackboard state not persisting

Verify Handlebars template syntax: {{STATE_NAME.output}}
Confirm the state completed before the value is referenced.
Check aegis workflow logs <EXEC_ID> --verbose for template rendering errors and state transitions.

Cortex methods show "not yet implemented"

This is expected — Cortex stubs return empty results gracefully. No action needed.

SeaweedFS / volume issues

docker logs aegis-seaweedfs-master             # or: podman logs aegis-seaweedfs-master
docker logs aegis-seaweedfs-filer              # or: podman logs aegis-seaweedfs-filer
docker exec -it <agent-container> df -h        # or: podman exec -it <agent-container> df -h
curl http://localhost:8080/status | jq

Protobuf compilation fails

ls proto/aegis_runtime.proto
cargo clean && cargo build --verbose
cat orchestrator/core/build.rs

Quick Reference

# Start / stop full stack (from docker/)
cd docker && docker compose up -d              # or: podman compose up -d
cd docker && docker compose down               # or: podman compose down

# Live logs
docker compose logs -f temporal-worker         # or: podman compose logs -f temporal-worker
docker compose logs -f aegis-runtime           # or: podman compose logs -f aegis-runtime

# PostgreSQL
psql -h localhost -U aegis -d aegis

# Temporal CLI
temporal workflow list
temporal workflow show --workflow-id <ID>
temporal workflow signal --workflow-id <ID> --name <SIGNAL> --input <JSON>

# gRPC
grpcurl -plaintext localhost:50051 list
grpcurl -plaintext -d '...' localhost:50051 <SERVICE>/<METHOD>

# TypeScript worker HTTP API
curl http://localhost:3000/health
curl http://localhost:3000/workflows

# Rust CLI
cargo run --bin aegis -- --port 8088 workflow deploy <YAML>
cargo run --bin aegis -- --port 8088 agent deploy <YAML>
cargo run --bin aegis -- --port 8088 workflow run <NAME> --input '<JSON>'
cargo run --bin aegis -- --port 8088 workflow executions get <EXEC_ID>
cargo run --bin aegis -- --port 8088 workflow signal <EXEC_ID> --response approved
cargo run --bin aegis -- --port 8088 workflow logs <EXEC_ID> --follow --verbose

Local & Integration Testing

On this page