# How to Configure Pluggable Compression Engines in OmniRoute: A Complete Guide

> Configure pluggable compression engines in OmniRoute with this comprehensive guide. Learn to combine strategies like lite, caveman, and ultra via JSON, CLI, API, or UI.

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

---

**OmniRoute uses a pluggable compression engine architecture that lets you combine multiple compression strategies—lite, caveman, aggressive, ultra, RTK, and Codex-Responses—through JSON configuration, CLI commands, REST API calls, or the Compression Studio UI.**

Configuring pluggable compression engines in OmniRoute requires understanding the type-safe schema system built on Zod validation. The framework allows you to stack engines in pipelines, set intensity levels per engine, and auto-trigger different modes based on token budgets. This article walks through the configuration model, runtime flow, and practical methods to configure compression using code examples from the OmniRoute source.

## Configuration Model and Core Schemas

All compression settings in OmniRoute validate against the **`compressionSettingsUpdateSchema`** defined in [[`src/shared/validation/compressionConfigSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/compressionConfigSchemas.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/shared/validation/compressionConfigSchemas.ts). This schema enforces type safety across every configuration surface.

A complete compression configuration includes these key fields:

- **`enabled`** – global on/off switch for the entire subsystem
- **`defaultMode`** / **`autoTriggerMode`** – base engine selection (`off`, `lite`, `standard`, `aggressive`, `ultra`, `rtk`, `codex-responses`)
- **`stackedPipeline`** – ordered array of engine steps, each with `engine`, optional `intensity`, and optional per-engine `config`
- **Per-engine blocks** – `cavemanConfig`, `aggressiveConfig`, `ultraConfig`, etc., for engine-specific knobs
- **`exclusions`** – regex patterns preventing compression on matching models or endpoints
- **`autoTriggerTokens`** – threshold for automatically switching engines on large requests
- **`comboOverrides`** – per-combo engine choices that override global defaults

The **engine catalog** (`STACKED_PIPELINE_ENGINE_INTENSITIES`) in [[`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/lib/db/compression.ts) serves as the single source of truth. Every `engine`/`intensity` combination accepted by the API must exist in this catalog, preventing drift between UI, schema, and runtime.

## Runtime Configuration Flow

Understanding the runtime flow helps debug configuration issues and build custom integrations:

1. **Request ingestion** – The API handler at [[`src/app/api/internal/codex-responses-ws/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/app/api/internal/codex-responses-ws/compression.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/api/internal/codex-responses-ws/compression.ts) reads persisted JSON from the `compression` database table
2. **Schema validation** – Incoming PUT bodies validate against Zod schemas before any persistence
3. **Database persistence** – Validated configs write to SQLite via helpers in [[`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/lib/db/compression.ts)
4. **Propagation** – The new configuration reaches:
   - **MCP server** through [[`open-sse/mcp-server/tools/compressionTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/compressionTools.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/tools/compressionTools.ts) for remote tooling
   - **Chat handlers** via [[`open-sse/handlers/chatCore/compressionSettings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore/compressionSettings.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/handlers/chatCore/compressionSettings.ts), which reads current config per-request
5. **Telemetry logging** – Each compression run logs to [[`src/lib/db/compressionRunTelemetry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compressionRunTelemetry.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/lib/db/compressionRunTelemetry.ts) for analytics and UI charts

## Method 1: Configure Pluggable Compression Engines via REST API

The `/api/settings/compression` endpoint provides full programmatic control. Use PUT to update settings and GET to retrieve current configuration.

### Update Compression Settings with cURL

```bash
curl -X PUT https://localhost:20128/api/settings/compression \
  -H "Authorization: Bearer $OMNIRoute_JWT" \
  -H "Content-Type: application/json" \
  -d '{
        "enabled": true,
        "defaultMode": "standard",
        "stackedPipeline": [
          { "engine": "caveman", "intensity": "lite", "config": { "compressRoles": ["assistant"] } },
          { "engine": "rtk",      "intensity": "standard" }
        ],
        "exclusions": ["^gpt-4.*$", "^anthropic/.*$"],
        "autoTriggerTokens": 4096,
        "autoTriggerMode": "aggressive"
      }'

```

The request body conforms to `compressionSettingsUpdateSchema`. The `stackedPipeline` array chains engines sequentially—output from caveman becomes input to RTK in this example.

### Retrieve Current Settings

```bash
curl -X GET https://localhost:20128/api/settings/compression \
  -H "Authorization: Bearer $OMNIRoute_JWT"

```

## Method 2: Configure Compression Engines Using the CLI

The OmniRoute CLI at [`bin/cli/commands/compression.mjs`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/bin/cli/commands/compression.mjs) wraps the same REST endpoints for convenient terminal access.

### Inspect Current Configuration

```bash
omniroute compression get

```

### Set a Global Engine with Specific Intensity

```bash
omniroute compression set --engine ultra --intensity ultra --enabled true

```

The CLI parses arguments, builds a `compressionSettingsUpdateSchema`-compliant payload, and sends the PUT request automatically.

### Programmatic CLI Integration in Node.js

```javascript
import { execSync } from 'child_process';

// Get current settings as JSON
const current = JSON.parse(execSync('omniroute compression get --json').toString());

// Modify and apply
const updated = {
  ...current,
  stackedPipeline: [
    { engine: 'lite', intensity: 'standard' },
    { engine: 'codex-responses', config: { preserveContext: true } }
  ]
};

execSync(`omniroute compression set --json '${JSON.stringify(updated)}'`);

```

## Method 3: Configure Compression via MCP Tools

The MCP server integration in [[`open-sse/mcp-server/tools/compressionTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/compressionTools.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/open-sse/mcp-server/tools/compressionTools.ts) exposes compression settings to remote debugging tools and AI assistants.

```javascript
// Within an MCP tool implementation
const compressionTools = await mcpServer.getTools('compression');

// Read current configuration
const config = await compressionTools.getCompressionSettings();

// Update with validated payload
await compressionTools.updateCompressionSettings({
  enabled: true,
  defaultMode: 'rtk',
  stackedPipeline: [
    { engine: 'rtk', intensity: 'aggressive' }
  ]
});

```

## Method 4: Configure Using the Compression Studio UI

For visual configuration, the Compression Studio in [`src/app/(dashboard)/dashboard/compression/studio/compressionFlowModel.ts`](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/app/(dashboard)/dashboard/compression/studio/compressionFlowModel.ts) provides:

- Drag-and-drop engine reordering in the `stackedPipeline`
- Intensity sliders per engine
- Live telemetry visualization from `compressionRunTelemetry`
- Combo override editors for per-combo engine customization

The UI model validates all changes against the same Zod schemas before API submission, ensuring database consistency.

## Extending the Engine Set: Adding Custom Compression Engines

To add a new pluggable compression engine to OmniRoute:

1. **Define the Zod schema** in [`compressionConfigSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compressionConfigSchemas.ts):

```typescript
// src/shared/validation/compressionConfigSchemas.ts
export const myEngineConfigSchema = z.object({
  customParam: z.number().min(0).max(100),
  preserveNewlines: z.boolean().default(true),
});

```

2. **Register in the engine catalog** in [`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts):

```typescript
export const STACKED_PIPELINE_ENGINE_INTENSITIES = {
  // existing engines...
  myEngine: ['lite', 'standard', 'aggressive', 'ultra'],
} as const;

```

3. **Update the database normalizer** to handle migration and persistence of the new engine's configuration structure.

4. **Implement runtime logic** in [`open-sse/handlers/chatCore/myEngine.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore/myEngine.ts) if the engine requires custom processing.

5. **Add UI components** in the Compression Studio if custom settings visualization is needed.

6. **Write round-trip tests** verifying GET → PUT → GET preserves the new engine configuration (see [`compression-engines-map-migration.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compression-engines-map-migration.test.ts) for patterns).

## Available Engine Types and Intensity Levels

| Engine | Description | Typical Intensities |
|--------|-------------|---------------------|
| **lite** | Fast, minimal compression preserving structure | lite, standard |
| **caveman** | Aggressive token reduction with role-based filtering | lite, standard, aggressive |
| **standard** | Balanced compression for general use | lite, standard |
| **aggressive** | Maximum reduction, may affect readability | standard, aggressive, ultra |
| **ultra** | Extreme compression for cost-critical paths | ultra |
| **rtk** | Retrieval-optimized compression preserving semantic structure | lite, standard, aggressive |
| **codex-responses** | Code-specific compression for API responses | standard, aggressive |

## Summary

- **Schema-driven configuration** – All compression settings validate through Zod schemas in [`compressionConfigSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compressionConfigSchemas.ts), ensuring type safety across API, CLI, MCP, and UI surfaces.

- **Four configuration methods** – Use REST API for automation, CLI for terminal workflows, MCP tools for remote debugging, or Compression Studio for visual pipeline editing.

- **Stacked pipeline architecture** – Chain multiple engines via the `stackedPipeline` array, with each engine's output feeding the next input.

- **Engine catalog enforcement** – The `STACKED_PIPELINE_ENGINE_INTENSITIES` map in [`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts) prevents invalid engine/intensity combinations.

- **Extension pathway** – Add new engines by defining schemas, registering in the catalog, updating database normalizers, and implementing runtime handlers.

## Frequently Asked Questions

### What file contains the compression engine schemas in OmniRoute?

The central Zod schemas reside in [[`src/shared/validation/compressionConfigSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/compressionConfigSchemas.ts)](https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/shared/validation/compressionConfigSchemas.ts). This file defines `compressionSettingsUpdateSchema` and every per-engine configuration schema, serving as the type contract for all configuration surfaces.

### How does OmniRoute validate compression engine configurations?

Validation occurs through Zod schema parsing at multiple layers. The API handler validates PUT bodies against `compressionSettingsUpdateSchema`. The database normalizer ensures persisted configs match expected shapes. The UI model validates user input before API submission. This layered approach prevents invalid configurations from reaching the runtime pipeline.

### Can I stack multiple compression engines in a single pipeline?

Yes. The `stackedPipeline` array in your configuration accepts multiple engine steps. Each step specifies an `engine`, optional `intensity`, and optional `config`. Engines execute sequentially—step N+1 receives the output from step N. This design allows combining specialized engines (e.g., caveman for role filtering followed by RTK for semantic compression).

### What triggers auto-trigger mode in OmniRoute compression?

The `autoTriggerTokens` field sets a token threshold. When a request exceeds this count, OmniRoute automatically switches from `defaultMode` to `autoTriggerMode`. This lets you use lightweight compression for small requests and aggressive engines only when necessary, optimizing the latency/cost tradeoff.