Skip to main content
This guide walks you through deploying Oxy on a cloud environment, from provisioning infrastructure to configuring authentication.
For operators. The Deployment section is intended for the person (DevOps, platform engineer, or self-hoster) who installs and runs the Oxy server. If you are an end user looking to query data or build agents, start with the Quickstart or Getting Started with Agents instead.
Looking for local development setup? See the quickstart guide to get started with oxy init and oxy start.
Quick Start with Docker: If you prefer a faster deployment option, you can use our Docker deployment method instead of the traditional setup. Docker provides a more streamlined experience with fewer manual steps.

​
Deployment Paths

There are several approaches to deploying Oxy:
  1. Traditional Linux Setup - Follow the step-by-step guide below to provision a machine, install dependencies, and configure each component manually.
  2. Docker Deployment - Use our Docker image for a containerized deployment that simplifies setup and maintenance. See the Docker deployment guide for details.
  3. Kubernetes Deployment - Deploy Oxy on Kubernetes clusters using our official Helm charts or raw YAML manifests. Choose from:
    • oxy-app Helm Chart - Standard deployment using oxy serve with an external PostgreSQL database. Recommended for most Kubernetes deployments.
    • oxy-start Helm Chart - Self-contained deployment using oxy start with Docker-in-Docker. No external database required — ideal for single-tenant instances.
    • Raw YAML - For advanced users who need full control over Kubernetes resources.
    • GitOps with ArgoCD - Manage Helm deployments declaratively for automated sync and drift detection.
  4. Multi-workspace Mode - Deploy Oxy as a multi-tenant platform using oxy serve (the default). Workspaces are imported from GitHub or created via the UI and managed centrally. Use --local for single-workspace deployments where the server serves one fixed directory.
  5. Hands-on Guides - For practical, ready-to-use deployment recipes, check our hands-on guides section which includes:
    • Google Cloud Platform (GCP) - Deploy Oxy on Google Cloud using our dedicated GCP deployment guide.

​
Deployment Overview

​
Deployment Request Flow Diagram

​
oxy start vs oxy serve

These are the two commands you’ll use to run Oxy. Choosing the right one depends on where you’re running it.
oxy startoxy serve --localoxy serve
Use whenRunning on your local machineDeploying to a remote server (single workspace)Running a multi-workspace cloud deployment
PostgreSQLAuto-started in Docker — no setup neededAuto-managed embedded instanceYou provide OXY_DATABASE_URL
WorkspacesOne project (current directory)One project (current directory)Multiple — imported from GitHub via UI
GitHub AppNot requiredNot requiredRequired for workspace import
Requires DockerYesNoNo

​
oxy start — for local machines

oxy start is the easiest way to run Oxy on your laptop or workstation. It spins up PostgreSQL in Docker automatically so you never have to configure a database: 
cd my-oxy-project
oxy start
Oxy starts and opens in your browser. Stop it with Ctrl+C. Requires a Docker-compatible container engine.

​
oxy serve --local — for remote servers (single workspace)

When deploying to a VM or container on a remote server, use oxy serve --local. It serves one fixed workspace directory and manages an embedded PostgreSQL instance on disk — no Docker required: 
cd /path/to/my-oxy-project
oxy serve --local --port 3000
This is what the hands-on deployment guides use.

​
oxy serve — for multi-workspace cloud mode

oxy serve (without --local) runs Oxy as a multi-tenant platform where users import repositories from GitHub and manage multiple workspaces through the UI. Requires an external PostgreSQL database and a GitHub App: 
export OXY_DATABASE_URL="postgresql://user:pass@host:5432/oxy"
oxy serve
See the Cloud Mode guide for full setup instructions.

​
Data Persistence

For production deployments, ensure your data persistence strategy matches your reliability requirements:
  • Local machine (oxy start): PostgreSQL runs in Docker, data stored in the oxy-postgres-data Docker volume
  • Remote server (oxy serve --local): Embedded PostgreSQL stored in OXY_STATE_DIR (default: ~/.local/share/oxy/)
  • Cloud mode (oxy serve): You manage an external PostgreSQL — use a managed service (RDS, Cloud SQL, Supabase) with automated backups
Data loss can occur if proper database configuration and backups are not in place. Always ensure your PostgreSQL instance is properly configured with: - Regular automated backups - Proper connection pooling - Adequate storage and performance settings - High availability setup for critical deployments

​
Deployment Steps

Follow these steps to deploy Oxy on your cloud environment:

1. Create Machine

Provision and set up your server with the necessary requirements

2. Install Oxy CLI

Install and configure the Oxy CLI on your server

3. Set Up Workspace & Repository

