Configuration.

Orchid layers three sources of settings — defaults, user, and project — and any of them can be overridden by environment variables for one-shot runs.

The four layers

  1. Built-in defaults — what ships with the app.
  2. User settings — ~/.config/orchid/settings.yaml, follows you across projects.
  3. Project config — .orchid/project.yaml, version-controlled with the notebook.
  4. Environment variables — temporary overrides per process.

Later layers win. The agents panel reads from this stack too, so a project-level model choice overrides whatever you picked in user settings.

Project config

Every project has an .orchid/project.yaml at its root. Commit it to git — it's designed to be hand-edited and reviewed.

# .orchid/project.yaml
orchid: '1.0'
project:
  name: Revenue review
  slug: revenue-review
  description: Monthly recurring revenue cohort analysis.

python:
  version: '3.11'
  requirements: requirements.txt

agents:
  default_provider: gemini
  multi_agent: false
  allow_write_ops: false      # require approval for INSERT/UPDATE/DELETE

integrations:
  default: warehouse
  defs:
    warehouse:
      type: postgres
      host: db.internal
      database: analytics
      # secrets resolved from the OS keychain, never written here

publish:
  visibility: link_only        # or 'public', 'team'
  include_data: true

Anything under project.* shows in the project shelf. The python block controls which bundled interpreter the kernel uses.

User settings

Stored at ~/.config/orchid/settings.yaml on macOS and Linux. Edit by hand or through Preferences in the app.

# ~/.config/orchid/settings.yaml
orchid: '1.0'

editor:
  font_family: JetBrains Mono
  font_size: 13
  tab_size: 4
  format_on_save: true

ui:
  theme: dark
  density: comfortable
  show_minimap: false

agents:
  default_provider: gemini
  byo_keys:
    anthropic: env:ANTHROPIC_API_KEY    # read from the named env var
    openai:    env:OPENAI_API_KEY

telemetry:
  enabled: false        # opt out of anonymous usage events

updates:
  check_at_launch: true

The env:VAR_NAME syntax tells Orchid to read the secret from the named environment variable instead of storing it on disk. For sensitive values prefer this or the OS keychain.

Environment variables

Override common settings for a single launch — useful for CI, sandboxes, and debugging.

  • ORCHID_HOME — root directory for app state. Defaults to ~/Library/Application Support/Orchid on macOS and ~/.config/orchid on Linux. Point it at a portable folder to take Orchid with you on a USB drive.
  • ORCHID_LOG_LEVEL — trace, debug, info (default), warn, error. debug is the right level when reporting bugs.
  • ORCHID_NO_TELEMETRY — set to 1 to disable all telemetry, including crash reports. Equivalent to telemetry.enabled: false.
  • ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY — BYO model keys read by the agent system when env: resolution is configured.

Examples

$ ORCHID_LOG_LEVEL=debug orchid run report.orchid
$ ORCHID_HOME=$PWD/.orchid-portable ./Orchid-1.0.0.AppImage

Python version pinning

Orchid bundles Python and gives each project its own virtualenv. Pin a version with the python.version key in .orchid/project.yaml.

# .orchid/project.yaml
python:
  version: '3.11'         # default
  requirements: requirements.txt
  extra_index_url: https://pypi.org/simple/
  isolated: true          # default: each project gets its own venv

Set requirements to point at any pip-compatible file — requirements.txt, pyproject.toml, or uv.lock. Orchid resolves and caches dependencies on first run, then re-uses the venv across kernel restarts.

No system Python

Orchid does not call out to your system Python. If you need a package that bundles a C extension, point Orchid at a wheel for the bundled interpreter version. See Troubleshooting if a build fails.

Model providers

The free tier uses Gemini. Bring your own key (BYOK) to use Anthropic Claude or OpenAI GPT — paid usage hits your account directly with no Orchid markup.

agents:
  default_provider: anthropic    # one of gemini, anthropic, openai
  byo_keys:
    anthropic: env:ANTHROPIC_API_KEY
    openai:    env:OPENAI_API_KEY
  models:
    anthropic:
      planner: claude-opus-4-7
      executor: claude-sonnet-4-7
    openai:
      planner: gpt-5
      executor: gpt-5-mini
  max_tokens_per_session: 500_000   # safety cap
  multi_agent: true

Provider choice is per-project — your work notebooks can run on Claude while a side project stays on the free Gemini tier. See Agents for the behavioral differences.

Telemetry opt-out

Orchid collects anonymous event counts (which commands ran, which connectors were used, whether agents were invoked) to prioritize what to build next. No notebook contents, prompts, query results, or file paths are sent. Opt out two ways:

  • In settings: telemetry.enabled: false
  • Permanently: set ORCHID_NO_TELEMETRY=1 in your shell rc

Crash reports are a separate toggle (telemetry.crash_reports) and default to on. They include a stack trace plus your Orchid version and OS — no user content.

Where files live

Defaults — override with ORCHID_HOME:

  • Config / app state — ~/Library/Application Support/Orchid/ (macOS), ~/.config/orchid/ (Linux)
  • Logs — ~/Library/Logs/Orchid/ (macOS), ~/.config/orchid/logs/ (Linux)
  • Project data — anywhere you cloned the project; outputs spill to <project>/.orchid/outputs/
A tree view showing where Orchid keeps its config, cache, and per-project venv directories./docs-images/reference/configuration-files.png
Three locations, predictable layout. Move any of them with ORCHID_* env vars.

Hitting a wall? Walk through Troubleshooting, or check FAQs.