Container Runtime Support

Overview

Oxy requires a Docker API-compatible endpoint to manage PostgreSQL, ClickHouse, and other containerized services. This means any container runtime that exposes a Docker-compatible API socket.

Important: Oxy communicates via the Docker API (typically through a Unix socket or TCP endpoint). You can use:

Docker Engine (dockerd) - standalone or via Docker Desktop
Podman with Docker socket emulation enabled
Any runtime that provides a Docker-compatible API socket

Note: containerd alone does not expose a Docker API. If using containerd-based runtimes (like Rancher Desktop), select the dockerd (moby) engine option to get Docker API compatibility.

Key Takeaway

TL;DR: Oxy needs a Docker API-compatible socket endpoint, not a specific application.You can use:

Docker Engine installed directly (no GUI)
Docker Desktop, Rancher Desktop (with dockerd/moby), Colima, OrbStack, etc. (with GUI)
Podman with Docker socket emulation

Oxy doesn’t care which one you choose - they all work the same way once installed, as long as they expose a Docker-compatible API socket.

What Oxy Actually Needs

Container Runtime

Docker Engine (dockerd) or any Docker API-compatible runtimeThis is the actual runtime that manages containers

Docker-Compatible API Socket

A Docker API endpoint at:

unix:///var/run/docker.sock (default on Linux/macOS)
npipe:////./pipe/docker_engine (Windows)
Custom location via DOCKER_HOST env var

This is how Oxy communicates with the runtime

The applications listed below (Docker Desktop, Rancher Desktop, etc.) are just convenient ways to install and manage the underlying container engine. You can also install Docker Engine directly without any desktop application - see the “Docker Engine (Standalone)” tab.

Installation Options

You can install a Docker-compatible container engine in several ways:

Installation & Setup

Install Docker Engine Only (No Desktop App)

This installs just the Docker Engine (dockerd) without any GUI application. Perfect for servers or if you prefer a lightweight setup.

Linux Installation

Follow the official Docker Engine installation for your distribution:Ubuntu/Debian:

# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

Fedora/RHEL/CentOS:

sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf install docker-ce docker-ce-cli containerd.io
sudo systemctl start docker

macOS (via Homebrew)

# Install Docker Engine without Docker Desktop
brew install docker docker-compose

# You'll also need a VM to run Linux containers (use Colima)
brew install colima
colima start

Enable Docker Service (Linux)

sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $USER
newgrp docker

Verify Installation

docker ps
oxy start

This is the most lightweight option and recommended for servers and CI/CD environments.

Install Docker Desktop (GUI Application)

Docker Desktop is an application that includes Docker Engine plus a GUI for container management. It’s convenient but not required.

Download Docker Desktop

Download from docker.com for your platform:

macOS (Apple Silicon or Intel)
Windows
Linux

Install and Start

Follow the installer instructions. Docker Desktop includes the Docker Engine and starts it automatically.

Verify Installation

docker ps
oxy start

Install Rancher Desktop (Alternative GUI Application)

Rancher Desktop is another application that can provide the Docker Engine. Like Docker Desktop, it’s just one way to install the engine.

Download Rancher Desktop

Download from rancherdesktop.io for your platform.

Configure Container Engine

Important: Select dockerd (moby) to get a Docker-compatible API.

Open Rancher Desktop
Go to Preferences → Container Engine
Select dockerd (moby) (this provides Docker Engine)
Wait 30-60 seconds for the engine to initialize

Verify Installation

docker ps
oxy start

Why dockerd (moby) and not containerd?

Rancher Desktop can install either:

dockerd (moby) - Provides Docker API socket (✅ Works with Oxy)
containerd - Does NOT expose Docker API (❌ Won’t work with Oxy)

Oxy communicates via the Docker API, which containerd alone does not provide. You must select dockerd (moby) for Oxy compatibility.

Install Colima - Lightweight Container Engine Manager

Colima runs Docker Engine in a lightweight Linux VM on macOS. No heavy desktop application needed.

Install via Homebrew

brew install colima docker

This installs:

Colima (VM manager)
Docker CLI (to communicate with the engine)

Start Colima

colima start

This starts the Docker Engine in a VM.

Verify Installation

docker ps
oxy start

Custom Socket Location

If Colima uses a non-standard socket, set the DOCKER_HOST environment variable:

export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock
oxy start

Add this to your ~/.zshrc or ~/.bashrc to make it permanent.

Colima is extremely lightweight compared to desktop applications, perfect for development on macOS.

Install Podman (Daemonless Alternative)

Podman is a daemonless container engine that can emulate Docker. You can use Podman Desktop (GUI) or just the Podman engine.

Install Podman Engine

Linux:

# Fedora/RHEL/CentOS
sudo dnf install podman

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install podman

macOS:

brew install podman
podman machine init
podman machine start

Windows: Download from podman.io or use Podman Desktop

Enable Docker Socket Compatibility

For Oxy to work, enable Podman’s Docker socket emulation:Linux:

sudo systemctl enable podman.socket
sudo systemctl start podman.socket

macOS/Windows (Podman Machine): The Docker socket is enabled by default with Podman machine.

Verify Installation

docker ps  # or: podman ps
oxy start

Install OrbStack - Fast macOS Container Engine

OrbStack runs Docker Engine with excellent performance on macOS. It’s a lightweight application alternative to Docker Desktop.

