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

> Learn how to configure the OmniRoute data directory by setting the DATA_DIR environment variable. Control where your SQLite database and persistent files are stored.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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:

```bash

# From .env.example

cp .env.example .env

```

Edit `.env`:

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

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

```

### **Programmatic Override in Tests**

Set before any OmniRoute import:

```typescript
// 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`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/databaseSettings.ts) | Implements `DATA_DIR` resolution hierarchy |
| [`src/lib/db/core.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/core.ts) | Creates SQLite connection using resolved path |
| `.env.example` | Environment variable template |
| [`tests/unit/zenmux-models-fetch-4202.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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`](https://github.com/diegosouzapw/OmniRoute/blob/main/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.