Infrastructure Overview

tx-agent-kit splits infrastructure into two layers: shared services managed by Docker Compose, and application processes run as local Node.js processes during development.

Shared infrastructure (Docker)

All backing services run inside Docker containers through a single docker-compose.yml with the infra profile. These services are shared across all git worktrees.

The pnpm infra:ensure command starts all services idempotently. If they are already running, it exits immediately. Services are health-checked before the command returns.

Temporal runtime is managed separately:

• Local: pnpm temporal:dev:up starts host Temporal CLI (TEMPORAL_RUNTIME_MODE=cli).
• Deployed environments: TEMPORAL_RUNTIME_MODE=cloud with Temporal Cloud address/namespace/API key.

Application processes (local Node.js)

During development, applications run as local Node.js processes managed by Turborepo.

This split is intentional. Infrastructure services are long-lived and shared; application code changes frequently and benefits from fast local reload.

Why not Docker for everything?

Running applications inside containers during development adds friction: slower rebuilds, volume mount overhead, and debugging complexity. By keeping infra in Docker and apps as local processes, you get the reliability of containerized services with the speed of native Node.js hot-reload.

In staging and production, applications are deployed as container images. The deploy:build-images script builds immutable images for api and worker. See Deployment for details.

Quick start

# Configure local environment variables
pnpm env:configure

# Start Docker infrastructure
pnpm infra:ensure

# Start local Temporal runtime
pnpm temporal:dev:up

# Run database migrations
pnpm db:migrate

# Start all applications
pnpm dev

Related pages