Skip to main content
Oxygen is delivered as a hosted product at app.oxygen-hq.com — sign up, connect your data, and start asking questions. There is nothing to install to use the product. The oxy CLI is an optional companion for developers who want to work with an Oxygen project from the terminal — scaffolding a project, running automations, validating config, and previewing it locally. You do not need it to use Oxygen. The CLI is the preferred way to test local changes before they ship to production. Because Oxygen is code-first, you run your project on your machine with oxy start --local, iterate until your semantic model, agents, and apps behave the way you want, and only then commit and push — so what reaches your production deployment is already verified.
The CLI is for local development workflows. If you just want to ask questions of your data, use the web app — skip this page.

​
Install

Run the install script. It downloads the right binary for your OS and architecture (macOS and Linux, x86_64 and arm64) and drops it on your PATH:
To pin a specific version, set OXY_VERSION:
The script installs to /usr/local/bin when run as root, otherwise to ~/.local/bin (and adds it to your PATH for bash/zsh). If ~/.local/bin isn’t already on your PATH, open a new shell after installing.
The install script supports macOS and Linux. Windows isn’t supported directly — use WSL.

​
Verify

​
Update

Upgrade to the latest release in place:

​
Basic commands

The CLI is self-documenting — run oxy --help, or oxy <command> --help for any subcommand. The commands you’ll reach for most:

​
Create a project

Scaffold a new Oxygen project in the current directory:

​
Validate your config

Check your config.yml, automation files, and agent definitions for syntax and schema errors before running anything:

​
Run an automation

Point oxy run at an automation or SQL file to execute it from the terminal:

​
Preview locally

oxy start brings up a local PostgreSQL container and the Oxygen web server so you can preview your project in the browser. It needs a Docker-compatible container engine (Docker Engine, Docker Desktop, Rancher Desktop, Colima, Podman, …):
For most local development, add --local — it runs a single workspace rooted at the current directory with guest authentication (no orgs, no login), so you can iterate on your project without any cloud setup:
--local disables authentication entirely. Don’t expose a --local instance on a non-loopback interface without a reverse proxy that restricts access.
Add --enterprise to turn on the fuller feature set (observability, analytics, and the surfaces the SDK talks to). The flags combine — oxy start --local --enterprise is the usual way to run the SDK against a project on disk:
Use oxy serve instead if you’re supplying your own database via OXY_DATABASE_URL, oxy start --clean for a fresh slate, and oxy status to check what’s running.

​
Expose Oxygen to your editor over MCP

Start an MCP server so MCP-compatible tools can query your project. This is the usual way to wire Oxygen into Cursor or Claude Desktop:
See MCP → for editor configuration.

​
Next steps

Quickstart

Sign up and ask your first question in the web app

Connect to your editor with MCP

Use Oxygen as a tool in Cursor and Claude Desktop