What Is the Purpose of the Config Directory in Karakeep?

The config directory in Karakeep serves as a centralized, type-safe configuration module that validates environment variables using Zod and exposes a single source of truth for all runtime settings across the web server, CLI, workers, and background jobs.

The Karakeep repository relies on a robust configuration system to manage runtime settings across its monorepo architecture. The config directory—specifically the centralized config.ts files—provides a typed schema for environment variables, ensuring consistent behavior whether you're running the web server, CLI tools, or background workers. This architecture eliminates "magic strings" scattered throughout the codebase by exposing a single, validated configuration object that the entire application consumes.

Centralized Configuration Architecture

Type-Safe Schema Validation with Zod

The configuration system uses Zod to define strict schemas for every environment variable. According to the Karakeep source code, this validation ensures that required variables are present and shaped correctly before the application starts. Located at packages/shared/config.ts, the central module groups related settings into logical sections—database, email, asset storage, rate-limiting, Redis, Stripe, OpenTelemetry, and Prometheus—each with inline documentation.

The serverConfig Object

The serverConfig object acts as the single source of truth for all runtime values. Instead of accessing process.env directly throughout the codebase, Karakeep components import this typed object from @/shared/config. This pattern prevents configuration drift and makes it easy to modify settings in one location while maintaining type safety across TypeScript files.

Key Responsibilities of the Config Directory

• Schema Validation: The config directory enforces that all environment variables match their expected types using Zod parsers, triggering clear runtime errors when required fields are missing.

• Logical Grouping: Settings are organized into functional categories. Database connection strings, SMTP hosts for email verification, and Redis cache endpoints each live in dedicated sections within packages/shared/config.ts.

• Default Values: Optional configuration keys receive sensible defaults (such as feature flags disabled by default), while still allowing overrides via .env files or environment variables.

• Cross-Component Consistency: The same configuration object powers the web server, CLI interface, workers, and background jobs, ensuring uniform behavior across all Karakeep deployment targets.

Implementation Across the Monorepo

The configuration system spans multiple files to support different execution contexts:

• Core Module: packages/shared/config.ts contains the central, type-safe definition of all server-wide settings.
• CLI Wrapper: apps/cli/src/lib/config.ts provides a thin wrapper that forwards environment variables to the shared config.
• Frontend Exposure: packages/trpc/routers/config.ts implements a TRPC endpoint that serves configuration values to the frontend, particularly for feature flags.

Accessing Configuration Values

Any package in the monorepo can import settings from the shared module:

// Import the shared configuration object
import serverConfig from "@/shared/config";

const dbUrl = serverConfig.database.url;          // Database connection string
const emailHost = serverConfig.email.smtpHost;    // SMTP host for verification emails

Feature Flags and Optional Settings

The config directory handles optional feature toggles with fallback values:

import serverConfig from "@/shared/config";

if (serverConfig.features.enableAI) {
  // Initialise AI tagging service
}

// Providing a fallback for optional Redis configuration
const redisHost = serverConfig.redis?.host ?? "localhost";

CLI-Specific Configuration

The CLI tool maintains its own configuration wrapper while leveraging the shared schema:

import cliConfig from "@/apps/cli/src/lib/config";

console.log("Running with API key:", cliConfig.KARAKEEP_API_KEY);

Summary

• The config directory in Karakeep centralizes all runtime settings into a type-safe module using Zod validation.
• File locations: packages/shared/config.ts (core), apps/cli/src/lib/config.ts (CLI), and packages/trpc/routers/config.ts (frontend API).
• Code pattern: Replace direct process.env access with imports from @/shared/config to leverage the serverConfig object.
• Benefits: Schema validation prevents runtime errors, logical grouping improves maintainability, and consistent defaults ensure reliable deployments across web servers, workers, and CLI tools.

Frequently Asked Questions

Where is the main configuration file located in Karakeep?

The primary configuration module lives at packages/shared/config.ts. This file contains the Zod schema definitions and the exported serverConfig object that validates all environment variables at runtime. The CLI maintains a separate wrapper at apps/cli/src/lib/config.ts that forwards variables to this shared module.

How does Karakeep validate environment variables?

Karakeep uses Zod to define typed schemas for every configuration option. When the application starts, the config directory parses process.env against these schemas, throwing clear runtime errors if required variables are missing or malformed. This validation happens in packages/shared/config.ts before any other modules initialize.

Can I access Karakeep configuration from the frontend?

Yes, through the TRPC router located at packages/trpc/routers/config.ts. This endpoint exposes specific configuration values (such as feature flags) to the frontend while keeping sensitive settings server-side. The router reads from the same serverConfig object used by the backend, ensuring consistency between client and server behavior.

What happens if an optional configuration value is missing?

Optional values in the Karakeep config directory receive sensible defaults defined in the Zod schema. For example, Redis host settings might default to "localhost" if not specified. You can also implement runtime fallbacks using optional chaining: serverConfig.redis?.host ?? "localhost".

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