Environment variables

Set up the file

For Docker Compose, put server settings in .env beside your Compose file. Start with the complete installation guide, then use this page to add optional features. For the sample environment file, see the example .env file.

Core configuration

General URLs

For the bundled image, set KANEO_CLIENT_URL and leave KANEO_API_URL unset. The API URL defaults to your client URL plus /api. Set both explicitly only for a separate API deployment or a different proxy path.

Name	Description
`KANEO_CLIENT_URL`	The URL of the web application.
`KANEO_API_URL`	Public API URL. Derived by the bundled image; set it explicitly for a separate API or host-native development.
`CORS_ORIGINS`	Optional comma-separated list of allowed browser origins, for example `https://kaneo.example.com`. When omitted, HTTP CORS uses `KANEO_CLIENT_URL`.

The web container embeds only KANEO_API_URL, KANEO_CLIENT_URL, and KANEO_TURNSTILE_SITE_KEY into browser assets at startup. These values are public; other KANEO_* variables are not substituted into frontend files. Values are encoded as JavaScript strings. The standalone web image serves its generated MCP discovery documents as JSON files, without modifying the nginx configuration. Configure actual public service URLs; escaping a value does not make an invalid URL usable. Recreate the container when changing its environment.

Database

The bundled Compose setup derives its database connection from POSTGRES_*. Set DATABASE_URL when using an external database; it takes precedence. The API needs a server-reachable database address, not a browser URL.

Name	Description
`DATABASE_URL`	The full PostgreSQL connection string, in the format `postgresql://[user]:[password]@[host]:[port]/[database]`. Example: `postgresql://kaneo:kaneo@localhost:5432/kaneo`. Use the actual credentials for that database. This value overrides `POSTGRES_*`. Percent-encode special characters in URL credentials.
`POSTGRES_DB`	The name of the PostgreSQL database. Example: `kaneo`.
`POSTGRES_USER`	The username for the PostgreSQL database. Example: `kaneo`.
`POSTGRES_PASSWORD`	The password for the PostgreSQL database. Use a strong value in production.
`POSTGRES_HOST`	Database hostname for derived configuration. Default: `postgres`; use `localhost` for a host-native API connected to local PostgreSQL.
`POSTGRES_PORT`	Database port for derived configuration. Default: `5432`.
`POSTGRES_PASSWORD_FILE`	Path to a UTF-8 file containing the database password. Used when `POSTGRES_PASSWORD` is unset and Kaneo derives `DATABASE_URL` from `POSTGRES_*`. Set the same file variable on the PostgreSQL container when using the bundled Compose setup; see Keep secrets in files.
`DATABASE_POOL_MAX`	Maximum number of PostgreSQL connections each API process keeps open. Default: `10`. Lower it when the database user has a connection limit, for example on a shared PostgreSQL server; with several API replicas, the limit has to cover all of them. Label deletions and GitHub imports running at once beyond the pool size minus one get a retryable `429`. Must be an integer of at least `2`, otherwise startup fails.

Authentication

Keep AUTH_SECRET stable across restarts and include it in your protected configuration backup. The bundled image can generate a temporary secret if it is unset; a host-native API requires you to provide one.

Name	Description
`AUTH_SECRET`	The secret used by the authentication service. Must be at least 32 characters long, use a long, random value in production. Example: use `openssl rand -base64 32` to generate a secure key in Linux/macOS.
`COOKIE_DOMAIN`	Optional cookie domain override. Leave unset for host-only cookies. Set a parent domain only when your deployment needs cookies shared across its trusted subdomains.
`AUTH_SECRET_FILE`	Path to a UTF-8 file containing the authentication secret. Used when `AUTH_SECRET` is unset; the same 32-character minimum applies.
`DEVICE_AUTH_CLIENT_IDS`	Optional. Comma-separated list of allowed device authorization client IDs. When unset, Kaneo implicitly allows `kaneo-cli` and `kaneo-mcp` by default, so no extra configuration is required for the CLI or MCP. Override only when you need additional trusted clients, for example `kaneo-cli,kaneo-mcp,my-desktop-app`.

The Docker Compose quick-start pins image 2.28.3, which predates _FILE support. Raise KANEO_IMAGE_TAG to a release containing this feature before following Keep secrets in files. For the supported _FILE variables, a non-empty direct value takes precedence. Kaneo removes trailing line endings from secret files but keeps other whitespace. Missing, unreadable, or empty files fail startup instead of silently using a fallback. Secrets are read at startup; restart Kaneo after rotating a file. DATABASE_URL takes precedence over both PostgreSQL password variables.

Optional variables

MCP

