Skip to main content

​
Deploy Oxy on AWS

This guide walks you through deploying Oxy on Amazon EC2 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:
  • An AWS account
  • A domain name (optional, but recommended for production deployments)
  • Basic familiarity with Linux command line

​
Creating an EC2 Instance

Follow these steps to create an EC2 instance in Amazon Web Services:
1

Access AWS Management Console

Go to the AWS Management Console and sign in with your account.
2

Navigate to EC2 Dashboard

From the services menu, select EC2 under Compute services.
3

Launch an Instance

Click the Launch instance button and configure your instance:
  • Name: Choose a name for your instance (e.g., oxy-server)
  • Application and OS Images:
    • Select Ubuntu Server 22.04 LTS (64-bit ARM or x86)
    • For best value, choose the ARM-based Amazon Machine Image (AMI)
  • Instance type:
    • For ARM-based, select t4g.small (2 vCPU, 2 GB memory) or t4g.medium (2 vCPU, 4 GB memory)
    • For x86-based, select t3.small (2 vCPU, 2 GB memory) or t3.medium (2 vCPU, 4 GB memory)
  • Key pair: Create a new key pair or select an existing one
    • If creating a new one, make sure to download and save the private key file
  • Network settings:
    • Allow SSH traffic from your IP
    • Allow HTTP traffic on port 3000 (custom TCP rule: TCP, Port 3000, Source: 0.0.0.0/0)
  • Storage:
    • Default 8 GB gp3 root volume is sufficient to start
Click Launch instance to create your EC2 instance.
4

Note Your Public IP

Once your instance is running (it may take a minute), select it from the Instances list and note the Public IPv4 address. 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 Your EC2 Instance (Optional)

If you have a domain name and want to use it with your Oxy deployment:
1

Access DNS Settings

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

Add DNS Records

Add the following DNS record to point your domain to your EC2 instance:
  • A Record:
    • Host/Name: @ or your subdomain (e.g., oxy)
    • Value/Points to: Your EC2 instance’s public IP address
    • TTL: 3600 (or as recommended by your registrar)
You can find your EC2 instance’s public IP address in the AWS Console under EC2 → Instances.
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 EC2 Instance

Connect to your EC2 instance and prepare it for Oxy deployment:
1

Connect to Your Instance

You can connect using the AWS EC2 Instance Connect from the AWS Console by selecting your instance and clicking “Connect”, or use SSH with your key file:
# Using SSH (replace with your key file path and public IP)
ssh -i /path/to/your-key-file.pem ubuntu@YOUR_PUBLIC_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 EC2 instance:
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.

​
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 security group configuration. The service will be accessible directly on this port from the internet.
This configuration uses the default ubuntu user which is standard on EC2 Ubuntu 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 EC2 instance’s public IP:
http://YOUR_PUBLIC_IP:3000
For production deployments with HTTPS, consider setting up a reverse proxy like nginx with Let’s Encrypt certificates, or implementing additional AWS services for SSL termination and enhanced security.
You should see the Oxy interface. Congratulations! 🎉 You’ve successfully deployed Oxy on AWS EC2.

​
Security Group Configuration

To ensure your Oxy deployment is accessible, verify your EC2 instance’s security group allows inbound traffic on port 3000:
1

Access Security Groups

In the AWS Management Console, go to EC2 > Security Groups.
2

Find Your Instance's Security Group

Locate the security group associated with your EC2 instance (you can find this in the instance details).
3

Add Inbound Rule for Port 3000

Edit the security group and add the following inbound rule:
  • Type: Custom TCP
  • Port range: 3000
  • Source: 0.0.0.0/0 (for public access) or your specific IP range for restricted access
  • Description: Oxy HTTP access
4

Save Changes

Click Save rules to apply the changes.
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.

​
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 Amazon S3 or use an additional EBS volume 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 Amazon S3
aws s3 cp oxy-backup-*.tar.gz s3://your-bucket-name/
You’ll need the AWS CLI installed and configured 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)t4g.small (2 vCPU, 2 GB memory) or t4g.medium (2 vCPU, 4 GB memory)t3.small (2 vCPU, 2 GB memory) or t3.medium (2 vCPU, 4 GB memory)
Medium (3-5 users)t4g.large (2 vCPU, 8 GB memory)t3.large (2 vCPU, 8 GB memory)
Large (5-15 users)t4g.xlarge (4 vCPU, 16 GB memory)t3.xlarge (4 vCPU, 16 GB memory)
ARM-based instances (T4g series) typically offer 20% cost savings over equivalent x86-based instances with comparable or better performance.

​
Scaling on AWS

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

​
Vertical Scaling

  1. Stop your EC2 instance from the AWS Management Console
  2. Change the instance type to a larger size (e.g., from t4g.small to t4g.medium)
  3. Start the instance 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 EBS volume in the AWS Management Console:
    • Go to EC2 → Volumes → Create Volume
    • Choose a size and volume type (gp3 is recommended for balanced cost/performance)
    • Create in the same Availability Zone as your EC2 instance
  2. Attach the volume to your EC2 instance:
    • Select the volume you created
    • Actions → Attach Volume
    • Select your instance and choose a device name (e.g., /dev/sdf)
  3. Connect to your VM and mount the disk: 
    # Check the volume name
lsblk

# Create a filesystem on the new volume (usually nvme1n1 on newer instances or xvdf on older ones)
sudo mkfs -t ext4 /dev/nvme1n1

# Mount the disk to a new location
sudo mkdir -p /mnt/oxy-data
sudo mount /dev/nvme1n1 /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
  4. To make the mount persistent across reboots, add it to fstab: 
    # Get the UUID of the volume
sudo blkid

# Add to fstab using the UUID
echo "UUID=$(sudo blkid -s UUID -o value /dev/nvme1n1) /mnt/oxy-data ext4 defaults,nofail 0 2" | sudo tee -a /etc/fstab

​
Troubleshooting

  • Check your EC2 instance security group: Ensure it allows inbound traffic on port 3000 from 0.0.0.0/0 (or your specific IP range)
  • Verify Oxy is running: sudo systemctl status oxy
  • Test local connection: curl http://localhost:3000
  • For domain issues: Run dig yourdomain.com to verify DNS is pointing to your EC2 instance’s public IP
  • Check if your EC2 instance’s public IP has changed (this can happen after stop/start)
  • View detailed logs: sudo journalctl -u oxy -f
  • Verify environment file exists: cat ~/oxy-workspace/.env
  • Check service file: sudo cat /etc/systemd/system/oxy.service
  • Ensure workspace exists: ls -la ~/oxy-workspace
  • Verify Oxy binary is installed: which oxy
  • Verify data directory exists: ls -la ~/oxy-data
  • Check environment variable is set: grep OXY_STATE_DIR ~/oxy-workspace/.env
  • If you didn’t set OXY_STATE_DIR, check the default location: ls -la ~/.local/share/oxy/
  • Ensure proper permissions: sudo chown -R ubuntu:ubuntu ~/oxy-data
  • Check if you’ve hit CPU credit limits (t-series instances are burstable)
  • Consider upgrading to a larger instance type if consistently hitting limits
  • View system metrics in the AWS EC2 console to diagnose resource constraints
  • Check available disk space: df -h
  • Verify the EC2 instance is running in the AWS Console
  • Check if the security group allows traffic on port 3000
  • Ensure Oxy service is running: sudo systemctl status oxy
  • Test if the port is open: sudo netstat -tlnp | grep :3000
For further help, join our community on Discord.

​
Next Steps

Once your AWS EC2 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 EC2 instance’s resource usage and scale as needed
For more information on using Oxy, refer to the main documentation.
⌘I