Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

24.0 KB
Raw Blame
---
title: Environment variables
description: Look up configuration names, defaults, and when to set them.
---

## Set up the file

For Docker Compose, put server settings in `.env` beside your Compose file. Start with the [complete installation guide](/core/installation/docker-compose), then use this page to add optional features.
For the sample environment file, see the [example .env file](https://github.com/usekaneo/kaneo/blob/main/.env.sample).

## 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](/core/installation/docker-compose#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](/core/installation/docker-compose#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](/core/installation/silo). For managed storage, see [AWS S3 and other providers](/core/installation/storage-backends). 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. When `true`, the matching [instance setting](/core/operations/administration#instance-settings) is locked. 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 `true`, the matching [instance setting](/core/operations/administration#instance-settings) is locked; otherwise administrators can close registration there. 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. When `true`, the matching [instance setting](/core/operations/administration#instance-settings) is locked. 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` |

<Warning>
  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.
</Warning>

### 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` |

<Warning>
  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.
</Warning>

### 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](/core/migrations) 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](/core/migrations) 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](#notifications)).

Name | Description | Default |
--- | --- | --- |
| `TRELLO_API_KEY` | API key of a Trello Power-Up you create at [trello.com/power-ups/admin](https://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](/core/migrations/from-trello#set-up-trello-on-a-self-hosted-instance). | Unset |

### GitHub SSO

Sign in with GitHub uses a [GitHub OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-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](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps). These variables do not enable GitHub sign-in; configure [GitHub SSO](#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.
| `CUSTOM_OAUTH_BACKCHANNEL_LOGOUT` | (Optional) Set to `true` to sign out Kaneo sessions when your identity provider sends an OpenID Connect back-channel logout to `/api/auth/oauth2/backchannel-logout/custom`. Requires `CUSTOM_OAUTH_DISCOVERY_URL` and `CUSTOM_OAUTH_CLIENT_ID`. Without them, the API stops at startup. Default: `false`.
| `CUSTOM_OAUTH_MANAGED_PROFILE_FIELDS` | (Optional) Comma-separated profile fields your identity provider manages: `name`, `image`, `locale`. Kaneo updates them from the provider's claims whenever someone signs in with it, and people with a linked provider account cannot change them in Kaneo. Any other value stops the API at startup. Default: unset, so profiles stay editable.
| `CUSTOM_OAUTH_ACCOUNT_URL` | (Optional) Absolute `http` or `https` URL of your identity provider's account page. Kaneo links to it next to managed profile fields. An invalid URL stops the API at startup.

### 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](https://nodemailer.com/smtp#tls-options).

## Key points

- If you enable GitHub SSO, create a GitHub OAuth App in [GitHub Developer Settings](https://github.com/settings/developers) and set `GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET` (or the legacy `GITHUB_CLIENT_*` variables). See the [GitHub SSO guide](/core/social-providers/github).
- If you use the GitHub repository integration, configure a GitHub App and set the integration variables in [GitHub integration](#github-integration). See the [GitHub integration configuration](/core/integrations/github/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](https://console.cloud.google.com/). See the [Google SSO guide](/core/social-providers/google).
- If you enable Discord SSO, you need to set up the Discord application which is used to authenticate users in the [Discord Developer Portal](https://discord.com/developers/applications). See the [Discord SSO guide](/core/social-providers/discord).
- If you enable Custom OAuth/OIDC, you need to configure your identity provider with the appropriate redirect URI. See the [Custom OAuth/OIDC guide](/core/social-providers/custom-oauth).
- 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.