Running and workers

> For operators who need to know what Agent Taskbay's processes do, how to run the worker separately, and how to tell whether it is healthy.

Taskbay has a web server and a set of background loops (the "worker"). The browser never drives agent work: a send is saved first, then the worker delivers it, watches the task and records what comes back. That is why you can close the browser and the task keeps being tracked. The mechanism is explained in Durable tasks; this page is the operator's view.

Before you startCopy Anchor Link

• A source checkout with npm ci and npm run build done. Keep the development dependencies: the worker runs under tsx.
• For a separate worker: a PostgreSQL database, A2A_DATABASE_PROFILE=postgresql and A2A_DATABASE_URL set, and migrations applied with npm run db:migrate. Workers never migrate.
• One environment shared by the web server and every worker. The full procedure is in Production deployment; ready-made variable sets are in Configuration recipes.
• A process supervisor that restarts both processes.

Two ways to runCopy Anchor Link

Details:

• Embedded mode needs a long-running Node server. A serverless or scale-to-zero host will not run the loops reliably.
• External mode requires PostgreSQL. With PGlite the web server fails at start with External command workers require PostgreSQL., and the worker script refuses with The separate worker requires PostgreSQL; PGlite uses embedded dispatch. PGlite allows one process to own its data directory.
• Any other value for the mode fails at start with Invalid A2A_COMMAND_WORKER_MODE.
• The worker needs the same database, artifact directory and server configuration as the web server (see Production deployment). It also needs NODE_ENV=production in its own environment: next start sets it for web, but the worker runs under tsx and does not.
• worker:commands is an alias for worker:tasks; both run scripts/command-worker.ts.

Stop a worker with SIGTERM or SIGINT. It stops each loop, waits for the current step, closes the database connection and exits.

Start the web server and a separate workerCopy Anchor Link

Export the shared environment in the shell or the service definition of both processes. Both also read .env.production.local, .env.local, .env.production and .env from the working directory; values already in the environment win. Set at least:

export NODE_ENV=production A2A_COMMAND_WORKER_MODE=external A2A_DATABASE_PROFILE=postgresql

export A2A_DATABASE_URL=postgresql://taskbay:PASSWORD@db.internal:5432/taskbay

Start the web server (next start -p 3002):

npm start

In a second terminal or service, start the worker (worker:commands runs the same script):

npm run worker:tasks

Add more workers by starting the same command again, on the same or another host.

A worker that started correctly prints nothing: the script has no startup message, and it writes to the log only when something fails. To confirm it is working, send a message and follow the command (see Health signals). If the worker exits immediately, read the first line of its error output and look it up in When it fails.

What each loop doesCopy Anchor Link

All loops are idempotent and retry after a database error, logging a single line and trying again.

The browser side: GET /api/tasks/events is a server-sent-events stream that sends ready, then freshness when something committed and resync about every 15 seconds. It closes itself after 55 seconds and the browser reconnects. It carries no task content; the browser re-reads state from the API. With PostgreSQL, web replicas poll a freshness token every 500 ms, so a change made by a worker on another host shows up without a message broker.

Scaling and leasesCopy Anchor Link

Any number of workers can share a database. Each unit of work (a command, a subscription, a push registration, a reconciliation cursor) is claimed with a time-limited lease and renewed in the background about three times per lease. If a worker dies, its leases expire and another worker takes the work over: streams after 15 seconds, command dispatch after 60 seconds. A worker that loses a lease stops and discards its result rather than writing it. The lease errors are not printed as such; the loop logs its generic ... could not access durable state; will retry. line. For a command whose dispatch lease expired, the worker that takes it over marks it uncertain with A previous dispatch lease expired. Remote outcome requires reconciliation. instead of sending it again.

The 8-stream cap is per process. If you track many simultaneously active tasks, add worker processes. Nothing in this repository measures throughput, so there are no capacity numbers.

Health signalsCopy Anchor Link

There is no health endpoint and no metrics export. What you have:

Log lines the loops print on a database or lease problem, one per failed pass:

Command dispatcher could not access durable state; will retry.
Subscription worker could not access durable state; will retry.
Push worker could not access durable state; will retry.
Reconciliation worker could not access durable state; will retry.
Freshness dispatcher could not access durable state; will retry.
Decision sweeper could not access durable state; will retry.
Escalation sweeper could not access durable state; will retry.
Notification fan-out could not access durable state; will retry.
Notification delivery could not access durable state; will retry.

A single line is noise. The same line repeating means the process cannot reach PostgreSQL or the schema is wrong; check Troubleshooting.

Configuration that affects workersCopy Anchor Link

The complete list is in the configuration reference.

When it failsCopy Anchor Link

More symptoms: Troubleshooting.

LimitsCopy Anchor Link

• Workers have no human identity; they act as the system, which is why accepted work continues after a person signs out or loses access.
• No per-loop switches. The external worker always runs every loop.
• No dashboards for leases, queue depth or cursors. A user-facing view of reconciliation cursors is not built.
• Uncertain commands need a human to check the task on the agent. Taskbay will not resend them.

Further readingCopy Anchor Link

Decision record: command dispatch and the local worker.

RelatedCopy Anchor Link

• Troubleshooting
• Production deployment
• Configuration recipes
• Durable tasks
• Configuration reference