Global config

The config.yml file at the root of your repository is the configuration file you’ll use to define your project’s connections and project-wide settings. The two keys most projects need are:

databases: database connections
models: foundation model connections

A sample config.yml file is shown below:

databases:
  - name: primary-database
    type: bigquery
    key_path: /path/to/keyfile
    dataset: dataset-name
  - name: local
    type: duckdb
    dataset: /path/to/local/files

models:
  - name: openai-4.1-mini
    vendor: openai
    model_ref: gpt-4.1-mini
    key_var: OPENAI_API_KEY
  - name: llama3.2
    vendor: ollama
    model_ref: llama3.2:latest
    api_url: http://localhost:11434/v1
    api_key: secret

Top-level keys

Key	Description
`databases`	Database connections. See Databases.
`models`	LLM connections. See OpenAI, Anthropic, Gemini, and Gateways.
`defaults`	Project defaults. `defaults.database` names the database used when a task or query doesn’t specify one.
`integrations`	External integrations such as Looker.
`timezone`	IANA timezone (e.g. `America/Los_Angeles`) used to resolve relative dates such as “yesterday” or “last week” in agent runs. Defaults to UTC. An agent’s own `timezone:` overrides it.
`builder_agent`	Model for the built-in builder agent, e.g. `builder_agent: { model: claude-sonnet-4-6 }`.
`mcp`	Which files the MCP server exposes as tools.
`health_check`	Opt-in scheduled health checks for the workspace. See Health checks.
`protected_branches`, `base_branch`	Git branch behavior in the IDE. See Branches.
`repositories`	External repositories (dbt, LookML, …) to show in the IDE. Each entry has a `name` and either a local `path` or a `git_url` (with optional `branch`).
`pre_aggregations`	Pre-aggregation settings for the semantic model: `schema` (default `AIRLAYER`), `database`, and `refresh_worker` (`enabled`, `heartbeat`, `renewal_threshold`).

A legacy top-level slack: block is ignored — Slack is connected per org from the web app. admins: is also ignored; platform owners are set with the OXY_OWNER environment variable.

Health checks

Health checks are off until a workspace opts in by adding a health_check: block. Once on, Oxygen evaluates the workspace on a schedule and runs a cheap smoke test that checks every database connection with SELECT 1. Heavier probes are opt-in:

health_check:
  interval: 1h            # how often to evaluate (10m–24h, default 1h)
  smoke_test:
    interval: 6h          # how often to run probes (10m–7d, default 6h)
    connections: true     # SELECT 1 against every database (default true)
    semantic:             # one measure query per topic — true for every topic
      - topic: orders
        measures: [orders.total_revenue]
    agents:               # ask an agent a fixed question; any answer passes
      - agent_ref: agents/analytics.agentic.yml
        prompt: How many orders did we get yesterday?
    max_targets: 25       # cap per probe kind (default 25)

health_check: {} turns checks on with the defaults; enabled: false inside the block (or inside smoke_test) turns them off again.

The semantic and agents probes run real warehouse queries (and, for agents, LLM calls) on every smoke run. On bytes-billed warehouses a semantic probe over a large fact table is a recurring cost, and on Snowflake even the connection check resumes a suspended warehouse.

Environment Variables

You can use environment variables for database connection parameters instead of hardcoding values. This is recommended for production deployments and keeping sensitive data out of version control. For example:

databases:
  - name: postgres_prod
    type: postgres
    host_var: POSTGRES_HOST
    user_var: POSTGRES_USER
    password_var: POSTGRES_PASSWORD
    database_var: POSTGRES_DATABASE

See the Environment Variables Reference for complete documentation.

Git Branch Workflow

If your workspace is a git repository, config.yml can also configure how the IDE handles saves on protected branches and where new feature branches fork from (protected_branches, base_branch). See the Branch Configuration reference for details.

Additional Resources

To get more information about connecting to databases or models, you can reference our integrations section.

Get started

Data Infrastructure

World Model

Agentic Intelligence

Custom Apps

Automations

Integrations

Edge fleet

Manage

Workspaces

Authentication

Observability

Enterprise

Reference

REST API

Resources

Troubleshooting

Global config

Top-level keys

Health checks

Environment Variables

Git Branch Workflow

Additional Resources

​Top-level keys

​Health checks

​Environment Variables

​Git Branch Workflow

​Additional Resources

Top-level keys

Health checks

Environment Variables

Git Branch Workflow

Additional Resources