Skip to main content

Getting started Preview

Preview

The Temporal worker and API starter repos referenced below are still hardening before their OSS release — the git clone URLs in this walkthrough will start working once those repos are published. Mechanics, configuration, and verification steps are accurate today. BAH internal readers can substitute the internal mirror URL.

This guide walks through standing up the full local stack from scratch. By the end you'll have four services running together:

ServiceURLDescription
Temporal Serverhttp://localhost:8080 (UI), localhost:7233 (gRPC)Open-source Temporal orchestration engine
Workflow Worker— (no exposed port, connects to Temporal)Executes workflows and activities
Workflow APIhttp://localhost:8000FastAPI gateway for starting/managing workflows
Mock Agenthttp://localhost:8081Simulated Strands agent for local development

The mock agent is swapped for the real Foundry Strands Base Agent in the next walkthrough.

Architecture overview​

┌─────────────────────┐       ┌──────────────────────────┐
│   Workflow API       │       │   Temporal Server         │
│   (FastAPI)          │──────▶│   (PostgreSQL-backed)     │
│   localhost:8000     │       │   gRPC: localhost:7233    │
└─────────────────────┘       │   UI:   localhost:8080    │
                               └──────────┬───────────────┘
                                          │
                               ┌──────────▼───────────────┐
                               │   Workflow Worker         │
                               │   (temporal-network)      │
                               │   Polls task queue        │
                               └──────────┬───────────────┘
                                          │
                               ┌──────────▼───────────────┐
                               │   Mock Strands Agent      │
                               │   localhost:8081          │
                               └──────────────────────────┘

Prerequisites​

macOS (Rancher Desktop)​

  1. Rancher Desktop — provides Docker and Docker Compose. Download from rancherdesktop.io. During setup, select dockerd (moby) as the container runtime. Then verify:

    docker --version
    docker compose version

  2. Git, Python 3.11+ (3.13 recommended), uv:

    git --version
    python3 --version
    curl -LsSf https://astral.sh/uv/install.sh | sh

  3. Just command runner (optional but recommended):

    brew install just

Windows (WSL2)​

  1. WSL2 with Ubuntu:

    # In PowerShell (Administrator)
    wsl --install -d Ubuntu

    Reboot, then continue in the Ubuntu terminal.

  2. Docker Engine inside WSL2 — Rancher Desktop with WSL integration enabled (recommended), or Docker Engine directly:

    sudo apt update && sudo apt install -y docker.io docker-compose-plugin
    sudo usermod -aG docker $USER
    newgrp docker

  3. Git, Python, uv, Just inside WSL2:

    sudo apt update && sudo apt install -y git python3 python3-pip python3-venv
    curl -LsSf https://astral.sh/uv/install.sh | sh
    curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/bin
    echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

  4. Verify everything:

    docker --version && docker compose version
    git --version && python3 --version && uv --version && just --version

Step 1 — Clone the repositories​

Three repos go side-by-side in a workspace directory:

mkdir -p ~/agent-foundry-workspace && cd ~/agent-foundry-workspace

# 1. Temporal Server (open-source docker-compose setup)
git clone https://github.com/temporalio/docker-compose.git temporalio/docker-compose

# 2. Workflow Worker Starter (preview — URL will resolve once the repo is published)
git clone https://github.com/boozallen/temporal-workflow-worker-starter.git

# 3. Workflow API Starter (preview — URL will resolve once the repo is published)
git clone https://github.com/boozallen/temporal-workflow-api-starter.git

The directory should look like:

agent-foundry-workspace/
├── temporalio/
│   └── docker-compose/                ← Open-source Temporal Server
├── temporal-workflow-worker-starter/  ← Worker template (preview)
└── temporal-workflow-api-starter/     ← API template (preview)

Step 2 — Start the Temporal Server​

The Temporal Server is the backbone. It must be running before the worker or API can connect.

2.1 Create the environment file​

cd ~/agent-foundry-workspace/temporalio/docker-compose

Create a file named .env:

