How to Change Kaneo Settings: Environment Variables and UI Configuration

You can change Kaneo settings via environment variables for server-side configuration (all KANEO_* prefixed variables) or through the web interface for account and workspace preferences.

Kaneo is an open-source project management platform that splits configuration between server-side environment variables and in-app user preferences. Whether you are self-hosting with Docker or managing a cloud deployment, knowing how to change Kaneo settings allows you to customize authentication, CORS policies, and UI behavior to match your infrastructure requirements.

Server-Side Configuration via Environment Variables

Server-side settings in Kaneo are controlled through environment variables defined in the ENVIRONMENT_SETUP.md file and loaded at runtime. These variables configure the API endpoint, client URL, security settings, and cloud-specific features.

Essential Environment Variables

The core configuration uses the following KANEO_* variables as documented in ENVIRONMENT_SETUP.md:

• KANEO_CLIENT_URL – The public URL of the web application. Change this from the default http://localhost:5173 to your production domain (e.g., https://kaneo.mycompany.com).
• KANEO_API_URL – The base URL for the API server. Update this when the API runs behind a proxy or on a different port than the default http://localhost:1337.
• KANEO_CLOUD – Boolean flag that enables cloud-only protections including disposable email blocking, Turnstile captcha, and stricter rate limits. Set to true for hosted SaaS deployments.
• KANEO_TURNSTILE_SITE_KEY – Your Cloudflare Turnstile site key, injected into the web bundle at container startup.
• AUTH_SECRET – A JWT signing secret requiring at least 32 characters. Generate this using openssl rand -hex 32.
• CORS_ORIGINS – Comma-separated list of allowed origins, typically matching your KANEO_CLIENT_URL for production security.

According to the source code in packages/mcp/README.md, headless clients also use KANEO_API_URL and KANEO_API_KEY for authentication.

Applying Configuration Changes

To change Kaneo settings on the server:

1. Edit your .env file or Helm values.yaml with the desired values.
2. Restart the containers using docker compose restart or helm upgrade.
3. Verify the changes by checking the API logs. The server prints effective URLs on startup in apps/api/src/index.ts, emitting logs like ⚡ API is running at http://localhost:1337.

In-Application Settings via the Web UI

For user-specific preferences, Kaneo exposes a comprehensive settings interface located under apps/web/src/routes/_layout/_authenticated/dashboard/settings/. The UI uses TanStack Query hooks to persist changes through the backend API.

Account-Level Configuration

Account settings manage personal preferences and developer access:

• Preferences (account/preferences.tsx) – Toggle language, theme, and notification preferences.
• Notifications (account/notifications.tsx) – Configure email, Slack, or webhook delivery endpoints.
• Developer (account/developer.tsx) – Create and revoke API keys for headless access.

The API key creation modal is implemented in apps/web/src/components/settings/create-api-key-dialog.tsx, which generates secrets stored as KANEO_API_KEY for external scripts.

Workspace-Level Configuration

Workspace settings control project organization and team permissions:

• General (workspace/general.tsx) – Rename workspaces, update descriptions, and adjust default visibility settings.
• Labels (workspace/labels.tsx) – Create and manage custom task labels across projects.
• Roles (workspace/roles.tsx) – Configure role-based access control and permissions.
• Billing (workspace/billing.tsx) – Manage subscription details for cloud-hosted instances.

Practical Implementation Examples

Updating Docker Environment Variables

Modify your .env file to change Kaneo settings for a self-hosted deployment:

# .env

KANEO_CLIENT_URL=https://kaneo.mycompany.com
KANEO_API_URL=http://api.kaneo.internal:1337
KANEO_CLOUD=true
AUTH_SECRET=$(openssl rand -hex 32)

Apply the changes by recreating the containers:

docker compose up -d --force-recreate

Creating API Keys Through the UI

Navigate to Settings → Account → Developer in the web interface. Click "Create API Key" to open the dialog component defined in components/settings/create-api-key-dialog.tsx. Copy the generated secret immediately, as it functions as your KANEO_API_KEY for API authentication.

Programmatically Updating Workspace Settings

The following React component demonstrates how to update workspace names using the TanStack Query mutation pattern found in the Kaneo codebase:

import { useMutation } from "@tanstack/react-query";
import { updateWorkspace } from "@/fetchers/workspace/update";

export function WorkspaceGeneral({ workspaceId }: { workspaceId: string }) {
  const mutation = useMutation({
    mutationFn: (payload) => updateWorkspace(workspaceId, payload),
  });

  const handleRename = (newName: string) => {
    mutation.mutate({ name: newName });
  };

  // UI binds handleRename to a text input field
}

The updateWorkspace fetcher communicates with the API endpoint defined in the workspace controllers, following Kaneo's standard "controller → fetcher → UI" architecture.

Summary

• Server-side settings use KANEO_* environment variables defined in ENVIRONMENT_SETUP.md and require container restarts to apply.
• Account settings (preferences, notifications, API keys) reside in apps/web/src/routes/_layout/_authenticated/dashboard/settings/account/.
• Workspace settings (general config, labels, roles, billing) are located in apps/web/src/routes/_layout/_authenticated/dashboard/settings/workspace/.
• API keys are generated via components/settings/create-api-key-dialog.tsx and used as KANEO_API_KEY for programmatic access.
• Changes to environment variables appear in API logs on startup, as implemented in apps/api/src/index.ts.

Frequently Asked Questions

Where are Kaneo environment variables documented?

All server-side configuration variables are documented in ENVIRONMENT_SETUP.md in the repository root. This file lists every KANEO_* variable, its default value, and its purpose for both Docker and Helm deployments.

How do I update Kaneo settings without restarting the server?

In-application settings changed through the web UI apply immediately without restarts. However, environment variable changes require a container restart or redeployment to take effect, as they are loaded at runtime in apps/api/src/index.ts.

What is the difference between account and workspace settings in Kaneo?

Account settings (account/preferences.tsx, account/developer.tsx) affect individual user preferences and API access. Workspace settings (workspace/general.tsx, workspace/roles.tsx) affect team-wide project organization, permissions, and billing configurations.

How do I secure my Kaneo API keys?

Generate API keys through the Developer settings page and store them securely as environment variables (e.g., KANEO_API_KEY) rather than hardcoding them. For production deployments, set AUTH_SECRET to a cryptographically secure random string and configure CORS_ORIGINS to restrict API access to your specific client domain.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}