Skip to main content

​
Starting the server

​
oxy serve — web server only

Starts the Oxy web interface. Requires an external PostgreSQL database configured via OXY_DATABASE_URL. 
oxy serve                        # multi-workspace mode (default)
oxy serve --local                # single-workspace mode: serve the current directory
oxy serve --port 8080            # custom port (default: 3000)
oxy serve --host 0.0.0.0         # bind to all interfaces (needed in containers)
oxy serve --enterprise           # enable ClickHouse telemetry + OTel Collector
oxy serve --readonly             # reject file writes via the API (IDE-alongside mode)
Deployment modes:
FlagBehavior
(none)Multi-workspace mode — default. Workspaces are stored in $OXY_STATE_DIR/workspaces/ and managed via the UI. GitHub import available when GITHUB_* env vars are set.
--localSingle-workspace mode — serves the current working directory as the only workspace. Git sync disabled; files already exist on disk.
For more details see the Deployment Modes guide.

​
oxy start — PostgreSQL + web server

Starts a PostgreSQL container with Docker and then launches the web server. Recommended for local development and single-node deployments without a managed database. 
oxy start                        # start PostgreSQL container + web server
oxy start --enterprise           # also start ClickHouse + OTel Collector
oxy start --clean                # remove existing containers/volumes first
For full details see the oxy start reference.

​
Agent interaction

Once you have your agents, config, and data configured, you can ask this agent questions by running oxy run path/to/agent.agent.yml "<prompt>", as shown below: 
oxy run path/to/agent.agent.yml "How many users do we have?"

​
Database Synchronization

The sync command collects semantic information from your databases, making their structure available to your agents. Basic usage: 
oxy sync
Sync a specific database: 
oxy sync database_name
Sync specific datasets within a database: 
oxy sync database_name -d dataset1
By default, files that already exist will be skipped. To overwrite existing files: 
oxy sync --overwrite
# or oxy sync -o (shorthand)
To overwrite existing files for a specific database: 
oxy sync database_name --overwrite
The sync command will show warnings when files are skipped (already exist) or when files are overwritten (when using the -o flag). For more detailed information about database synchronization, see the Database Sync documentation.

​
Run queries

Run a raw query on target database 
oxy run example_monthly_rejected.sql --database=primary_database
Run a query rendered from a Jinja template 
oxy run example_weekly_rejected.sql --database=primary_database -v variable_a=1 variable_b=a variable_c=\*

​
Workflow usage

To execute a workflow, you can run: 
oxy run path/to/workflow_name.workflow.yml

​
Testing

Run tests defined in your agent or workflow files to ensure quality and consistency:

​
Basic Testing

oxy test agent-name.agent.yml
oxy test workflow-name.workflow.yml

​
JSON Output for CI/CD

Get machine-readable JSON output suitable for automated pipelines: 
oxy test agent.yml --format json
Output: 
{ "accuracy": 0.855, "recall": 0.723 }

​
Quality Gates with Thresholds

Enforce minimum accuracy requirements (exits with code 1 if threshold not met): 
# Average mode: average of all tests must meet threshold (default)
oxy test agent.yml --format json --min-accuracy 0.8 --threshold-mode average

# All mode: every individual test must meet threshold
oxy test agent.yml --format json --min-accuracy 0.8 --threshold-mode all

​
Quiet Mode

Suppress progress bars and detailed output: 
oxy test agent.yml --quiet --format json
Available Flags:
  • --format <format> - Output format: pretty (default) or json
  • --min-accuracy <threshold> - Minimum accuracy threshold (0.0-1.0)
  • --threshold-mode <mode> - Threshold mode: average (default) or all
  • --quiet, -q - Suppress detailed output
For comprehensive testing documentation, see Testing.

​
Building the semantic layer

Build your semantic layer with intelligent incremental builds for 10-100x speedup: 
# Incremental build (default)
oxy build

# Force full rebuild
oxy build --force
The build system automatically detects changes and only rebuilds modified views/topics and their dependencies. For comprehensive documentation on build modes, dependency tracking, performance, and troubleshooting, see the oxy build reference.