COMPOSE_PROJECT_NAME=temporal
TEMPORAL_VERSION=1.29.1
TEMPORAL_ADMINTOOLS_VERSION=1.29.1-tctl-1.18.4-cli-1.5.0
TEMPORAL_UI_VERSION=2.34.0
POSTGRESQL_VERSION=16
POSTGRES_PASSWORD=temporal
POSTGRES_USER=temporal
POSTGRES_DEFAULT_PORT=5432

Check Temporal's releases page for newer stable version numbers.

2.2 Start the server​

docker compose -f docker-compose-postgres.yml up -d

This launches four containers:

ContainerPurpose
temporal-postgresqlPostgreSQL database for Temporal state
temporalTemporal Server (auto-setup with schema migration)
temporal-admin-toolsCLI tools for administration
temporal-uiWeb UI for monitoring workflows

If image pulls fail with toomanyrequests, see Troubleshooting.

2.3 Verify​

Wait ~30 seconds, then:

docker compose -f docker-compose-postgres.yml ps
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080
# → 200

Open http://localhost:8080 — the Temporal Web UI should load.

2.4 Confirm the Docker network​

docker network ls | grep temporal
# → temporal-network

The worker joins this network in the next step.

Step 3 — Start the Workflow Worker​

The worker registers workflows and activities with Temporal and executes them when triggered.

3.1 Configure​

cd ~/agent-foundry-workspace/temporal-workflow-worker-starter
cp env.template .env

Defaults work for local development:

TEMPORAL_HOST=host.docker.internal:7233
TEMPORAL_NAMESPACE=default
TASK_QUEUE=workflow-task-queue
WORKER_IDENTITY=worker-1

host.docker.internal is a Docker-provided DNS name that resolves to the host machine. The worker container uses it to reach Temporal on the host's port 7233.

3.2 Start the worker and mock agent​

just start
# or: docker compose up -d

Two containers come up on temporal-network:

ContainerPurposePort
workerTemporal workflow worker — polls the task queue— (internal)
mock-strands-agentMock A2A JSON-RPC agent for local development8081 (host)

3.3 Verify​

docker compose ps
curl http://localhost:8081/health
# → {"status":"healthy","agent":"mock-strands-agent",...}

docker compose logs -f worker

Worker logs should include:

  • Loaded workflow: MyWorkflow from src.workflows
  • Loaded activity: my_activity from src.activities
  • Temporal worker started successfully

Ctrl+C stops following the logs.

Step 4 — Start the Workflow API​

The API is a FastAPI REST gateway for starting and managing workflows.

4.1 Configure​

cd ~/agent-foundry-workspace/temporal-workflow-api-starter
cp env.template .env

Defaults:

API_HOST=0.0.0.0
API_PORT=8000
LOG_LEVEL=INFO
TEMPORAL_HOST=host.docker.internal:7233
TEMPORAL_NAMESPACE=default
TEMPORAL_TASK_QUEUE=workflow-task-queue

4.2 Start​

just start
# or: docker compose up -d

4.3 Verify​

docker compose ps
curl http://localhost:8000/health/
# → {"status":"healthy",...}

curl http://localhost:8000/health/detailed

Open http://localhost:8000/docs for the interactive Swagger UI.

Step 5 — Verify the full stack​

5.1 Health-check all three​

echo "--- Temporal UI ---"
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:8080

echo "--- Workflow API ---"
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:8000/health/

echo "--- Mock Agent ---"
curl -s -o /dev/null -w "HTTP %{http_code}\n" http://localhost:8081/health

All three should return HTTP 200.

5.2 Start a test workflow​

curl -X POST http://localhost:8000/workflows/start \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_type": "MyWorkflow",
    "workflow_id": "test-workflow-001",
    "args": [{"message": "Hello from end-to-end test", "processing_type": "standard"}]
  }'

5.3 Monitor in the Temporal UI​

  1. Open http://localhost:8080.
  2. Select the default namespace.
  3. The workflow test-workflow-001 should appear. Click it for execution history, step-by-step events, and pending signals.

Common operations​

View logs​

# Worker
cd ~/agent-foundry-workspace/temporal-workflow-worker-starter
docker compose logs -f

# API
cd ~/agent-foundry-workspace/temporal-workflow-api-starter
docker compose logs -f