Name	Description	Default
`KANEO_INTERNAL_API_URL`	API origin used only for server-side requests from the built-in HTTP MCP endpoint. Override it only if the API is not reachable at the default loopback address from its own process.	`http://127.0.0.1:1337`

Object Storage

Kaneo uses S3-compatible object storage for private uploads in task descriptions and task comments. For self-hosted storage, follow the Silo setup. For managed storage, see AWS S3 and other providers. The endpoint must be reachable by both the API and the browser.

Name	Description	Default
`S3_ENDPOINT`	The S3-compatible API endpoint used by the Kaneo API for presigned uploads. Example: `https://files.example.com`.
`S3_BUCKET`	The bucket Kaneo will use for uploaded files.
`S3_ACCESS_KEY_ID`	Access key used by the Kaneo API to create presigned upload URLs. Optional: leave unset (together with `S3_SECRET_ACCESS_KEY`) to use the default AWS credential provider chain (IAM role / IRSA / instance profile).
`S3_SECRET_ACCESS_KEY`	Secret key used by the Kaneo API to create presigned upload URLs. Must be set together with `S3_ACCESS_KEY_ID`, or left unset for IAM-role-based access.
`S3_REGION`	The storage region used for request signing.	`us-east-1`
`S3_PUBLIC_BASE_URL`	Optional public base URL for uploaded assets. Kaneo does not require this for the current private asset flow.
`S3_FORCE_PATH_STYLE`	Use path-style S3 URLs. Set to `true` for Silo. Check other providers’ endpoint requirements.	`true`
`S3_MAX_IMAGE_UPLOAD_BYTES`	Maximum allowed upload size in bytes for images and other uploaded files.	`10485760`
`S3_KEY_PREFIX`	Optional prefix prepended to all S3 object keys. Useful for sharing a single bucket across multiple environments (e.g. `staging/`, `prod/kaneo/`). Trailing slashes are trimmed automatically.
`S3_PRESIGN_TTL_SECONDS`	How long presigned upload URLs remain valid.	`300`

Access Control

Browser WebSocket connections require an exact origin matching KANEO_CLIENT_URL, KANEO_API_URL, or a comma-separated CORS_ORIGINS entry. Wildcards, null, and missing browser origins are rejected. Production deployments must configure their public URLs. Native clients without an Origin header must provide a valid bearer token or API key; cookies alone are not sufficient. Both real-time endpoints accept only the small {"type":"ping"} text keepalive, with a 64-byte message limit.

Name	Description	Default
`DISABLE_WORKSPACE_CREATION`	Allow only instance administrators to create workspaces. Workspace ownership or a workspace admin role does not grant this instance-wide permission.	`false`
`DISABLE_GUEST_ACCESS`	Disable anonymous/guest sign-in. Guests are also blocked before initial instance setup and when registration, local registration, or the local login form is disabled.	`false`
`DISABLE_REGISTRATION`	Disable public user registration. When set to `true`, the sign-up option will not be shown on the sign-in page and new user creation is blocked (including via SSO). Note: Invited password signups must present the matching invitation link. OAuth, OTP, and magic-link signups may match an invitation by email only after that email has been verified. Sign-in emails (OTP codes and magic links) are only sent to existing accounts or pending invitations. The first non-guest user can complete initial instance setup.	`false`
`DISABLE_PASSWORD_REGISTRATION`	Disable local account creation through password, email OTP, magic link, and guest access. Existing accounts can still use email sign-in unless `DISABLE_LOGIN_FORM=true`. Social/OIDC registration remains available unless `DISABLE_REGISTRATION=true`. The initial administrator can still be created through password signup.	`false`
`DISABLE_EMAIL_OTP_SIGN_IN`	When SMTP is configured, sign-in uses email verification codes by default. Set to `true` to use email/password sign-in instead. Workspace invitation and password-reset emails still use SMTP.	`false`
`DISABLE_LOGIN_FORM`	Disable local email sign-in and hide the form on the sign-in page. When set to `true`, only SSO/OAuth buttons are shown. Useful when you want to enforce authentication exclusively through an external identity provider.	`false`
`CUSTOM_OAUTH_AUTO_LOGIN`	Automatically redirect to the custom OAuth/OIDC provider instead of showing the sign-in page. When set to `true`, users are immediately redirected to your identity provider without seeing the login page. Requires a custom OAuth provider to be configured.	`false`

Before enabling SSO-only access with DISABLE_LOGIN_FORM=true or CUSTOM_OAUTH_AUTO_LOGIN=true on an existing installation, make sure existing local accounts have verified email addresses. OAuth/OIDC identities cannot be linked to an unverified local account, and affected users will receive error=account_not_linked. Keep the login form available until those users have signed in with an email OTP or magic link. If SSO-only access is already enabled, temporarily set both options to false, recreate the Kaneo container, and let affected users complete an email sign-in before restoring the SSO-only settings.

