# How to Use OmniRoute Compression Studio with Pluggable Engines: A Complete Guide

> Master OmniRoute compression studio with pluggable engines. Configure and fine-tune compression strategies via API, CLI, or the visual interface for optimal performance.

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

---

**TLDR;** OmniRoute’s compression subsystem uses a pluggable engine architecture that lets you chain, configure, and fine-tune compression strategies through a REST API, CLI, or visual Compression Studio interface, all validated by central Zod schemas.

OmniRoute is an open-source routing platform that includes a sophisticated compression subsystem designed to optimize token usage across LLM interactions. The **OmniRoute Compression Studio** provides a visual interface and programmatic APIs for configuring **pluggable compression engines** that can be stacked, customized, and triggered automatically based on token thresholds.

## Understanding the Pluggable Architecture

The compression system is built around a runtime engine catalog and strict schema validation. Every engine is defined in the `STACKED_PIPELINE_ENGINE_INTENSITIES` map located in [`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts), which serves as the source of truth for available engines and their supported intensity levels. This catalog drives both the UI dropdowns in the Compression Studio and the API validation layer.

The central validation logic lives in [`src/shared/validation/compressionConfigSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/compressionConfigSchemas.ts). Here, the `compressionSettingsUpdateSchema` Zod object defines the complete configuration contract, including the `stackedPipeline` array that allows you to chain multiple engines sequentially. Each pipeline step specifies an `engine` identifier, optional `intensity` level, and engine-specific `config` parameters.

## Configuring Engines via the REST API

The HTTP API exposes compression settings through the `/api/settings/compression` endpoint. You can retrieve current settings with a GET request or update the entire configuration using PUT with a payload that conforms to the `compressionSettingsUpdateSchema`.

To enable a stacked pipeline with multiple engines:

```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/.*$"]
      }'

```

The `stackedPipeline` array processes engines in order, passing the output of one engine as input to the next. The `exclusions` array accepts regex patterns to bypass compression for specific model patterns.

## Using the CLI for Compression Management

OmniRoute provides a dedicated CLI command at `bin/cli/commands/compression.mjs` for inspecting and modifying compression settings without writing HTTP clients.

To view current configuration:

```bash
omniroute compression get

```

This command internally executes a GET request to `/api/settings/compression` and formats the JSON response for terminal readability.

To set a global engine with specific intensity:

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

```

The CLI parses arguments, constructs a valid `compressionSettingsUpdateSchema` payload, and sends the PUT request automatically.

## Building Stacked Pipeline Configurations

The `stackedPipeline` field in your configuration enables sophisticated processing chains. Each step in the array is validated against the `stackedPipelineStepSchema`, which ensures the `engine` value exists in the `ENGINE_CATALOG` and that the requested `intensity` is supported for that engine.

Key configuration fields include:

- **autoTriggerTokens**: Automatically switches from `defaultMode` to `autoTriggerMode` when requests exceed the specified token count
- **comboOverrides**: Per-combination engine selections stored in the `compressionCombos` table that override global defaults
- **Per-engine blocks**: Typed configuration objects like `cavemanConfig`, `aggressiveConfig`, or `ultraConfig` that expose engine-specific knobs

The database layer in [`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts) persists these settings to SQLite, while [`compressionRunTelemetry.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compressionRunTelemetry.ts) logs execution metrics for each compression run.

## Programmatic Integration with Node.js

For custom tooling, interact directly with the compression API using standard HTTP clients:

```javascript
import fetch from 'node-fetch';

const resp = await fetch('http://localhost:20128/api/settings/compression', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${process.env.OMNIRoute_JWT}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    enabled: true,
    defaultMode: 'lite',
    stackedPipeline: [{ engine: 'lite' }],
  }),
});

const data = await resp.json();
console.log('Compression updated:', data);

```

## Extending the Engine Set

To add a custom compression engine to OmniRoute:

1. **Define the schema**: Add a new Zod schema (e.g., `myEngineConfigSchema`) in [`src/shared/validation/compressionConfigSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/shared/validation/compressionConfigSchemas.ts)
2. **Register in catalog**: Update `STACKED_PIPELINE_ENGINE_INTENSITIES` in [`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts) with the engine ID and supported intensities
3. **Update persistence**: Modify the DB normalizer in [`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts) to handle the new engine in migrations
4. **Implement runtime logic**: Create a handler under `open-sse/handlers/chatCore/` if the engine requires request-time processing
5. **Add UI support**: Extend the Compression Studio in `src/app/(dashboard)/dashboard/compression/studio/compressionFlowModel.ts` if custom UI components are needed
6. **Verify with tests**: Add unit tests ensuring GET→PUT round-tripping works correctly, following patterns in [`compression-engines-map-migration.test.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compression-engines-map-migration.test.ts)

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) automatically exposes new engines to remote debugging tools once registered.

## Summary

- OmniRoute uses **Zod schemas** in [`compressionConfigSchemas.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/compressionConfigSchemas.ts) to validate all engine configurations type-safely
- The **engine catalog** in [`src/lib/db/compression.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/compression.ts) maintains the canonical list of available engines and intensity levels
- Configure engines via **REST API** (`/api/settings/compression`), **CLI** (`omniroute compression`), or the **Compression Studio** UI
- Use **stacked pipelines** to chain multiple engines, with output from each feeding into the next
- **Auto-trigger tokens** enable automatic mode switching based on request size
- Extend the system by adding schemas to the validation layer and registering engines in the database catalog

## Frequently Asked Questions

### How do I exclude specific models from compression?

Use the `exclusions` array in your compression settings payload. This field accepts JavaScript regex patterns as strings. For example, `["^gpt-4.*$", "^anthropic/.*$"]` prevents compression on any GPT-4 or Anthropic models. The patterns are evaluated at runtime in [`open-sse/handlers/chatCore/compressionSettings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/handlers/chatCore/compressionSettings.ts).

### What is the difference between defaultMode and stackedPipeline?

The `defaultMode` specifies a single engine to use when `stackedPipeline` is empty or when auto-trigger conditions aren't met. The `stackedPipeline` array overrides this behavior by allowing you to chain multiple engines sequentially. If both are configured, `stackedPipeline` takes precedence for processing flow while `defaultMode` serves as a fallback label.

### Can I use the Compression Studio UI and API simultaneously?

Yes. The Compression Studio (`src/app/(dashboard)/dashboard/compression/studio/compressionFlowModel.ts`) operates on the same underlying database tables and API endpoints as the REST interface. Changes made through the drag-and-drop UI immediately persist via the same PUT requests to `/api/settings/compression`, ensuring consistency across CLI, UI, and programmatic access.

### How does the MCP server expose compression settings?

The MCP server loads compression configurations through [`open-sse/mcp-server/tools/compressionTools.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/open-sse/mcp-server/tools/compressionTools.ts), which interfaces with the same SQLite persistence layer used by the HTTP API. This allows remote debugging tools and AI assistants to read current engine configurations and trigger compression runs without direct database access.