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-failureThe 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: 30If 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
| Variable | Description | Default |
|---|---|---|
TEMPORAL_ADDRESS | Temporal Server gRPC address | localhost:7233 |
TEMPORAL_NAMESPACE | Temporal namespace | default |
TEMPORAL_TASK_QUEUE | Task queue name (must match orchestrator config) | aegis-agents |
DATABASE_URL | PostgreSQL connection string (same DB as the orchestrator) | — |
AEGIS_RUNTIME_GRPC_URL | Rust AegisRuntime gRPC address | localhost:50051 |
AEGIS_ORCHESTRATOR_URL | Base URL of the Rust HTTP API (for event publishing) | http://localhost:8080 |
PORT | HTTP server port for workflow registration and health endpoints | 3000 |
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:
| Variable | Description | Default |
|---|---|---|
AEGIS_RUNTIME_GRPC_KEEPALIVE_TIME_MS | Time after the last answered ping before the next ping, with or without calls in flight | 10000 |
AEGIS_RUNTIME_GRPC_KEEPALIVE_TIMEOUT_MS | How long a ping may go unanswered before the connection is dropped | 5000 |
AEGIS_RUNTIME_GRPC_MAX_RECONNECT_BACKOFF_MS | Longest wait between two reconnection attempts while the orchestrator is unreachable | 5000 |
AEGIS_RUNTIME_GRPC_DNS_MIN_TIME_BETWEEN_RESOLUTIONS_MS | Shortest time between two lookups of the orchestrator's name | 5000 |
AEGIS_RUNTIME_GRPC_CONNECT_TIMEOUT_MS | How long a call waits for a connection before it fails as UNAVAILABLE, which Temporal retries | 60000 |
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:
| Variable | Description | Default |
|---|---|---|
AEGIS_EXECUTION_FALLBACK_IDLE_MS | How long the stream may stay quiet, in milliseconds, before the status is polled | 5000 |
AEGIS_EXECUTION_FALLBACK_POLL_MS | The first wait between two polls, in milliseconds; each later wait is twice the one before | 1000 |
AEGIS_EXECUTION_FALLBACK_MAX_POLL_MS | The longest wait between two polls, in milliseconds | 30000 |
AEGIS_EXECUTION_FALLBACK_MAX_RETRIES | Unset 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-failureRunning Locally
cd aegis-temporal-worker
cp .env.example .env # fill in the required variables
npm install
npm startStartup Behaviour
On startup, the worker:
- Connects to PostgreSQL and runs any pending
workflow_definitionstable migrations. - Loads all registered workflow definitions from the
workflow_definitionstable into its in-memory registry. - Begins polling the
aegis-agentsTemporal 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 --verboseThe 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=2Each 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-agentstask 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.
Caddy Edge Proxy
Reverse proxy configuration with Caddy for production AEGIS deployments — automatic TLS, domain routing, and Cloudflare DNS-01.
SeaweedFS Storage
Deploying SeaweedFS as the AEGIS volume storage backend — single-node dev setup, production HA topology, replication, S3 gateway, and health checks.