Does OmniRoute Support Docker? Complete Setup Guide with Examples

Yes, OmniRoute fully supports Docker with multi-stage builds, Docker-Compose configurations, and runtime container detection.

OmniRoute treats Docker as a first-class deployment target. The diegosouzapw/OmniRoute repository ships everything needed to build, configure, and run the application in containers — from production-ready images to environment-specific Compose files and runtime detection logic.

Docker Support Overview

OmniRoute's Docker implementation spans three layers:

• Build layer: Multi-stage Dockerfile with separate base, builder, and runner stages
• Orchestration layer: Docker-Compose files for development and production
• Runtime layer: Automatic container detection that adapts feature behavior

This architecture keeps images lean while preserving full functionality for both the API backend and the Next.js dashboard.

Building the OmniRoute Docker Image

The repository's Dockerfile (at the repository root) defines a multi-stage build process using node:26-trixie-slim as the base image. Lines 2–28 handle dependency installation, while lines 125–232 produce the optimized runtime images.

Build the image locally:

docker build -t omniroute:latest .

The build produces separate outputs for the web UI and CLI components, minimizing final image size by excluding build-time dependencies.

Running OmniRoute in Docker

Launch a container with the standard port mappings and persistent storage:

docker run -d \
  -p 20131:20131 \
  -p 20130:20130 \
  -e DATA_DIR=/data \
  -v omniroute-data:/data \
  --name omniroute \
  omniroute:latest

Port 20131 exposes the API endpoint; port 20130 serves the web dashboard. The DATA_DIR environment variable ensures data persists across container restarts.

Docker-Compose Configuration

OmniRoute provides two Compose files for different environments.

Production Deployment

The docker-compose.prod.yml file configures production-ready services:

services:
  omniroute:
    image: omniroute:latest
    ports:
      - "${PROD_API_PORT:-20131}:20131"
      - "${PROD_DASHBOARD_PORT:-20130}:20130"
    environment:
      - DATA_DIR=/data
    volumes:
      - omniroute-data:/data
volumes:
  omniroute-data:

Deploy with:

docker compose -f docker-compose.prod.yml up -d

Development Setup

The standard docker-compose.yml includes additional tooling like hot-reload volumes and the optional VNC-Chromium container for browser-automation providers. See docker/vnc-browser/README.md for configuration details.

Environment Variables for Docker

The docs/reference/ENVIRONMENT.md file documents Docker-specific variables:

Variable	Purpose	Default
DATA_DIR	Persistent data mount point	/data
PROD_API_PORT	API service port binding	20131
PROD_DASHBOARD_PORT	Dashboard port binding	20130

These variables are consumed by the container entrypoint and the Next.js runtime configuration.

Runtime Docker Detection

OmniRoute detects container execution through src/lib/zed-oauth/dockerDetect.ts. The isRunningInDocker() function checks for /.dockerenv presence and Docker entries in /proc/1/cgroup:

import { isRunningInDocker } from "./src/lib/zed-oauth/dockerDetect.ts";

if (isRunningInDocker()) {
  console.log("Running inside Docker – enabling Docker‑specific features.");
}

This detection enables conditional behavior for:

• Zed IDE token import: Adjusted OAuth flow when running containerized
• MITM stub activation: Modified certificate handling in Docker networks

Unit tests in tests/unit/zed-docker-detect.test.ts verify detection accuracy across Linux cgroup versions.

Advanced: Self-Hosted Model Runner

OmniRoute integrates with Docker-based AI model runners. Deploy a compatible endpoint:

docker run -d -p 12434:12434 \
  -e OMNIROUTE_BASE_PATH=/omniroute \
  omniroute-model-runner:latest

Then configure the UI to use http://localhost:12434/v1 as an OpenAI-compatible provider endpoint, documented in docs/reference/PROVIDER_REFERENCE.md.

Key Docker Files Reference

File Path	Purpose
Dockerfile	Multi-stage build definition (base → builder → runner)
docker-compose.yml	Development orchestration with VNC browser
docker-compose.prod.yml	Production orchestration with env-based ports
docs/guides/DOCKER_GUIDE.md	Official deployment walkthrough
src/lib/zed-oauth/dockerDetect.ts	Runtime container detection
docs/reference/ENVIRONMENT.md	Environment variable reference
docker/vnc-browser/README.md	Browser automation container setup

Summary

• OmniRoute supports Docker through official multi-stage images, Compose files, and runtime detection
• Build with docker build -t omniroute . using the root Dockerfile
• Deploy via docker-compose.prod.yml with configurable ports and persistent volumes
• Configure using Docker-specific environment variables in ENVIRONMENT.md
• Detect container execution at runtime with isRunningInDocker() for feature adaptation

Frequently Asked Questions

What base image does OmniRoute use?

OmniRoute builds on node:26-trixie-slim as specified in the Dockerfile. This Debian-based image provides Node.js 26 while keeping the final runtime image minimal through multi-stage builds that discard build dependencies.

Can I run OmniRoute without Docker-Compose?

Yes. Use docker run with the port mappings and volume mounts shown in the examples above. Docker-Compose is recommended for production to handle environment variables and service dependencies more cleanly.

How does OmniRoute detect it's running in Docker?

The isRunningInDocker() function in src/lib/zed-oauth/dockerDetect.ts checks for /.dockerenv file existence and inspects /proc/1/cgroup for docker or containerd entries. This detection activates Docker-specific code paths for authentication and networking features.

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