Proxies

Name	Description	Default
`TRUSTED_PROXIES`	Comma-separated IPs or CIDR ranges of trusted reverse proxies. Kaneo first checks the actual TCP peer, then walks `X-Forwarded-For` right to left only through trusted hops. Defaults trust the bundled loopback nginx only. For a separate Docker/ingress proxy, explicitly add its IP or dedicated proxy subnet; avoid shared private-network ranges. Use `none` for direct API access without trusted proxies. Invalid entries prevent startup. `CF-Connecting-IP` and client-supplied `X-Kaneo-Client-IP` are never used.	`127.0.0.0/8, ::1/128`

Only list addresses you control. Any host in this range can set X-Forwarded-For and have it believed, so do not include a range that clients can reach Kaneo from directly. The client IP is used for rate limiting and session records.

Notifications

Name	Description	Default
`NOTIFICATION_SECRET_ENCRYPTION_KEY`	Required to store personal notification tokens and webhook signing secrets. Generate a random value, keep it stable, and include it in protected configuration backups. Changing or losing it prevents decryption of existing secrets.	Unset
`KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS`	Allow outbound notification destinations (ntfy, Gotify, generic webhooks), self-managed Gitea or GitLab instances, and import sources that resolve to private or non-routable addresses. Off by default to prevent SSRF; the `http`/`https` requirement still applies. Only enable on a trusted, isolated deployment.	`false`

Imports

The in-app importer reads from the source on the API server. Sources on a private network, such as a PLANKA container in the same Docker network, also need KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS=true (see Notifications).

Name	Description	Default
`TRELLO_API_KEY`	API key of a Trello Power-Up you create at trello.com/power-ups/admin. Enables the one-click Authorize on Trello button when importing from Trello. Kaneo only hands it to workspace admins, inside the authorize link, when they start a Trello import. The key identifies the app and grants no access by itself. Without it, users paste their own Trello API key in the import form. See Import from Trello.	Unset

GitHub SSO

Sign in with GitHub uses a GitHub OAuth App. Set GITHUB_OAUTH_CLIENT_ID and GITHUB_OAUTH_CLIENT_SECRET (or rely on the legacy variables below).

Name	Description
`GITHUB_OAUTH_CLIENT_ID`	OAuth client ID for GitHub sign-in.
`GITHUB_OAUTH_CLIENT_SECRET`	OAuth client secret for GitHub sign-in.
`GITHUB_CLIENT_ID`	Legacy fallback for OAuth client ID when `GITHUB_OAUTH_*` is not set.
`GITHUB_CLIENT_SECRET`	Legacy fallback for OAuth client secret when `GITHUB_OAUTH_*` is not set.

GitHub integration

Repository sync and webhooks use a GitHub App. These variables do not enable GitHub sign-in; configure GitHub SSO separately if you want both.

Name	Description
`GITHUB_APP_ID`	The GitHub App ID.
`GITHUB_WEBHOOK_SECRET`	Secret used to verify GitHub webhook payloads.
`GITHUB_PRIVATE_KEY`	PEM private key for the GitHub App (JWT authentication). Accepts a real multi-line PEM, or a single line where every newline is replaced with the literal characters `\n` (useful when the host’s env editor strips newlines, e.g. Portainer’s form-based stack editor).
`GITHUB_PRIVATE_KEY_BASE64`	(Optional) Alternative to `GITHUB_PRIVATE_KEY`: a base64-encoded PEM. Takes precedence when both are set. Convenient when your orchestrator can’t carry newlines at all.
`GITHUB_APP_NAME`	(Optional) GitHub App slug, used for installation links in the UI.

Google SSO

Name	Description
`GOOGLE_CLIENT_ID`	The Google client ID.
`GOOGLE_CLIENT_SECRET`	The Google client secret.

Discord SSO

Name	Description
`DISCORD_CLIENT_ID`	The Discord client ID.
`DISCORD_CLIENT_SECRET`	The Discord client secret.

Custom OAuth/OIDC

