Local Setup

This guide walks through every step to get tx-agent-kit running on your local machine.

1. Clone the repository

git clone <your-repo-url> tx-agent-kit
cd tx-agent-kit

2. Install dependencies

pnpm install

This installs all workspace dependencies across apps and packages. pnpm's workspace protocol ensures packages reference each other correctly.

3. Configure environment

pnpm env:configure

This command copies .env.example to .env (if it does not already exist) and upserts sensible defaults for local development. No external tools are required for this step.

For staging and production deploys, the project uses 1Password CLI (op) to resolve secrets:

4. Start infrastructure

pnpm infra:ensure

This starts the shared local infrastructure via Docker Compose:

The command is idempotent. Running it multiple times will not create duplicate containers. It also works correctly across git worktrees, deriving ports from the worktree to avoid collisions.

5. Start local Temporal runtime

This step requires the Temporal CLI (temporal) on your PATH. Install it via brew install temporal on macOS or follow the Temporal CLI docs.

pnpm temporal:dev:up

This starts a local Temporal dev server on port 7233 (gRPC) and 8233 (UI). The server persists state to .data/temporal/dev-state.db so workflow history survives restarts.

Use pnpm temporal:dev:status to confirm the runtime is healthy.

6. Run database migrations

pnpm db:migrate

This runs Drizzle migrations against your local PostgreSQL instance, creating all tables, triggers, and indexes.

To verify the migration was successful:

pnpm db:studio

This opens Drizzle Studio in your browser, letting you inspect the database schema.

7. Start development servers

pnpm dev

This starts all application servers in development mode:

The web app communicates with the API server via API_BASE_URL. In local development, this defaults to http://localhost:4000.

Verifying the setup

Once all services are running, verify the stack is healthy:

# API health check
curl http://localhost:4000/health

# Run unit tests
pnpm test

# Run linter and type checks
pnpm lint && pnpm type-check

For integration tests (which require running infrastructure):

pnpm test:integration

Integration tests are lock-guarded (/tmp/tx-agent-kit-integration.lock) to prevent overlapping runs from clobbering each other.

Quiet runners

During development iteration, prefer quiet runners to reduce terminal output:

pnpm lint:quiet          # ESLint + structural + shell checks (minimal output)
pnpm type-check:quiet    # TypeScript compilation check (errors only)
pnpm test:quiet          # Unit tests (summary only)
pnpm test:integration:quiet  # Integration tests (summary only)

Switch to the full commands when you need detailed diagnostics.

Troubleshooting

Docker services will not start: Ensure Docker Desktop is running and you have sufficient disk space. Run docker compose ps to check container status.

Database connection refused: Verify PostgreSQL is running (docker compose ps) and the DATABASE_URL in .env points to localhost:5432.

1Password CLI errors: Ensure you are signed in (op signin) and have access to the required vaults.