Aegis Orchestrator
Deployment

Temporal Deployment

Running Temporal Server, the TypeScript workflow worker, and PostgreSQL for durable workflow execution in AEGIS.

Temporal Deployment

AEGIS uses Temporal as the durable execution backend for all workflow FSM execution. Two additional services are required beyond the Rust orchestrator itself: Temporal Server and the TypeScript workflow worker (aegis-temporal-worker). Both connect to the same PostgreSQL instance used by the orchestrator.


Prerequisites

  • PostgreSQL 14+ accessible from all services
  • Docker Engine (for the recommended Compose deployment) or equivalent container runtime
  • The Rust AEGIS orchestrator configured and running (see Docker Deployment)

Running Temporal Server

Temporal Server stores durable workflow state in PostgreSQL. Run it alongside its required dependencies:

# docker-compose.temporal.yaml

services:
  temporal:
    image: temporalio/auto-setup:1.24
    ports:
      - "7233:7233"
    environment:
      - DB=postgresql
      - DB_PORT=5432
      - POSTGRES_USER=${POSTGRES_USER:-aegis}
      - POSTGRES_PWD=${POSTGRES_PASSWORD}
      - POSTGRES_SEEDS=${POSTGRES_HOST:-postgres}
      - TEMPORAL_BROADCAST_ADDRESS=127.0.0.1
    depends_on:
      - postgres
    restart: on-failure

  temporal-ui:
    image: temporalio/ui:2.26
    ports:
      - "8233:8080"
    environment:
      - TEMPORAL_ADDRESS=temporal:7233
      - TEMPORAL_CORS_ORIGINS=http://localhost:8233
    depends_on:
      - temporal
    restart: on-failure

The auto-setup image automatically creates the Temporal schema in PostgreSQL on first start. The UI is available at http://localhost:8233.

Configure the orchestrator to reach Temporal by setting the following in aegis-config.yaml:

temporal:
  address: "localhost:7233"   # or temporal:7233 inside Compose
  namespace: "default"
  task_queue: "aegis-agents"
  max_connection_retries: 30

If spec.temporal.max_connection_retries is omitted, the orchestrator retries Temporal client connection setup 30 times before failing startup.


Running the TypeScript Worker

The aegis-temporal-worker service polls the aegis-agents task queue and interprets all AEGIS workflow FSM definitions. It must be running for any workflow execution to make progress.

Required Environment Variables

VariableDescriptionDefault
TEMPORAL_ADDRESSTemporal Server gRPC addresslocalhost:7233
TEMPORAL_NAMESPACETemporal namespacedefault
TEMPORAL_TASK_QUEUETask queue name (must match orchestrator config)aegis-agents
DATABASE_URLPostgreSQL connection string (same DB as the orchestrator)—
AEGIS_RUNTIME_GRPC_URLRust AegisRuntime gRPC addresslocalhost:50051
AEGIS_ORCHESTRATOR_URLBase URL of the Rust HTTP API (for event publishing)http://localhost:8080
PORTHTTP server port for workflow registration and health endpoints3000

The Worker's Connection to the Orchestrator

The worker pings the orchestrator over its gRPC connection, drops a connection that does not answer, looks up the orchestrator's name again and reconnects, so a replaced orchestrator (a new pod or container at the same name) is reached again without restarting the worker. These optional variables tune it; each takes a positive whole number of milliseconds:

VariableDescriptionDefault
AEGIS_RUNTIME_GRPC_KEEPALIVE_TIME_MSTime after the last answered ping before the next ping, with or without calls in flight10000
AEGIS_RUNTIME_GRPC_KEEPALIVE_TIMEOUT_MSHow long a ping may go unanswered before the connection is dropped5000
AEGIS_RUNTIME_GRPC_MAX_RECONNECT_BACKOFF_MSLongest wait between two reconnection attempts while the orchestrator is unreachable5000
AEGIS_RUNTIME_GRPC_DNS_MIN_TIME_BETWEEN_RESOLUTIONS_MSShortest time between two lookups of the orchestrator's name5000
AEGIS_RUNTIME_GRPC_CONNECT_TIMEOUT_MSHow long a call waits for a connection before it fails as UNAVAILABLE, which Temporal retries60000

How the Worker Runs an Agent State

