Deployment

The repository's production topology is docker-compose.yml.

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

Service order

1. Postgres starts and passes pg_isready.
2. The one-shot migration service completes.
3. The server starts on container port 8080.
4. The agent runtime image is built.
5. The worker starts and connects to Postgres and the selected sandbox adapter.

The server is published at ${TASUKU_PORT:-8080}. Put TLS termination and a stable public origin in front of it, then set TASUKU_PUBLIC_URL to that exact external origin.

Agent capacity

Set TASUKU_MAX_CONCURRENT_AGENTS to the lowest concurrency supported by the worker host, sandbox infrastructure, or external agent provider. The default is 1, so additional requests remain queued until the running job finishes.

Each worker process executes one agent at a time. Scale worker replicas to run more agents in parallel, give every replica the same configured limit, and keep the replica count at or above the desired parallelism. PostgreSQL enforces the ceiling across all replicas sharing the database. Lowering the value does not cancel running jobs; workers resume claiming when usage falls below the new limit.

Health checks

The process liveness and dependency readiness endpoints are:

GET /healthz
GET /readyz

/healthz reports that the HTTP process is alive and remains healthy during a transient database outage. /readyz performs a bounded Postgres check and returns unavailable as soon as shutdown begins. Compose uses /readyz every ten seconds after startup. Postgres also has its own readiness check. The worker is monitored through process state, structured logs, queue progress, and workflow/task timestamps rather than an HTTP endpoint.

Persistent state

The Compose topology stores Postgres in the tasuku-postgres named volume. The server and worker are replaceable; Postgres plus the matching master key are not.

Docker execution

The production worker mounts /var/run/docker.sock and joins ${DOCKER_GID:-0} so the Docker adapter can create agent containers. Treat the worker host as privileged infrastructure.

For Daytona or Lambda, configure the corresponding adapter and credentials. The current Compose file still builds the local runtime image, but effective repository configuration selects the provider used for a task.

Upgrade procedure

1. Back up Postgres and separately confirm the saved master key.
2. Build the new images.
3. Run the migration service.
4. Replace server and worker containers.
5. Verify /healthz and /readyz, worker startup, queue progress, OAuth, and a test repository workflow.

Never restore a database without the complete matching active and previous master-key ring. Use the master-key rotation runbook for planned changes.