Configuration & Messaging
A worker reads all of its configuration from environment variables. Those variables live in an environment file on the worker host, and the platform edits it for you from the Environment sub-page — the file is never part of your repository.
The Environment Page
Open a worker, then click Environment. The page loads the live .env from the running
worker and shows it as editable text.
| Control | What it does |
|---|---|
| Load .env / Reload | Fetches the current file from the worker host |
| Prefill recommended values | Fills in the connection settings the platform already knows |
| Save .env | Validates, then writes the whole file back |
The page auto-loads once the worker is active. Before that there’s no process to read from, and the controls stay disabled.
Values are shown in full, not masked, so that saving an unchanged entry can’t
overwrite a real secret with a mask. Treat this page as sensitive and be careful sharing
your screen. Editing requires the create_workers permission; without it the editor is
read-only.
Nothing Is Seeded Automatically
A freshly created worker starts with an empty environment file. That’s what Prefill recommended values is for.
Click Prefill recommended values
The platform fills in the RabbitMQ URL, DaaS URL and token, the project MCP token, and this worker’s identity.
Review what changed
Prefill only writes keys that are missing or empty. Anything you already set is left alone, and the page tells you exactly which keys it added.
Click Save .env
Nothing reaches the worker until you save.
Restart the worker
Changes are picked up on the next restart or deploy, not immediately. See Operating Workers.
Recommended Variables
| Variable | Source | Purpose |
|---|---|---|
RABBITMQ_URL | Project broker | Full AMQP URL, credentials included |
RABBITMQ_MANAGEMENT_URL | Project broker | Web console, for inspecting queues by hand |
WORKER_JOB_TYPES | Defaults to worker.job | Comma-separated job types this worker consumes |
DAAS_URL | Project DaaS backend | Data backend base URL |
DAAS_TOKEN | Minted per request | Bearer token for DaaS calls |
BUILDPAD_MCP_TOKEN | Project MCP token | Platform access for AI tooling |
PROJECT_ID | This project | Worker identity, used as the message source |
WORKER_ID | This worker | Worker identity, used as the message source |
Add your own variables freely — third-party API keys, tuning values, feature switches. Prefill never removes them.
PROJECT_ID and WORKER_ID are also exported into the environment by the platform at
start time, so they’re available even if the file doesn’t list them. Prefill includes them
anyway so local runs behave the same as deployed ones.
Validation Rules
Every meaningful line must be a KEY=VALUE assignment:
- Keys match
[A-Za-z_][A-Za-z0-9_]*— letters, digits, underscores, not starting with a digit - Blank lines and
#comments are ignored - Everything after the first
=is the value, verbatim - A repeated key means the last assignment wins
If any line is malformed, the whole save is rejected with the offending line number and nothing is written — the worker keeps running on its previous configuration. An entirely empty file is also rejected, since a worker with no configuration can’t connect to anything.
Deploys Preserve Configuration
Pushing code never overwrites the environment file. Config and code have separate lifecycles: deploy as often as you like without re-entering secrets.
Messaging
Workers consume jobs from the project’s RabbitMQ broker. The convention the starter implements:
- One topic exchange named
jobs, shared by the project - One durable queue per job type, named
q.<type> - The routing key is the job type itself
WORKER_JOB_TYPES is a comma-separated list of the types one worker handles:
WORKER_JOB_TYPES=report.generate,image.thumbnailThat worker declares and consumes q.report.generate and q.image.thumbnail.
The platform provisions the broker, not your topology. Exchanges and queues are
declared by your worker code at startup — that’s why the starter declares them
idempotently on connect. If you expect a queue to exist and it doesn’t, check that the
worker actually started and that WORKER_JOB_TYPES lists the type.
Splitting Work Across Workers
Because job types drive queue names, you decide the split by configuration rather than code layout:
- One worker, many types — simplest. Set several types in
WORKER_JOB_TYPES. - One worker per type — isolates failures and lets you deploy and restart each independently. Preferred when one job type is far heavier or far riskier than the rest.
Publishing side: your app or microapp publishes to the jobs exchange with the job type as
the routing key. Nothing special is needed on the platform for a new job type beyond a
worker configured to consume it.
Talking to DaaS
DAAS_URL and DAAS_TOKEN give the worker the same data backend your apps use, so a
worker reads and writes collections through the normal DaaS REST API. Full reference:
DaaS documentation .
The token is minted when the platform builds the recommended values. If DaaS calls start
returning authentication errors long after setup, reload the Environment page, prefill
again into an emptied DAAS_TOKEN, save, and restart.