# How to Change Kaneo Settings: Environment Variables and UI Configuration

> Learn how to change Kaneo settings using environment variables for server-side configuration or the UI for account preferences. Easily manage your Kaneo environment.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-02

---

**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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/account/preferences.tsx)) – Toggle language, theme, and notification preferences.
- **Notifications** ([`account/notifications.tsx`](https://github.com/usekaneo/kaneo/blob/main/account/notifications.tsx)) – Configure email, Slack, or webhook delivery endpoints.
- **Developer** ([`account/developer.tsx`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/workspace/general.tsx)) – Rename workspaces, update descriptions, and adjust default visibility settings.
- **Labels** ([`workspace/labels.tsx`](https://github.com/usekaneo/kaneo/blob/main/workspace/labels.tsx)) – Create and manage custom task labels across projects.
- **Roles** ([`workspace/roles.tsx`](https://github.com/usekaneo/kaneo/blob/main/workspace/roles.tsx)) – Configure role-based access control and permissions.
- **Billing** ([`workspace/billing.tsx`](https://github.com/usekaneo/kaneo/blob/main/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:

```bash

# .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:

```bash
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`](https://github.com/usekaneo/kaneo/blob/main/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:

```typescript
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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts).

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

Account settings ([`account/preferences.tsx`](https://github.com/usekaneo/kaneo/blob/main/account/preferences.tsx), [`account/developer.tsx`](https://github.com/usekaneo/kaneo/blob/main/account/developer.tsx)) affect individual user preferences and API access. Workspace settings ([`workspace/general.tsx`](https://github.com/usekaneo/kaneo/blob/main/workspace/general.tsx), [`workspace/roles.tsx`](https://github.com/usekaneo/kaneo/blob/main/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.