​
Deploy Oxy on GCP

This guide walks you through deploying Oxy on Google Cloud Platform using Compute Engine VM instances with direct access. We’ll cover everything from setting up a virtual machine to configuring Oxy with proper data persistence.

This guide sets up Oxy for direct access on port 3000. For production deployments, consider implementing additional security measures such as HTTPS with SSL certificates, authentication, and network access controls.

This is part of our Hands-on Deployment Guides. For additional deployment options, see our Docker Deployment Guide or the general deployment overview.

​
Prerequisites

Before you begin, make sure you have:

  • A Google Cloud Platform account
  • A domain name (optional, but recommended for production deployments)
  • Basic familiarity with Linux command line

​
Getting a VM Instance

Follow these steps to create a VM instance in Google Cloud Platform:

1

Access Google Cloud Console

Go to the Google Cloud Console and sign in with your account.

2

Create or Select a Project

Select an existing project or create a new one using the project selector at the top of the page.

3

Navigate to Compute Engine

From the navigation menu, select Compute Engine > VM instances.

If this is your first time using Compute Engine, you might need to enable the API.

4

Create a VM Instance

Click the CREATE INSTANCE button and configure your instance:

  • Name: Choose a name for your instance (e.g., oxy-server)
  • Region & Zone: Select a region close to your users
  • Machine Configuration:
    • For optimal cost-performance, consider using ARM-based instances (T2A series):
      • t2a-standard-1 (1 vCPU ARM, 4 GB memory)
  • Boot disk:
    • Operating System: Ubuntu
    • Version: Latest stable (e.g., Ubuntu 22.04)
    • Size: recommended starting point 10 GB
  • Firewall:
    • Check “Allow HTTP traffic” to allow access on port 3000
    • You may also check “Allow HTTPS traffic” if you plan to set up HTTPS later

Click Create to provision your VM.

5

Note Your External IP

Once your VM is ready, note the External IP address displayed in the VM instances list. You’ll need this to connect to your instance and to configure your domain DNS settings if using a custom domain.

​
Pointing Your Domain to the VM (Optional)

If you have a domain name you want to use for your Oxy deployment:

1

Access DNS Settings

Go to your domain registrar’s website (such as GoDaddy, Namecheap, or Google Domains) and navigate to the DNS settings for your domain.

2

Add DNS Records

Add the following DNS records:

  • A Record:
    • Host/Name: @ (represents the root domain)
    • Value/Points to: Your VM’s External IP address
    • TTL: 3600 (or as recommended by your registrar)
  • A Record for www subdomain:
    • Host/Name: www
    • Value/Points to: Your VM’s External IP address
    • TTL: 3600 (or as recommended by your registrar)
3

Wait for DNS Propagation

DNS changes can take from a few minutes to several hours to propagate. You can check the status using online tools like whatsmydns.net.

​
Setting Up the VM

Connect to your VM instance and prepare it for Oxy deployment:

1

Connect to Your VM

You can connect directly from the Google Cloud Console by clicking the “SSH” button next to your instance, or use a terminal:

# If using gcloud CLI
gcloud compute ssh --project=YOUR_PROJECT_ID --zone=YOUR_ZONE oxy-server

# Or using standard SSH if you've set up SSH keys
ssh username@EXTERNAL_IP
2

Update System and Install Essential Packages

# Update package lists and install essential tools in one command
sudo apt update && sudo apt install -y curl wget git unzip jq nano

​
Installing Oxy CLI

Let’s install Oxy directly on the VM:

1

Install Required Dependencies

# Install all necessary dependencies at once
sudo apt update && sudo apt install -y build-essential libssl-dev pkg-config
2

Install Oxy

Run the official Oxy installation script:

