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

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/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/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/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/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/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/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/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

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

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 wraps the same REST endpoints for convenient terminal access.

Inspect Current Configuration

omniroute compression get

Set a Global Engine with Specific Intensity

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

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/release/v3.8.50/open-sse/mcp-server/tools/compressionTools.ts) exposes compression settings to remote debugging tools and AI assistants.

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

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

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 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 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, 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 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/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.

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