# What Is the Purpose of the Config Directory in Karakeep?

> Discover the purpose of the config directory in Karakeep. It offers type-safe configuration and validates environment variables for consistent settings across your application.

- Repository: [Karakeep App/karakeep](https://github.com/karakeep-app/karakeep)
- Tags: how-to-guide
- Published: 2026-07-07

---

**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`](https://github.com/karakeep-app/karakeep/blob/main/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`](https://github.com/karakeep-app/karakeep/blob/main/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`](https://github.com/karakeep-app/karakeep/blob/main/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`](https://github.com/karakeep-app/karakeep/blob/main/packages/shared/config.ts) contains the central, type-safe definition of all server-wide settings.
- **CLI Wrapper**: [`apps/cli/src/lib/config.ts`](https://github.com/karakeep-app/karakeep/blob/main/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`](https://github.com/karakeep-app/karakeep/blob/main/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:

```typescript
// 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:

```typescript
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:

```typescript
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`](https://github.com/karakeep-app/karakeep/blob/main/packages/shared/config.ts) (core), [`apps/cli/src/lib/config.ts`](https://github.com/karakeep-app/karakeep/blob/main/apps/cli/src/lib/config.ts) (CLI), and [`packages/trpc/routers/config.ts`](https://github.com/karakeep-app/karakeep/blob/main/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`](https://github.com/karakeep-app/karakeep/blob/main/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`](https://github.com/karakeep-app/karakeep/blob/main/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`](https://github.com/karakeep-app/karakeep/blob/main/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`](https://github.com/karakeep-app/karakeep/blob/main/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"`.