How to Configure the Data Directory for OmniRoute: Environment Variable Configuration Guide

Set the DATA_DIR environment variable before starting OmniRoute to control where the SQLite database and persistent files are stored.

OmniRoute determines its data directory at runtime through a resolution hierarchy defined in src/lib/db/databaseSettings.ts. This directory houses the SQLite database (omniroute.db) and all cached provider state. Understanding this configuration is essential for production deployments, containerized environments, and test isolation.

---

How OmniRoute Resolves the Data Directory

The resolution logic in src/lib/db/databaseSettings.ts follows a strict priority order:

1. process.env.DATA_DIR — If set, the trimmed value is used directly.
2. XDG_CONFIG_HOME — Falls back to the XDG base directory standard when available.
3. $HOME/.omniroute — Default location when no environment variables are defined.

The resolved path is then joined with omniroute.db in src/lib/db/core.ts to establish the database connection.

---

Critical Timing: Set Before Import

All components that touch persistent storage read DATA_DIR at import time. This means the variable must be defined before any OmniRoute database module is required.

The test suite enforces this pattern extensively. For example, in tests/unit/zenmux-models-fetch-4202.test.ts, you'll see process.env.DATA_DIR assigned before any database imports.

---

Configuration Methods

.env File (Recommended)

Copy the provided template and customize:

# From .env.example

cp .env.example .env

Edit .env:

DATA_DIR=/var/lib/omniroute
JWT_SECRET=your-secret-key
API_KEY_SECRET=your-api-key

Shell Export for Ad-Hoc Runs

Use for container deployments or temporary overrides:

export DATA_DIR=/mnt/storage/omniroute
npm run dev

Programmatic Override in Tests

Set before any OmniRoute import:

// Test harness setup
process.env.DATA_DIR = '/tmp/omniroute-test';

// Only then import database modules
import { getDbInstance } from '@/src/lib/db/core';
// DB will be created in /tmp/omniroute-test

---

Migrating Existing Data

Changing DATA_DIR after OmniRoute has run requires manual migration:

• Copy omniroute.db from the old location to the new DATA_DIR path.
• OmniRoute automatically creates a new database if none exists, but existing state is lost without migration.
• Cached tokens, combo routing history, and provider state all reside in this file.

---

Key Source Files

File	Purpose
src/lib/db/databaseSettings.ts	Implements DATA_DIR resolution hierarchy
src/lib/db/core.ts	Creates SQLite connection using resolved path
.env.example	Environment variable template
tests/unit/zenmux-models-fetch-4202.test.ts	Demonstrates test-time configuration pattern

---

Summary

• Primary mechanism: DATA_DIR environment variable, resolved in src/lib/db/databaseSettings.ts.
• Timing constraint: Must be set before any database module import.
• Configuration options: .env file, shell export, or programmatic process.env assignment.
• Migration requirement: Copy omniroute.db when changing directories to preserve state.
• Default fallback: $HOME/.omniroute when no variables are configured.

---

Frequently Asked Questions

What happens if I don't set DATA_DIR?

OmniRoute defaults to $HOME/.omniroute according to the resolution logic in src/lib/db/databaseSettings.ts. This works for local development but is rarely suitable for production or containerized deployments.

Can I change the data directory after OmniRoute has started?

No. The path is resolved at module import time in src/lib/db/core.ts. Changing the environment variable after any database module has loaded has no effect. You must restart the process with the new value pre-configured.

Does OmniRoute support relative paths for DATA_DIR?

Yes, but they are resolved relative to the working directory at startup. For predictable behavior, use absolute paths in production—especially in container environments where the working directory may vary.

How do I verify which data directory OmniRoute is using?

Check the resolved path by inspecting process.env.DATA_DIR before imports, or examine the database file location after startup. The test files in tests/unit/ demonstrate reliable patterns for asserting the correct directory in automated scenarios.

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