Environment variables

Everything Conatus reads comes from the .env file next to docker-compose.yml. This page is the reference; the annotated template that ships with the app is .env.example.

Variables marked required have no usable default. Compose refuses to start the stack without them.

Images and versions

Variable	Default	Purpose
CONATUS_VERSION	latest*	Release image tag, without the leading v. During the public beta, pin 0.2.0-beta.3; the latest image is not published yet.
CONATUS_MCP_VERSION	latest	Tag for the optional MCP sidecar, released on its own schedule.
CONATUS_IMAGE	ghcr.io/nojusmorkunas/conatus	Override only when running images from a fork or another registry.
CONATUS_MCP_IMAGE	ghcr.io/nojusmorkunas/conatus-mcp	Same, for the MCP sidecar.

* The Compose fallback is latest, but that tag is not published until the first stable release. A fresh beta installation must set CONATUS_VERSION=0.2.0-beta.3 explicitly.

Network

Variable	Default	Purpose
CONATUS_PORT	4399	Host port for the web app. The container always listens on 3000.
CONATUS_BIND_ADDRESS	0.0.0.0	Address the host port binds to. Set to 127.0.0.1 when a reverse proxy fronts the app.
AUTH_URL	empty	External HTTPS origin, e.g. https://tasks.example.com. Required behind a domain or proxy.
PUBLIC_BASE_URL	empty	Same value as AUTH_URL. Used for generated links.

Set AUTH_URL and PUBLIC_BASE_URL together or not at all. See Reverse proxy.

Database

Variable	Default	Purpose
POSTGRES_USER	app	Database user.
POSTGRES_PASSWORD	required	Ends up inside a connection URL, so keep it URL-safe.
POSTGRES_DB	app	Database name.
POSTGRES_PORT	5432	Host port for PostgreSQL, published on 127.0.0.1 only.
DATABASE_URL	none	Only used when running the app directly with npm. Compose builds its own internal URL from the POSTGRES_* values and ignores this.

Authentication and accounts

Variable	Default	Purpose
AUTH_SECRET	required	Session signing secret. Generate with npx auth secret. Changing it signs everyone out.
REGISTRATION_MODE	invite-only	The first account bootstraps the server and becomes administrator; everyone else needs an invite.
CONATUS_ADMIN_USERNAME	empty	One-time bootstrap. Set before the first docker compose up.
CONATUS_ADMIN_PASSWORD	empty	Same. The bootstrap job only acts on an empty database. Remove both after first login.
CONATUS_DEV_MODE	0	Local development only. See the warning below.

CONATUS_DEV_MODE is not gated on NODE_ENV

CONATUS_DEV_MODE=1 disables rate limiting on login, registration, password reset, email resend and error reporting, and opens registration to anyone. Setting it in a production .env is enough to do all of that. There is no second switch protecting you. Never set it on a server reachable from outside your machine.

Attachment storage (MinIO)

Variable	Default	Purpose
S3_ACCESS_KEY	required	MinIO root user.
S3_SECRET_KEY	required	MinIO root password.
S3_BUCKET	attachments	Bucket for uploaded files.
S3_ENDPOINT	minio under Compose	The template says localhost for direct npm runs; Compose overrides it to the minio service name.
S3_PORT	9000	Same.
MINIO_PORT	9000	Host port for the S3 API, published on 127.0.0.1 only.
MINIO_CONSOLE_PORT	9001	Host port for the MinIO web console, published on 127.0.0.1 only.

Email

Email is disabled unless all three are set. Conatus works without it. Registration uses username and password, with no SMTP requirement.

Variable	Default	Purpose
SMTP_HOST	empty	Mail server hostname.
SMTP_PORT	empty	Usually 587.
SMTP_FROM	empty	Sender, e.g. "Conatus <conatus@example.com>".

Backups

Variable	Default	Purpose
BACKUP_INTERVAL	86400	Seconds between dumps. Default is daily.
BACKUP_KEEP	7	Number of dumps to retain. The service deletes older ones.

See Backups.

Optional MCP sidecar

Only read when you start the mcp profile. Full reference on the MCP server page.

Variable	Default	Purpose
TASKS_API_TOKEN	placeholder	Scoped tdm_ token created in Settings → API tokens.
MCP_PUBLIC_URL	empty	Exact external HTTPS URL, ending in /mcp. Required for OAuth mode.
MCP_OAUTH_PASSWORD	empty	Separate password entered on the browser approval page.
MCP_ALLOWED_ORIGINS	http://localhost:4399	Comma-separated browser origins allowed to call the MCP endpoint.
MCP_BEARER_TOKEN	empty	Static credential for clients that cannot do OAuth.

Other

Variable	Default	Purpose
ERROR_WEBHOOK_URL	empty	Endpoint that receives JSON error reports.

Note

This page and .env.example are maintained separately. If they disagree, .env.example in the release you are running is the truth. Please open an issue.