Name	Description
`CUSTOM_OAUTH_CLIENT_ID`	OAuth client ID from your provider.
`CUSTOM_OAUTH_CLIENT_SECRET`	OAuth client secret from your provider.
`CUSTOM_OAUTH_CLIENT_SECRET_FILE`	Path to a UTF-8 file containing the custom OAuth client secret. Used when `CUSTOM_OAUTH_CLIENT_SECRET` is unset.
`CUSTOM_OAUTH_AUTHORIZATION_URL`	Authorization endpoint URL.
`CUSTOM_OAUTH_TOKEN_URL`	Token exchange endpoint URL.
`CUSTOM_OAUTH_USER_INFO_URL`	User info endpoint URL.
`CUSTOM_OAUTH_DISCOVERY_URL`	(Optional) OpenID Connect discovery document URL.
`CUSTOM_OAUTH_SCOPES`	(Optional) Comma-separated list of OAuth scopes. Default: `profile,email`.
`CUSTOM_OAUTH_RESPONSE_TYPE`	(Optional) OAuth response type. Default: `code`.
`CUSTOM_AUTH_PKCE`	(Optional) Enable/disable PKCE. Default: `true`.
`CUSTOM_OAUTH_NAME`	(Optional) Provider name on the sign-in button, for example `Authentik`. Default: `SSO`.
`CUSTOM_OAUTH_LOGOUT_URL`	(Optional) Logout endpoint URL for your identity provider.

Redis

Kaneo supports Redis for horizontal scaling of WebSocket broadcasts. When any Redis mode is configured, multiple API instances can relay real-time updates via Redis Pub/Sub. When none are set, an in-memory adapter is used (single-instance only). Three deployment modes are supported: Standalone, Sentinel, and Cluster. Only one mode should be configured at a time. If multiple are set, the priority is: Cluster > Sentinel > Standalone.

Standalone (single server)

Name	Description
`REDIS_URL`	Redis connection string (e.g., `redis://localhost:6379`).

Sentinel (high-availability with automatic failover)

Name	Description	Default
`REDIS_SENTINELS`	Comma-separated list of Sentinel nodes (e.g., `sentinel-1:26379,sentinel-2:26379,sentinel-3:26379`).
`REDIS_SENTINEL_MASTER_NAME`	Name of the Sentinel master group.	`mymaster`
`REDIS_SENTINEL_PASSWORD`	Password for Sentinel instances, if different from the Redis password.
`REDIS_SENTINEL_TLS`	Set to `true` to enable TLS for Sentinel connections.	`false`

Cluster (horizontal sharding)

Name	Description
`REDIS_CLUSTER_NODES`	Comma-separated list of cluster seed nodes (e.g., `node-1:6379,node-2:6379,node-3:6379`).

Shared (used by Sentinel and Cluster modes)

Name	Description
`REDIS_PASSWORD`	Password for the Redis data nodes (used by both Sentinel and Cluster modes, not for Sentinel auth itself; use `REDIS_SENTINEL_PASSWORD` for that).

SMTP Configuration

Name	Description
`SMTP_HOST`	The SMTP host.
`SMTP_PORT`	The SMTP port.
`SMTP_SECURE`	Use TLS immediately (default: `true`, typically port 465). Set to `false` for STARTTLS, typically on port 587.
`SMTP_USER`	The SMTP user.
`SMTP_PASSWORD`	The SMTP password.
`SMTP_FROM`	The SMTP from address.
`SMTP_REQUIRE_TLS`	Require STARTTLS when `SMTP_SECURE=false` (default: `true`). Sending fails if the server cannot upgrade. Only use `false` for an intentionally unencrypted local development relay.
`SMTP_IGNORE_TLS`	Removed: `true` is rejected. This option disabled STARTTLS; it never bypassed certificate validation.
`NODE_EXTRA_CA_CERTS`	Path to a trusted CA PEM file for a private SMTP certificate authority. Set before starting the API; certificate expiry and hostname checks remain enabled.
`KANEO_EMAIL_ASSETS_URL`	Optional base URL for the logo and icons in emails (default: `KANEO_CLIENT_URL` followed by `/email`). Mail clients load these images directly, so set this to a public URL if your instance is only reachable on a private network.

When upgrading, remove SMTP_IGNORE_TLS=true and verify delivery with the corrected certificate trust configuration before rollout. Fix invalid certificates instead of disabling validation. Nodemailer documents the difference between STARTTLS and certificate validation.

Key points

