Environment variables

The environment variables are used to configure the application.

Set up the file

The environment variables are used to configure the application. We will use a .env file to store the variables. For the sample environment file, see the example .env file.

The variables are split up into the following sections:

• General URLs
• Database
• Authentication
• Object Storage
• Access Control
• GitHub SSO
• GitHub integration
• Google SSO
• Discord SSO
• Custom OAuth/OIDC
• Redis
• SMTP Configuration

Required variables

General URLs

This section will cover all the variables related to the general URLs.

Name	Description
KANEO_CLIENT_URL	The URL of the web application.
KANEO_API_URL	The URL of the API.

Database

This section will cover all the variables related to the database.

Name	Description
DATABASE_URL	The URL of the PostgreSQL database.
POSTGRES_DB	The name of the PostgreSQL database.
POSTGRES_USER	The username for the PostgreSQL database.
POSTGRES_PASSWORD	The password for the PostgreSQL database.

Authentication

This section will cover all the variables related to the authentication.

Name	Description
AUTH_SECRET	The secret key for the JWT token. 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.
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.

Optional variables

Object Storage

Kaneo uses S3-compatible object storage for private uploads in task descriptions and task comments.

MinIO is the easiest local option and the primary tested target. You can also use other S3-compatible storage backends such as AWS S3, Cloudflare R2, or fs.

Name	Description	Default
S3_ENDPOINT	The S3-compatible API endpoint used by the Kaneo API for presigned uploads. Example: http://minio:9000.
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.
S3_SECRET_ACCESS_KEY	Secret key used by the Kaneo API to create presigned upload URLs.
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. This should usually be true for MinIO and fs.	true
S3_MAX_IMAGE_UPLOAD_BYTES	Maximum allowed upload size in bytes for images and other uploaded files.	10485760
S3_PRESIGN_TTL_SECONDS	How long presigned upload URLs remain valid.	300

Access Control

Name	Description	Default
DISABLE_GUEST_ACCESS	Disable anonymous/guest sign-in. When set to true, the guest access button will not be shown on sign-in and sign-up pages.	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: Users with valid workspace invitations can still register even when this is enabled.	false
DISABLE_PASSWORD_REGISTRATION	Disable password-based account creation. When set to true, email/password sign-up is blocked, but social/OIDC registration remains available unless DISABLE_REGISTRATION=true.	false

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).
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_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.

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	Whether to use SSL/TLS.
SMTP_USER	The SMTP user.
SMTP_PASSWORD	The SMTP password.
SMTP_FROM	The SMTP from address.
SMTP_REQUIRE_TLS	Whether to explicitly force to use TLS. See more on.
SMTP_IGNORE_TLS	Ignore TLS certificate errors. Set to true for self-signed or invalid certificates. Default: false.

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, your sign in will be done via email using a magic link.
• 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.