# Temporal Server
cd ~/agent-foundry-workspace/temporalio/docker-compose
docker compose -f docker-compose-postgres.yml logs -f

Stop everything (preserve data)​

Stop in reverse order — API first:

cd ~/agent-foundry-workspace/temporal-workflow-api-starter && docker compose down
cd ~/agent-foundry-workspace/temporal-workflow-worker-starter && docker compose down
cd ~/agent-foundry-workspace/temporalio/docker-compose && docker compose -f docker-compose-postgres.yml down

Reset everything (remove data and volumes)​

cd ~/agent-foundry-workspace/temporal-workflow-api-starter && docker compose down -v
cd ~/agent-foundry-workspace/temporal-workflow-worker-starter && docker compose down -v --remove-orphans
cd ~/agent-foundry-workspace/temporalio/docker-compose && docker compose -f docker-compose-postgres.yml down -v

Restart from scratch​

# 1. Temporal Server
cd ~/agent-foundry-workspace/temporalio/docker-compose
docker compose -f docker-compose-postgres.yml up -d
sleep 30

# 2. Worker
cd ~/agent-foundry-workspace/temporal-workflow-worker-starter && just start

# 3. API
cd ~/agent-foundry-workspace/temporal-workflow-api-starter && just start

Troubleshooting​

Docker Hub rate limiting​

toomanyrequests: You have reached your pull rate limit.

Unauthenticated pulls share rate limits across IPs, so a busy corporate network exhausts the quota quickly. Options:

  1. docker login with a Docker Hub account.
  2. Retry later — the limit resets on a 24-hour basis. Once images are cached locally this stops being an issue.
  3. Use an internal registry proxy if your organization provides one.

Docker is not running​

ERROR: Cannot connect to the Docker daemon
  • macOS: open Rancher Desktop and check the tray icon.
  • Windows/WSL2: start Rancher Desktop with WSL integration enabled, or sudo service docker start.

Port conflicts​

If you see bind: address already in use:

PortUsed byResolution
5432PostgreSQLbrew services stop postgresql
7233Temporal gRPCpkill temporal
8000Workflow APIlsof -ti:8000 | xargs kill
8080Temporal UIlsof -ti:8080 | xargs kill
8081Mock Agentlsof -ti:8081 | xargs kill

Worker can't connect to Temporal​

Failed to connect to Temporal server at host.docker.internal:7233

  1. Temporal Server is up: docker compose -f docker-compose-postgres.yml ps.

  2. The shared network exists: docker network ls | grep temporal-network.

  3. The worker's compose.yaml joins it:

    networks:
      temporal-network:

API can't connect to Temporal​

The API container uses host.docker.internal:7233. If this doesn't resolve:

  • macOS/Rancher Desktop — supported by default.

  • Linux/WSL2 — add to the API's compose.yaml:

    services:
      api:
        extra_hosts:
          - "host.docker.internal:host-gateway"

Temporal UI shows no workflows​

  • View the default namespace.
  • Check worker logs to confirm it registered and connected.
  • Start a workflow through the API and refresh.

Service reference​

Temporal Server​

ItemValue
Compose filetemporalio/docker-compose/docker-compose-postgres.yml
Environment filetemporalio/docker-compose/.env
gRPC endpointlocalhost:7233
Web UIhttp://localhost:8080
DatabasePostgreSQL 16 on port 5432
Docker networktemporal-network

Workflow Worker Starter​

ItemValue
Compose filetemporal-workflow-worker-starter/compose.yaml
Environment filetemporal-workflow-worker-starter/.env
Task queueworkflow-task-queue
Mock agenthttp://localhost:8081
Docker networktemporal-network
just commandssetup, start, logs, status, reset, test, check

Workflow API Starter​

ItemValue
Compose filetemporal-workflow-api-starter/compose.yaml
Environment filetemporal-workflow-api-starter/.env
API endpointhttp://localhost:8000
Swagger docshttp://localhost:8000/docs
ReDoc docshttp://localhost:8000/redoc
just commandssetup, start, stop, logs, dev, test, check

What's next​

Ready to replace the mock agent with a real LLM-powered Strands Base Agent? Continue with Swap in a real agent.