To get a quick sense of how oxy works, your best bet is to set up our demo instance using oxy init, as laid out here. If you want to use your own data and get started building your own agents and workflows, you can follow the guide below. If you don’t have some data available, you can also run oxy init, use the defaults, then follow along in the guide with the demo data provided therein. In the following guide, we’ll build up a simple agent and workflow that operates against some local csv data.
1

Set up your project folder

To get started, create a new project folder where you’ll hold your oxy files.We personally like keeping our oxy projects within a folder in your home directory ~/projects. If you wish, you can follow this pattern by running the following command from the command-line, which will create this directory and move you to it.
mkdir -p ~/projects/new-oxy-project && cd ~/projects/new-oxy-project/
Oxy is directory-based, meaning we’ll look for files in the current working directory when running commands. We’ll look recursively upward until we find a config.yml file, which should sit at the root of your oxy folder.
2

Connect your data with a config.yml file

Now that you have a basic repository set up, the first step is to connect your data. We support a variety of connectors, but we recommend using duckdb with some local flat files (e.g. csv or parquet files) to get started. Oxy comes bundled with duckdb by default, meaning you can simply drop some csv files into your oxy repository and you’re good to go.To get started, you’ll have to create a config.yml file in the root of your oxy repository. You can do this by running the following command from within the oxy project folder:
touch config.yml
Using your favorite text editor, open this file and add the following:
databases:
  - name: local
    type: duckdb
    dataset: ./
This sets up a duckdb query engine called local. This duckdb instance executes from your local oxy directory (the path is specified by the dataset key and is defined relative to the oxy directory).This can have any name you’d like, but remember the name — you’ll be using the name to specify which database to use within your agent and workflow files.
To connect a different warehouse, you can check out our Integrations section.
3

Connect your model in config.yml

Adding a model to your oxy repository is also a matter of modifying the config.yml file. Open this file up again, and add the following section:
models:
  - name: openai-4.1
    vendor: openai
    model_ref: gpt-4.1
    key_var: OPENAI_API_KEY
For this, you’ll need to obtain an OpenAI API key, which you can do here. You’ll need to save your API key as an environment variable with name specified in key_var — in this case: OPENAI_API_KEY.In order to save your API key as an environment variable, you can add the following line to your ~/.bashrc or ~/.zshrc file:
export OPENAI_API_KEY="your-api-key"
Remember to restart your terminal instance once this is done, or the rc file won’t be sourced (and so your environment variables won’t be updated).
To connect a different model, you can check out our Integrations section.
Now that you’re done setting up your project scaffolding, you can set up your first agent.