Skip to main content

Documentation Index

Fetch the complete documentation index at: https://oxy.tech/docs/llms.txt

Use this file to discover all available pages before exploring further.

The oxy start command is the recommended way to run Oxy with a production-ready PostgreSQL database. It automatically manages a PostgreSQL container using a Docker-compatible container runtime and starts the Oxy web server.

​
Prerequisites

Container Runtime Required: oxy start needs a Docker API-compatible container runtime (e.g., Docker Engine, Podman with Docker socket).You can use:
  • Docker Engine (standalone, no GUI needed)
  • Docker Desktop, Rancher Desktop, Colima, OrbStack, or Podman
  • Any runtime that provides a Docker API
See the Container Runtime Setup Guide for installation instructions.

​
Overview

oxy start simplifies database setup by:
  1. Checking container runtime availability - Verifies Docker API is accessible
  2. Starting PostgreSQL in a container (or using existing one)
  3. Waiting for PostgreSQL to be ready
  4. Configuring the database connection automatically
  5. (Optional) Enabling observability with --enterprise flag

​
Quick Usage

oxy start                    # start DB + web server
oxy start --enterprise       # enable observability (traces, metrics, analytics)
oxy start --clean            # clean existing containers/volumes first
oxy start --clean --enterprise  # clean + start with enterprise features

​
Key Ports

ServiceHost Port
PostgreSQL (oxy-postgres)15432

​
Clean option

The --clean flag removes all existing Oxy-managed Docker resources before starting:
  • Removes oxy-postgres container
  • Removes oxy-postgres-data volume (⚠️ all data lost)
Use cases:
  • Troubleshooting database issues
  • Resetting to a fresh state for development
  • Clearing corrupted data
  • Starting with a clean slate after schema changes
⚠️ Warning: The --clean option permanently deletes all data in the database volumes. Make sure you have backups of any important data before using this option.

​
Environment vars (enterprise)

  • OXY_OBSERVABILITY_BACKEND = auto-detected (postgres when DB available, else duckdb)
  • OXY_SERVICE_NAME = oxy (service name for traces)

​
Minimal commands

  • Check status: oxy status
  • View logs: docker logs -f oxy-postgres
  • Stop containers: docker stop oxy-postgres
  • Clean restart: oxy start --clean (removes all containers and volumes)

​
Command-Line Options

​
--clean
boolean
default:"false"
Remove all existing Oxy-managed containers and volumes before starting.⚠️ Warning: This permanently deletes all database data.
​
--enterprise
boolean
default:"false"
Enable enterprise features including observability (traces, metrics, analytics).

​
Important Notes

Container Runtime Required: A Docker-compatible container engine must be installed and running. See Container Runtime Setup for options.
  • Data persists in named volumes (oxy-postgres-data)
  • Use --clean to remove existing containers and volumes for a fresh start (⚠️ data loss)
  • If a port is already in use, stop the conflicting service or configure external databases

​
Troubleshooting

Ensure your container runtime is installed and running:
# Verify Docker CLI works
docker ps

# If using a custom socket, set DOCKER_HOST
export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock
oxy start
See the Container Runtime Guide for detailed setup instructions.
If PostgreSQL port 15432 is in use:
  1. Check what’s using the port: lsof -i :15432
  2. Stop the conflicting service
  3. Or configure Oxy to use an external database instead
The container may still be initializing:
# Check container logs
docker logs -f oxy-postgres

# Wait for "ready to accept connections" message

​
Next Steps

Container Runtime Setup

Install and configure Docker Engine, Colima, or other runtimes

Production Deployment

Deploy Oxy in production environments

Database Sync

Learn about database migrations and syncing

Monitor Status

Check Oxy service status