bash <(curl --proto '=https' --tlsv1.2 -sSf https://get.oxy.tech)

This script will download and install the latest stable version of Oxy.

3

Verify the Installation

Confirm that Oxy is installed correctly:

oxy --version

You should see the version information displayed.

​
Setting Up Oxy Workspace

Let’s use the built-in oxy init command to initialize a new workspace with all the necessary files and configuration:

1

Create and Navigate to Workspace Directory

mkdir -p ~/oxy-workspace
cd ~/oxy-workspace
2

Initialize Oxy Project

oxy init

This interactive command will:

  1. Create a config.yml file with your database and model configurations
  2. Set up sample project files
  3. Create necessary directories like agents and workflows

Follow the prompts to configure:

  • Database settings (You can start with DuckDB for simplicity)
  • Model configuration (e.g., OpenAI with your API key)

The initialization process will ask for your OpenAI API key and create all the necessary configuration.

3

Alternative: Set Up Git and Clone Existing Project

If you already have an existing Oxy project in a Git repository, you should set up Git and clone your repository instead of using oxy init.

First, make sure Git is properly configured:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Then clone your existing repository:

git clone https://github.com/yourusername/your-oxy-project.git ~/oxy-workspace
cd ~/oxy-workspace

This will give you your existing project configuration and agents, which is preferable to starting from scratch if you already have a working setup.

4

Create Data Directory

mkdir -p ~/oxy-data

This directory will store all persistent data for Oxy, including the SQLite database files.

5

Configure Environment Variables

Create a standard .env file in the workspace directory:

cd ~/oxy-workspace
nano .env

Add your environment variables:

OXY_STATE_DIR=/home/$(whoami)/oxy-data

Save and exit.

If you don’t set OXY_STATE_DIR, Oxy will use the default location ~/.local/share/oxy/. We recommend setting it explicitly for production deployments to make backups and maintenance easier.

Note: You won’t need to manually set the OpenAI API key in the environment as it’s already configured during the oxy init process.

​
Firewall Configuration

To ensure your Oxy deployment is accessible, you need to create a firewall rule that allows traffic on port 3000:

1

Create Firewall Rule

In the Google Cloud Console, navigate to VPC network > Firewall.

2

Create Rule for Port 3000

Click CREATE FIREWALL RULE and configure:

  • Name: allow-oxy-port-3000
  • Direction: Ingress
  • Action: Allow
  • Targets: Specified target tags
  • Target tags: oxy-server (or the tag you want to use)
  • Source IP ranges: 0.0.0.0/0 (for public access) or your specific IP range for restricted access
  • Protocols and ports:
    • Check “Specified protocols and ports”
    • Select “TCP”
    • Enter port 3000

Click CREATE to save the rule.

3

Apply Tag to Your VM

Go back to Compute Engine > VM instances, select your VM instance, and click EDIT.

In the Network tags field, add oxy-server (or whatever tag you used in the firewall rule).

Click SAVE.

Opening port 3000 to 0.0.0.0/0 allows public access to your Oxy instance. For production deployments, consider restricting access to specific IP ranges or implementing additional authentication measures.

​
Setting Up and Starting Oxy as a Service

Let’s configure Oxy to run automatically on system startup and restart if it fails:

1

Create a Systemd Service File

sudo nano /etc/systemd/system/oxy.service

Add the following content:

[Unit]
Description=Oxy Server
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/oxy-workspace
EnvironmentFile=/home/ubuntu/oxy-workspace/.env
ExecStart=/usr/local/bin/oxy serve --port 3000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

We specify port 3000 explicitly to match the firewall rule configuration. The service will be accessible directly on this port from the internet.

This configuration uses the default ubuntu user which is standard on GCP instances. If you’re using a different username, adjust accordingly.

Save and exit.

2

Enable and Start the Service

sudo systemctl daemon-reload
sudo systemctl enable oxy
sudo systemctl start oxy
3

Verify the Service

sudo systemctl status oxy

You should see that the service is active and running.

4

View Logs (if needed)

If you encounter any issues, check the logs:

sudo journalctl -u oxy -f

This command will show you the live logs from the Oxy service.

5

Test the Connection

You can test if Oxy is responding properly:

curl http://localhost:3000

You should get a positive response indicating that Oxy is running.

6

Access Your Deployment

You can now access your Oxy deployment using:

If you’ve configured a domain name:

http://yourdomain.com:3000

Or directly using your VM’s external IP:

http://YOUR_VM_EXTERNAL_IP:3000

For production deployments with HTTPS, consider setting up a reverse proxy like nginx with Let’s Encrypt certificates, or implementing additional GCP services for SSL termination and enhanced security.

You should see the Oxy interface. Congratulations! 🎉 You’ve successfully deployed Oxy on Google Cloud Platform.

​
Optional Configuration and Management

Everything up to this point completes the core setup of your Oxy deployment. The following sections cover additional aspects of managing your deployment that you may want to explore as needed.

​
Data Persistence

It’s important to understand how Oxy handles data persistence:

  • Oxy uses SQLite for its internal database by default
  • All data is stored in the directory specified by OXY_STATE_DIR environment variable (we set it to ~/oxy-data)
  • If OXY_STATE_DIR is not set, Oxy uses ~/.local/share/oxy/ by default
  • This directory contains database files, semantic information, cached query results, and workflow history

For production deployments, consider backing up the oxy-data directory regularly. You can set up automated backups to Google Cloud Storage using gsutil or use a persistent disk for enhanced reliability.

​
Managing Your Deployment

1

Stopping the Service

If you need to stop the Oxy service temporarily:

sudo systemctl stop oxy
2

Updating Oxy

To update Oxy to the latest version:

# Stop the service first
sudo systemctl stop oxy

# Run the installation script again
bash <(curl --proto '=https' --tlsv1.2 -sSf https://get.oxy.tech)

# Start the service again
sudo systemctl start oxy
3

Backup Data

# Create a backup of your Oxy data
tar -czf oxy-backup-$(date +%Y%m%d).tar.gz ~/oxy-data/

# Optional: Upload to Google Cloud Storage
gsutil cp oxy-backup-*.tar.gz gs://your-bucket-name/

You’ll need the gcloud CLI installed and authenticated for the last command.

​
Machine Recommendations

Oxy runs well with just 4GB of memory for most use cases.

Choose from these recommended instance types:

Usage LevelARM-based (Best Value)x86-based
Small (1-3 users)t2a-standard-1 (2 vCPU, 4 GB)e2-medium (1 vCPU, 4 GB)
Medium (3-5 users)t2a-standard-2 (2 vCPU, 8 GB)e2-standard-2 (2 vCPU, 8 GB)
Large (5-15 users)t2a-standard-4 (4 vCPU, 16 GB)e2-standard-4 (4 vCPU, 16 GB)

ARM-based instances (T2A series) typically offer 15-20% cost savings over equivalent x86 instances.

​
Scaling on GCP

As your usage grows, you may need to scale your deployment:

​
Vertical Scaling

  1. Stop your VM from the GCP Console
  2. Edit the VM configuration to increase CPU and memory
  3. Start the VM again
  4. Reconnect and start your Oxy service: 
    sudo systemctl start oxy

​
Storage Scaling

If you need more storage for your Oxy data:

  1. Create a new persistent disk in the GCP Console

  2. Connect to your VM and mount the disk:

    # Mount the disk to a new location
sudo mkdir -p /mnt/oxy-data
sudo mount -o discard,defaults /dev/disk/by-id/google-[DISK_NAME] /mnt/oxy-data
sudo chown -R ubuntu:ubuntu /mnt/oxy-data

# Copy your existing data to the new location
cp -r ~/oxy-data/* /mnt/oxy-data/

# Update the data path in your .env file
echo "OXY_STATE_DIR=/mnt/oxy-data" > ~/oxy-workspace/.env

# Restart Oxy to use the new location
sudo systemctl restart oxy

  3. To make the mount persistent across reboots, add it to fstab:

    echo "/dev/disk/by-id/google-[DISK_NAME] /mnt/oxy-data ext4 discard,defaults 0 2" | sudo tee -a /etc/fstab

​
Troubleshooting

For further help, join our community on Discord.

​
Next Steps

Once your GCP deployment is running:

  1. Configure agents and workflows in your workspace
  2. Set up regular backups for your data
  3. Consider implementing a CI/CD pipeline for deploying configuration updates
  4. Monitor your VM’s resource usage and scale as needed

For more information on using Oxy, refer to the main documentation.