Download OrbStack

Download from orbstack.dev

Install and Launch

Follow the installation wizard. OrbStack automatically provides a Docker-compatible API.

Verify Installation

docker ps
oxy start

OrbStack is known for its speed and low resource usage on macOS while providing full Docker compatibility.

Custom Docker Host

For non-standard socket locations or remote Docker hosts, set the DOCKER_HOST environment variable before running Oxy. This is the standard Docker environment variable that Oxy (and the Docker CLI) automatically respects.

Setting DOCKER_HOST

# Unix socket (Colima example)
export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock
oxy start

# TCP connection (remote Docker)
export DOCKER_HOST=tcp://localhost:2375
oxy start

You can add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.

Common Socket Locations

Runtime	Default Socket Location
Docker Desktop	`unix:///var/run/docker.sock` (macOS/Linux)
	`npipe:////./pipe/docker_engine` (Windows)
Rancher Desktop	`unix://$HOME/.rd/docker.sock` (macOS)
	`unix:///var/run/docker.sock` (Linux)
Colima	`unix://$HOME/.colima/default/docker.sock`
Podman	`unix://$XDG_RUNTIME_DIR/podman/podman.sock`
OrbStack	`unix://$HOME/.orbstack/run/docker.sock`

Troubleshooting

Failed to connect to container runtime

Check if runtime is running:

docker ps

Common solutions:

Start your container runtime application
Wait 30-60 seconds for full initialization
Verify Docker CLI works: docker ps
Check DOCKER_HOST environment variable:
```
echo $DOCKER_HOST
```

Rancher Desktop: daemon not responding

Open Rancher Desktop preferences
Switch Container Engine to dockerd (moby)
Restart Rancher Desktop
Wait for full initialization (30-60 seconds)
Retry: oxy start

Colima: connection refused

# Check Colima status
colima status

# Start if not running
colima start

# Verify socket exists
ls -la ~/.colima/default/docker.sock

# Set DOCKER_HOST if using non-default socket
export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock
oxy start

Podman: no such file or directory

Enable Docker socket compatibility:Linux:

sudo systemctl enable podman.socket
sudo systemctl start podman.socket

For Podman Desktop, enable Docker compatibility in settings.

Permission Denied (Linux)

Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Then verify:

docker ps

Enterprise Mode Containers

When using the --enterprise flag, Oxy starts additional containers:

PostgreSQL

Main databasePort: 15432

ClickHouse

Analytics databasePorts: 8123 (HTTP), 9000 (Native)

OpenTelemetry Collector

Observability pipelinePorts: 4317 (gRPC), 4318 (HTTP)

Cube.js

Semantic layerPort: 4000

All container runtimes support these services with identical port mappings.

Performance Considerations

macOS Performance Comparison

Different runtimes have varying performance characteristics on macOS:

OrbStack

Fastest - Lowest resource usage, native performance

Colima

Fast - Good performance, lightweight footprint

Docker Desktop

Good - Excellent compatibility, higher resource usage

Rancher Desktop

Good - Rich features, moderate resource usage

On Linux, all runtimes perform similarly as they use native kernel features.

On Windows, Docker Desktop offers the best support and performance with WSL2 integration.

Clean Start

Remove all Oxy containers and volumes for a fresh start:

oxy start --clean

This removes across all container runtimes:

All Oxy-managed containers
Associated volumes
Container networks (enterprise mode)

Additional Resources

Docker Desktop Docs

Official documentation

Rancher Desktop Docs

Setup and configuration

Colima GitHub

Source and documentation

Podman Desktop Docs

Installation guides

Get Started

Learn about Oxy

MCP Server

Migration

Learn about deployment

Reference Architecture

Hands-on Guides

Authentication

Integrations

Data Sources

Models

Apps

Oxy commands

Configuration

Semantic Layer

​Overview

​Key Takeaway

​What Oxy Actually Needs

Container Runtime

Docker-Compatible API Socket

​Installation Options

​Installation & Setup

​Install Docker Engine Only (No Desktop App)

​Install Docker Desktop (GUI Application)

​Install Rancher Desktop (Alternative GUI Application)

​Install Colima - Lightweight Container Engine Manager

​Install Podman (Daemonless Alternative)

​Install OrbStack - Fast macOS Container Engine

​Custom Docker Host

​Setting DOCKER_HOST

​Common Socket Locations

​Troubleshooting

​Enterprise Mode Containers

PostgreSQL

ClickHouse

OpenTelemetry Collector

Cube.js

​Performance Considerations

​macOS Performance Comparison

OrbStack

Colima

Docker Desktop

Rancher Desktop

​Clean Start

​Additional Resources

Docker Desktop Docs

Rancher Desktop Docs

Colima GitHub

Podman Desktop Docs

Overview

Key Takeaway

What Oxy Actually Needs

Installation Options

Installation & Setup

Install Docker Engine Only (No Desktop App)

Install Docker Desktop (GUI Application)

Install Rancher Desktop (Alternative GUI Application)

Install Colima - Lightweight Container Engine Manager

Install Podman (Daemonless Alternative)

Install OrbStack - Fast macOS Container Engine

Custom Docker Host

Setting DOCKER_HOST

Common Socket Locations

Troubleshooting

Enterprise Mode Containers

Performance Considerations

macOS Performance Comparison

Clean Start

Additional Resources