Configuration
The server is configured with environment variables. --port and --database-url flags override their variables.
| Variable | Default | Description |
|---|---|---|
WORKLY_DATABASE_URL |
sqlite://.workly/dev.db in dev; required for serve |
postgres://user:pass@host:5432/db or sqlite://path/to/file.db (sqlite:///abs/path.db for an absolute path). |
WORKLY_SIGNING_SECRET |
workly-dev-secret in dev; required for serve |
Signs every delivery (Workly-Signature). Generate one with openssl rand -hex 32. |
WORKLY_SIGNING_SECRET_PREVIOUS |
unset | During a secret rotation, also signs deliveries with the old secret. See Rotating the signing secret. |
WORKLY_API_KEY |
unset | If set, /v1 and /metrics require Authorization: Bearer <key>. serve logs a warning when it’s unset. Always ignored by dev. |
WORKLY_PORT |
7337 |
Port for the API and dashboard. |
WORKLY_METRICS_PORT |
unset | Serve /metrics on this port instead, without the API key. Keep it internal. |
WORKLY_RETENTION |
168h |
How long succeeded, failed and cancelled tasks (with their attempts) are kept. 0 keeps them forever. |
WORKLY_RUN_RETENTION |
WORKLY_RETENTION |
How long finished schedule and workflow runs are kept. Each schedule’s and workflow’s latest run is always kept. 0 keeps them forever. |
WORKLY_SHUTDOWN_TIMEOUT |
25s |
How long in-flight requests and deliveries get to finish on shutdown. Deliveries still running after it are retried. |
WORKLY_MAX_PAYLOAD_BYTES |
1048576 |
Largest task body, up to 100 MiB. |
WORKLY_MAX_IN_FLIGHT |
100 |
Most task deliveries in flight at once, across all queues, up to 10,000. Throughput to slow endpoints is at most this divided by their response time; queues’ max_concurrency limits them further. Schedule runs have their own cap of 20. |
WORKLY_AUTO_CREATE_QUEUES |
true |
Enqueueing to a missing queue creates it with defaults. With false, it’s a 404 queue_not_found. |
WORKLY_AUTO_MIGRATE |
true |
Apply database migrations on startup. With false, run workly migrate before starting new versions. |
WORKLY_MCP |
read-only (full in dev) |
Tools served to coding agents at /mcp: read-only, full (adds enqueue, run now, retry, cancel, pause and settings changes) or off. See MCP. |
WORKLY_PUBLIC_URL |
http://localhost:7337 in dev; unset |
Where people open Workly, e.g. https://workly.example.com. Alerts link to its dashboard; without it they have no links. |
WORKLY_SMTP_URL |
unset | SMTP server for email alerts: smtp://user:pass@host:587 (STARTTLS, required before the password is sent, except to localhost) or smtps://user:pass@host:465. Without it, alerts go to Slack only. |
WORKLY_SMTP_FROM |
unset | The address alerts are sent from, e.g. Workly <alerts@example.com>. Required with WORKLY_SMTP_URL. |
WORKLY_LOG_LEVEL |
info |
debug, info, warn or error. |
WORKLY_LOG_FORMAT |
json (text in dev) |
json or text. |
Durations use Go’s syntax: 90s, 15m, 168h.
Postgres
Section titled “Postgres”Workly needs Postgres 14 or newer. It creates its tables on startup (WORKLY_AUTO_MIGRATE); replicas starting together take turns.
Connection settings go in the URL:
sslmode=require(orverify-full) for a managed database.search_path=worklykeeps Workly’s tables in their own schema. Create the schema first. Separate installs can share a database this way, each in its own schema.pool_max_conns=20raises the connection pool size (the default is 4, or the number of CPUs if higher). The dispatcher leader holds one more connection for its lock.
The CLI
Section titled “The CLI”The CLI’s API commands (queues, tasks, schedules and the rest) talk to a server over its API:
| Variable | Flag | Default |
|---|---|---|
WORKLY_URL |
--url |
http://localhost:7337 |
WORKLY_API_KEY |
--api-key |
unset |
The Python and TypeScript SDKs read the same two variables.
Rotating the signing secret
Section titled “Rotating the signing secret”Endpoints verify deliveries with the signing secret, so changing it takes three steps:
- Set the new secret as
WORKLY_SIGNING_SECRETand the old one asWORKLY_SIGNING_SECRET_PREVIOUS, and restart. Each delivery now carries both signatures, and endpoints still on the old secret keep verifying them. - Move your endpoints to the new secret.
- Unset
WORKLY_SIGNING_SECRET_PREVIOUSand restart.