How to Deploy OmniRoute Using Docker with AMD64/ARM64 Support

OmniRoute provides multi-architecture Docker images based on node:24-trixie-slim that automatically support both AMD64 and ARM64 platforms through Docker Buildx, with three distinct runtime targets (runner-base, runner-web, and runner-cli) tailored to different deployment needs.

OmniRoute ships with first-class Docker support including multi-architecture builds for both AMD64 and ARM64 processors. The containerization strategy implemented in the diegosouzapw/OmniRoute repository uses a security-hardened node:24-trixie-slim base image and offers flexible runtime profiles that let you deploy everything from a minimal server to a fully-featured installation with Playwright and CLI tools.

Multi-Architecture Base Image

The OmniRoute Dockerfile leverages the official node:24-trixie-slim image as its foundation, which provides native support for both AMD64 and ARM64 architectures without requiring separate build files. Because the base image uses a single FROM node:24-trixie-slim statement at the top of the Dockerfile, Docker automatically selects the appropriate architecture variant at build time. The base image includes recent Debian security patches (referenced in Dockerfile lines 2-10) and installs only the runtime dependencies required by OmniRoute.

Three Runtime Targets

The Docker build defines three distinct runtime targets that inherit from the same security-hardened base, allowing you to choose the image size and capabilities based on your use case:

runner-base – The minimal runtime that includes only the core OmniRoute server without additional CLI tools. This target is defined in Dockerfile lines 86-99 and produces the smallest image footprint.

runner-web – Adds Chromium and Playwright binaries required for web-cookie authentication providers such as Gemini-Web and Claude-Web. This target extends runner-base and is configured in Dockerfile lines 120-135.

runner-cli – Bundles the OmniRoute CLI tools including codex, claude-code, and other global npm packages. This target is specified in Dockerfile lines 88-106.

Building Multi-Platform Images

While the project publishes pre-built images to Docker Hub for both architectures (as documented in README.md lines 54-66), you can build your own multi-architecture image using Docker Buildx:

# Enable experimental Buildx support (once per machine)

docker buildx create --use

# Build and push a manifest that serves both amd64 and arm64

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --target runner-base \
  -t diegosouzapw/omniroute:latest \
  --push .

Replace --target runner-base with runner-web or runner-cli to include Playwright or CLI tools respectively.

Running OmniRoute Containers

Minimal Server Deployment

To run the core OmniRoute server without additional dependencies:

docker run -d \
  -p 20128:20128 \
  -v $(pwd)/data:/app/data \
  --name omniroute \
  diegosouzapw/omniroute:latest

Web-Enabled Deployment

For providers requiring browser automation (Gemini-Web, Claude-Web):

docker run -d \
  -p 20128:20128 \
  -v $(pwd)/data:/app/data \
  --name omniroute-web \
  diegosouzapw/omniroute:web

CLI-Enabled Deployment

To include bundled CLI tools:

docker run -d \
  -p 20128:20128 \
  -v $(pwd)/data:/app/data \
  --name omniroute-cli \
  diegosouzapw/omniroute:cli

All containers start as a non-root user (node) for security, as configured in Dockerfile lines 31-36.

Docker Compose Deployment (Recommended)

The docker-compose.yml file provides ready-made profiles documented in lines 5-22 that handle volume mounting and service dependencies. The compose configuration mounts a host ./data directory into /app/data within the container (lines 42-43) to ensure SQLite databases, migrations, and user configuration survive container restarts.

Deploy the minimal server:

docker compose --profile base up -d

Deploy with Playwright support:

docker compose --profile web up -d

Deploy with CLI tools:

docker compose --profile cli up -d

Add optional side-cars such as Qdrant for memory storage or Bifrost for routing:

docker compose --profile base --profile memory up -d
docker compose --profile base --profile bifrost up -d

Security and Health Monitoring

The container implements security hardening through a non-root execution context (node user) and includes a built-in health check defined in Dockerfile lines 41-44. The health check runs node healthcheck.mjs every 30 seconds to verify service availability.

Verify your deployment is healthy:

curl http://localhost:20128/healthz

The endpoint returns a JSON response with status "ok" when the container is ready to serve traffic at http://localhost:20128/v1.

Summary

• OmniRoute uses node:24-trixie-slim as an architecture-agnostic base that automatically supports both AMD64 and ARM64 processors.
• Three build targets (runner-base, runner-web, runner-cli) allow you to optimize image size by including only required dependencies.
• Docker Buildx enables building multi-platform manifests with --platform linux/amd64,linux/arm64.
• Docker Compose profiles (base, web, cli, memory, bifrost) provide production-ready deployment configurations with persistent data volumes.
• Containers run as non-root user node and expose a /healthz endpoint for monitoring.

Frequently Asked Questions

Does OmniRoute support Apple Silicon (M1/M2/M3) Macs?

Yes. Because the node:24-trixie-slim base image provides ARM64 variants, OmniRoute runs natively on Apple Silicon Macs without Rosetta emulation. Docker automatically pulls the correct architecture when you run docker pull diegosouzapw/omniroute:latest on an ARM64 host.

What is the difference between the runner-web and runner-cli targets?

The runner-web target adds Chromium and Playwright binaries to support web-based authentication providers like Gemini-Web and Claude-Web, while runner-cli bundles command-line tools such as codex and claude-code. Both targets extend runner-base, but they serve different use cases: choose runner-web for browser automation needs and runner-cli for terminal-based AI tool integration.

How do I persist data when restarting the container?

Mount a host directory to /app/data using the -v $(pwd)/data:/app/data flag in Docker or the volume definition in docker-compose.yml lines 42-43. This directory stores SQLite databases, migration files, and user configuration, ensuring data survives container recreation.

Which deployment method is recommended for production?

Use Docker Compose with profiles rather than standalone docker run commands. The compose file handles network configuration, volume persistence, and optional service dependencies (like Qdrant or Bifrost) declaratively. The base profile suits most production deployments, while web is required only if using web-cookie authentication providers.

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