Set up your Oxy workspace and configure your repository

4. Configure Environment

Set up environment variables and secrets management

Docker Deployment

Deploy Oxy using Docker containers for simplified setup and management

Kubernetes (Helm)

Deploy Oxy on Kubernetes using the oxy-app or oxy-start Helm chart

Cloud Mode

Multi-tenant deployment with GitHub-synced projects and workspace management

Kubernetes (Raw YAML)

Deploy Oxy on Kubernetes using raw YAML manifests for full control

GCP Deployment

Step-by-step guide for deploying Oxy on Google Cloud Platform

​
Troubleshooting

Looking for quick, copy-paste deployment recipes? Check out our Hands-on Deployment Guides that provide step-by-step instructions for common deployment scenarios.

​
Quick One-Time Script

If you prefer to set up everything with a single script, you can use the following bash script that automates the entire deployment process. Customize the variables at the beginning to fit your requirements: 
#!/bin/bash
# Oxy Cloud Deployment Script

# ===== CONFIGURATION =====
# Change these variables to match your setup
DOMAIN_NAME="your-domain.com"
WORKSPACE_DIR="/home/ubuntu/oxy-workspace"
GIT_REPO="git@github.com:your-org/your-oxy-repo.git"
USE_GIT=true
EMAIL="admin@your-domain.com"
OPENAI_API_KEY="your-openai-api-key"

# ===== STEP 1: Create Machine =====
echo "===== 1. Setting up server ====="
sudo apt-get update -y
sudo apt-get install -y \
    git \
    curl \
    wget \
    unzip \
    tar \
    gcc \
    g++ \
    make \
    python3-pip \
    ufw \
    software-properties-common

# Configure SSH
mkdir -p ~/.ssh
chmod 700 ~/.ssh
touch ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

# Configure Firewall
sudo ufw allow 22/tcp
sudo ufw allow 3000/tcp
sudo ufw --force enable

# ===== STEP 2: Install Oxy CLI =====
echo "===== 2. Installing Oxy CLI ====="
bash <(curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/oxy-hq/oxy/refs/heads/main/install_oxy.sh)

# Set up Oxy system service
cat <<EOF | sudo tee /etc/systemd/system/oxy.service
[Unit]
Description=Oxy server
After=network.target

[Service]
User=$(whoami)
WorkingDirectory=${WORKSPACE_DIR}
ExecStart=/bin/bash -c "/usr/local/bin/oxy serve --local & /usr/local/bin/oxy mcp-sse"
Restart=always
Environment="OXY_STATE_DIR=${HOME}/oxy_data"

[Install]
WantedBy=multi-user.target
EOF

# ===== STEP 3: Set Up Workspace & Repository =====
echo "===== 3. Setting up workspace ====="
mkdir -p ${WORKSPACE_DIR}
cd ${WORKSPACE_DIR}

if [ "$USE_GIT" = true ]; then
    # Set up SSH for Git
    if [ ! -f ~/.ssh/id_ed25519 ]; then
        ssh-keygen -t ed25519 -C "$EMAIL" -f ~/.ssh/id_ed25519 -N ""
        ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
        echo "Add this SSH key to your Git provider:"
        cat ~/.ssh/id_ed25519.pub
        echo "Press Enter when done..."
        read
    fi
    # Clone repository
    git clone ${GIT_REPO} .
else
    echo "Manual workspace setup. Place your files in ${WORKSPACE_DIR}"
    touch config.yml
    echo "basic: true" > config.yml
fi

# ===== STEP 4: Configure Environment =====
echo "===== 4. Setting up environment ====="
touch .env
chmod 600 .env
echo "OPENAI_API_KEY=${OPENAI_API_KEY}" > .env

# ===== Start Services =====
echo "===== Starting services ====="
sudo systemctl daemon-reload
sudo systemctl enable oxy
sudo systemctl start oxy

echo "===== Deployment Complete ====="
echo "Your Oxy instance should now be available at: http://${DOMAIN_NAME}:3000"
echo "Remember to update configuration variables in .env and restart the service if needed."
This script is provided as a starting point and may need adjustments for your specific environment. Always review scripts before running them on your server.o “Your Oxy instance should now be available at: https://${DOMAIN_NAME}” echo “Remember to update configuration variables in .env and restart the service if needed.”
To use the script:
  1. Save it to a file (e.g., deploy-oxy.sh)
  2. Make it executable: chmod +x deploy-oxy.sh This script is provided as a starting point and may need adjustments for your specific environment. Always review scripts before running them on your server.
  3. Edit the configuration variables at the beginning of the script
  4. Run the script: ./deploy-oxy.sh