If you enable GitHub SSO, create a GitHub OAuth App in GitHub Developer Settings and set GITHUB_OAUTH_CLIENT_ID / GITHUB_OAUTH_CLIENT_SECRET (or the legacy GITHUB_CLIENT_* variables). See the GitHub SSO guide.
If you use the GitHub repository integration, configure a GitHub App and set the integration variables in GitHub integration. See the GitHub integration configuration guide.
If you enable Google SSO, you need to set up the Google app which is used to authenticate users in the Google Cloud Console. See the Google SSO guide.
If you enable Discord SSO, you need to set up the Discord application which is used to authenticate users in the Discord Developer Portal. See the Discord SSO guide.
If you enable Custom OAuth/OIDC, you need to configure your identity provider with the appropriate redirect URI. See the Custom OAuth/OIDC guide.
If you have enabled SMTP, sign-in uses email verification codes by default. Set DISABLE_EMAIL_OTP_SIGN_IN=true to use email/password sign-in instead. The password form includes Forgot password?, which emails a single-use reset link valid for one hour. Resetting a password revokes existing sessions. Password reset requires SMTP and is unavailable when DISABLE_LOGIN_FORM=true.
If you need device authorization for clients beyond the defaults (kaneo-cli, kaneo-mcp when DEVICE_AUTH_CLIENT_IDS is unset), set DEVICE_AUTH_CLIENT_IDS to the full comma-separated list of trusted client IDs for your deployment.

Authentication CAPTCHA

When TURNSTILE_SECRET_KEY is configured on the API, set the matching public KANEO_TURNSTILE_SITE_KEY on the bundled container or standalone web container. For local Vite development, use VITE_TURNSTILE_SITE_KEY in apps/web/.env.local instead. The API validates the token at password signup, social/OIDC initiation, guest sign-in, OTP sending (including resend), magic-link initiation, and password-reset requests. Tokens are single-use; clients must obtain a fresh token for each attempt. OAuth callbacks and OTP redemption validate their own state/code and do not redeem the CAPTCHA token again. The widget uses the action auth. The API requires that action and the exact frontend hostname from KANEO_CLIENT_URL, and rejects verification failures, redirects and timeouts. Update the API and web app together when adopting this check. Custom clients must include the token in the x-turnstile-token header. Automatic OIDC redirection pauses at the sign-in page when a CAPTCHA widget is configured so the user can complete it. No secret configured means CAPTCHA is disabled, as on self-hosted instances that opt out. This does not bypass registration or guest-access restrictions.

Error reporting

API reporting is opt-in. Leave SENTRY_DSN unset to disable it.

Variable	Meaning	Default
`SENTRY_DSN`	Destination for API error reports	Unset
`SENTRY_ENVIRONMENT`	Environment tag	`NODE_ENV`, then `production`
`SENTRY_RELEASE`	Release identifier	Application version
`SENTRY_TRACES_SAMPLE_RATE`	Fraction of requests traced, from 0 to 1	`0`
`SENTRY_PROFILES_SAMPLE_RATE`	Profiling sample rate, from 0 to 1	`0`

The browser reads VITE_SENTRY_DSN when it is built. The current web container renderer does not replace KANEO_SENTRY_DSN at startup, so setting that variable on a running container does not enable browser reporting.

Cloud mode

KANEO_CLOUD=true enables hosted-service behavior, including cloud billing and additional signup and invitation restrictions. Leave it unset for a normal self-hosted instance. CAPTCHA is controlled by TURNSTILE_SECRET_KEY independently of this flag.

Install

Configure

Sign-in providers

Keep it running

Migrate a deployment

Environment variables

Set up the file

Core configuration

General URLs

Database

Authentication

Optional variables

MCP

Object Storage

Access Control

Proxies

Notifications

Imports

GitHub SSO

GitHub integration

Google SSO

Discord SSO

Custom OAuth/OIDC

Redis

Standalone (single server)

Sentinel (high-availability with automatic failover)

Cluster (horizontal sharding)

Shared (used by Sentinel and Cluster modes)

SMTP Configuration

Key points

Authentication CAPTCHA

Error reporting

Cloud mode

​Set up the file

​Core configuration

​General URLs

​Database

​Authentication

​Optional variables

​MCP

​Object Storage

​Access Control

​Proxies

​Notifications

​Imports

​GitHub SSO

​GitHub integration

​Google SSO

​Discord SSO

​Custom OAuth/OIDC

​Redis

​Standalone (single server)

​Sentinel (high-availability with automatic failover)

​Cluster (horizontal sharding)

​Shared (used by Sentinel and Cluster modes)

​SMTP Configuration

​Key points

​Authentication CAPTCHA

​Error reporting

​Cloud mode

Set up the file

Core configuration

General URLs

Database

Authentication

Optional variables

MCP

Object Storage

Access Control

Proxies

Notifications

Imports

GitHub SSO

GitHub integration

Google SSO

Discord SSO

Custom OAuth/OIDC

Redis

Standalone (single server)

Sentinel (high-availability with automatic failover)

Cluster (horizontal sharding)

Shared (used by Sentinel and Cluster modes)

SMTP Configuration

Key points

Authentication CAPTCHA

Error reporting

Cloud mode