Kaneo Documentation

The Kaneo documentation is managed via Mintlify with the following key files and locations:

• Docs root: /apps/docs
• Main configuration: apps/docs/docs.json
• OpenAPI source: apps/docs/openapi.json
• Landing page: index.mdx
• Product/Deployment guides: Located in core/**
• API Reference: Located in api-reference/** (includes overview and auth pages)

Note: API endpoints are automatically generated from the local OpenAPI file defined in docs.json.

Kaneo consists of three primary architectural components:

• API: The backend service built with Hono and TypeScript.
• Web: The frontend React application styled with Tailwind CSS.
• Database: The data persistence layer built with PostgreSQL.

Kaneo provides several core functional workflows to manage work and collaboration:

• Workspace and Project Management: Create new workspaces and projects.
• Task Management: Plan and execute tasks using Board, List, or Backlog views.
• Team Collaboration: Tools and methods for collaborating with team members.
• Workflow Customization: Configure project-specific workflows and manage workspace labels.
• Personalization: Customize your individual workspace experience.

To get a running instance of Kaneo, follow these paths based on your needs:

• Fastest path: Use the Quick Start guide.
• Deployment choice: Use the Installation Guide to decide between drim or Docker Compose.
• Integrations:
  • Set up GitHub Integration for repository synchronization.
  • Set up Gitea Integration for self-hosted Gitea environments.
  • Configure Outgoing webhooks to send notifications to Slack, Discord, or custom HTTP endpoints.
• Programmatic access: Refer to the API Introduction for details on authenticated API usage.

Use the device flow for CLIs, desktop apps, or clients that require browser-based sign-in. This flow returns a Bearer token.

Flow Overview

1. Request a device code: Call /api/auth/device/code with your client_id.
2. User Verification: The user visits the returned verification_uri in a browser to approve access.
3. Poll for token: Your app polls /api/auth/device/token using the device_code.
4. Access API: Once a token is issued, use it in the Authorization: Bearer <token> header.

Configuration Note

For self-hosted Kaneo, the instance operator must allow custom client IDs via the DEVICE_AUTH_CLIENT_IDS environment variable. Built-in clients include kaneo-cli and kaneo-mcp.

For public deployments, expose MinIO on its own hostname (e.g., https://files.cloud.kaneo.app) using a reverse proxy like Caddy, Nginx, or Traefik.

Requirements:

• A created bucket.
• A dedicated, non-root MinIO user with access limited to that bucket.
• MinIO CORS configured to allow your Kaneo origin.
• No anonymous bucket read policy is required.

S3_ENDPOINT=https://files.cloud.kaneo.app
S3_BUCKET=kaneo-uploads
S3_ACCESS_KEY_ID=kaneo
S3_SECRET_ACCESS_KEY=<generate-a-strong-random-secret>
S3_REGION=us-east-1
S3_FORCE_PATH_STYLE=true

To migrate a Kaneo instance from v1 to v2, follow these steps:

1. Backup your database: Ensure you have a complete backup before proceeding.
2. Update Environment Variables: Kaneo v2 now uses a .env file for configuration.
3. Rename JWT Secret: The v1 variable JWT_ACCESS must be renamed to AUTH_SECRET in your configuration.
4. Update Compose File: Ensure your Docker Compose services (such as api and web) are configured to load the .env file using the env_file directive.

For broader configuration beyond personal preferences, use the following settings paths:

• Settings -> Workspace: Manage workspace-level details, such as workspace labels.
• Settings -> Projects: Configure project-specific settings including general info, visibility, integrations, and workflows.

Before a channel can be used for specific workspaces, it must be configured at the account level via connection cards. Supported channels include:

• Email: Uses the signed-in account's email address. Requires SMTP to be configured on the Kaneo server.
• ntfy: Requires a server URL and a topic (optionally a bearer token).
• Gotify: Requires a server URL and an application token (bearer token). You must create an application in your Gotify server first. Kaneo sends directly to the Gotify message API.
• Custom webhook: Requires a destination URL and an optional signing secret.

To set up a local development environment for Kaneo:

1. Create a .env file in the project root containing the required environment variables.
2. Run the development servers using pnpm dev.

This command starts both the API (on port 1337) and the web app (on port 5173) with automatic reloading. The web app at http://localhost:5173 is pre-configured to connect to the API at http://localhost:1337.

You can use fs instead of MinIO by pointing the S3_* variables to its endpoint.

Requirements for fs:

• Set S3_FORCE_PATH_STYLE=true.
• Create buckets via the S3 API or CLI (not a web console).
• You may need to handle CORS via a reverse proxy as fs does not currently implement S3 CORS APIs.

To customize your personal view and workspace settings, navigate to the settings menu:

1. Go to Settings.
2. Open Account -> Preferences.