An Agent state's run is given the agent's own time limit (spec.security.resources.timeout, else 1,800 seconds) plus 60 seconds. The worker heartbeats the step every 30 seconds while the run streams, and the step is considered lost after 2 minutes without one. A run is started once per step: a retry after the run has begun cancels that run and fails the step instead of starting another, and a step that ends first, by its limit or by cancellation, asks the orchestrator to cancel its run (POST /v1/executions/{id}/cancel, naming the run's tenant). A refused cancel is logged and does not fail the step.

When a run's event stream goes quiet, the worker falls back to polling the run's stored status. It polls until the run reaches a terminal state or until the run's deadline, the step's time limit plus 60 seconds; past the deadline it asks the orchestrator to cancel the run and fails the step with "Execution status polling exhausted at the run's deadline …". These optional variables tune the fallback; each takes a whole number:

VariableDescriptionDefault
AEGIS_EXECUTION_FALLBACK_IDLE_MSHow long the stream may stay quiet, in milliseconds, before the status is polled5000
AEGIS_EXECUTION_FALLBACK_POLL_MSThe first wait between two polls, in milliseconds; each later wait is twice the one before1000
AEGIS_EXECUTION_FALLBACK_MAX_POLL_MSThe longest wait between two polls, in milliseconds30000
AEGIS_EXECUTION_FALLBACK_MAX_RETRIESUnset by default. When set, the most polls before the step fails; a step failed by this bound cancels nothing—

How the Worker Fires a Schedule

Each schedule is a Temporal Schedule that starts the worker's aegis_schedule_fire workflow. Its one activity posts the scheduled time to the orchestrator, which decides the fire and starts the run; it makes at most three attempts, 30 and then 60 seconds apart, each bounded to 30 seconds. The worker's service account must be the orchestrator's aegis-temporal-worker client: the orchestrator refuses a fire from any other caller.

Docker Compose

  aegis-temporal-worker:
    image: ghcr.io/100monkeys-ai/aegis-temporal-worker:latest
    ports:
      - "3000:3000"
    environment:
      TEMPORAL_ADDRESS: "temporal:7233"
      TEMPORAL_NAMESPACE: "default"
      TEMPORAL_TASK_QUEUE: "aegis-agents"
      DATABASE_URL: "postgresql://aegis:${POSTGRES_PASSWORD}@postgres:5432/aegis"
      AEGIS_RUNTIME_GRPC_URL: "aegis-orchestrator:50051"
      AEGIS_ORCHESTRATOR_URL: "http://aegis-orchestrator:8080"
    depends_on:
      - temporal
      - postgres
    restart: on-failure

Running Locally

cd aegis-temporal-worker
cp .env.example .env   # fill in the required variables
npm install
npm start

Startup Behaviour

On startup, the worker:

  1. Connects to PostgreSQL and runs any pending workflow_definitions table migrations.
  2. Loads all registered workflow definitions from the workflow_definitions table into its in-memory registry.
  3. Begins polling the aegis-agents Temporal task queue.

Because all definitions are loaded at startup from the shared PostgreSQL table, multiple worker replicas can run concurrently — any replica can execute any workflow regardless of which node originally registered it.


Verifying the Setup

1. Health check

curl http://localhost:3000/health
# {"status":"healthy","temporal":"connected","database":"connected"}

2. Check Temporal UI

Open http://localhost:8233. Navigate to Workers → task queue aegis-agents. You should see at least one active poller listed.

3. Register and run a workflow

# Deploy the example echo workflow
aegis workflow deploy ./aegis-examples/agents/workflows/echo-workflow.yaml

# Start an execution
aegis workflow run echo-workflow --input '{"message": "hello"}'

# Inspect and watch the execution
aegis workflow executions get <execution-id>
aegis workflow logs <execution-id> --follow --verbose

The execution should appear in the Temporal UI under Workflows with status Running and then Completed.


Registered Workflow Definitions

The worker exposes a management HTTP API on its PORT:

# List all registered workflow definitions
curl http://localhost:3000/workflows

# Get a specific definition by workflow ID
curl http://localhost:3000/workflows/<workflow-id>

# Remove a definition (does not affect in-progress executions)
curl -X DELETE http://localhost:3000/workflows/<workflow-id>

When aegis workflow deploy is run, the Rust orchestrator registers the serialized FSM via its workflow registration API and simultaneously saves the Workflow domain aggregate to PostgreSQL.


Scaling

Run additional worker replicas by starting more instances pointing at the same TEMPORAL_ADDRESS, DATABASE_URL, and TEMPORAL_TASK_QUEUE. Temporal distributes workflow tasks across all pollers in the task queue automatically.

# Example: two replicas via Compose scale
docker compose up --scale aegis-temporal-worker=2

Each replica loads the full workflow_definitions registry from PostgreSQL on startup, so no sticky routing is required.


Temporal Namespace Configuration

AEGIS uses the default Temporal namespace. For multi-tenant production deployments, dedicated namespaces can be provisioned via the tctl CLI:

tctl --address localhost:7233 namespace register aegis-production \
  --retention 30d \
  --description "AEGIS production workflows"

Update temporal.namespace in aegis-config.yaml and restart the orchestrator and worker.


Temporal UI

The Temporal UI at http://localhost:8233 provides full observability into all workflow executions:

  • Workflows — list all executions with status, start time, and duration
  • Workers — confirm active pollers on the aegis-agents task queue
  • Schedules — manage scheduled workflow starts (if used)
  • Execution detail — full event history for any execution, including Blackboard state at each transition, input/output of each activity, and any failures or retries

The Temporal UI remains the authoritative raw engine view, while aegis workflow logs provides the AEGIS domain-event view with workflow names, states, and iteration metadata.

On this page