Projects on disk.

A project is a folder. Orchid drops one hidden directory inside and leaves the rest alone.

A project is a folder

When you create a project, Orchid asks you to pick a folder. It can be an empty new folder or an existing one with code already in it; we don't care. Inside that folder, Orchid creates a single hidden subdirectory — .orchid/ — and that's the entire footprint.

Notebooks and dashboards (the .orchid files you create) live wherever in the folder you want them. Most analysts keep them in the root or in a notebooks/ subfolder; that's your call. Orchid's file tree shows whatever's on disk.

monthly-revenue/
├─ analysis.orchid
├─ q3-dashboard.orchid
├─ notebooks/
│  ├─ exploration.orchid
│  └─ scratch.orchid
├─ data/
│  └─ samples.csv
├─ .gitignore
└─ .orchid/
   ├─ project.yaml
   ├─ connections/
   │  └─ warehouse.yaml
   └─ outputs/
      ├─ q1.parquet
      └─ q2.parquet

What's in .orchid/

The hidden directory is small on purpose. Three things live here, and nothing more.

project.yaml

The project's identity. Its display name, its slug, the Python version pinned for this project's virtualenv, and a few timestamps. This file is small and stable — you can edit it by hand if you need to.

name: Monthly Revenue
slug: monthly-revenue
python_version: "3.11"
created_at: 2026-04-12T08:33:00Z
description: |
  Weekly revenue rollups by channel, plus the Q3 board deck dashboard.

connections/

One YAML file per database connection. These hold the profile — host, port, database name, user, the connector type, SSL settings — but never the password. The password lives in your OS keychain under a key derived from the profile name. When the kernel opens a connection it looks up the keychain entry by name and reads the secret then; the YAML on disk has nothing sensitive.

name: warehouse
type: postgres
host: db.internal.example.com
port: 5432
database: analytics
user: analyst
sslmode: require
# password lives in keychain under: orchid/connections/warehouse

This separation is load-bearing for collaboration. When a teammate clones the project, they get the connection profile but not the secret. They run Add credentials, paste their own username and password, and they're connected with their permissions. The notebook still references the connection by name (warehouse) so cells run unchanged.

Why not .env

Storing secrets in .env works until someone commits it by accident. Keychain integration removes that whole class of bug — there's nothing to gitignore because the secret was never on disk in a file.

outputs/

Where cell outputs spill when they're too big to inline in the notebook YAML. Mostly parquet files for DataFrame results, plus occasional images and HTML for chart snapshots. Gitignored by default. See The .orchid format for the spill rules.

Slug vs name vs path

Three things look like a project identifier, and they aren't the same thing.

  • Path — where the project folder lives on this machine. /Users/you/work/monthly-revenue. Machine-local; changes if you move the folder.
  • Name — what shows up in the IDE's project shelf and window title. Free-form Unicode; you can call a project "Monthly Revenue ★" if you want.
  • Slug — the URL-safe identifier. Generated from the name at create time, kebab-case, ASCII. This is what gets used when you publish — monthly-revenue.orchidide.com.

The slug is sticky. Renaming the project changes the display name but not the slug — because the slug might be in a published URL that someone bookmarked. To change a slug, you do it explicitly from project settings, and Orchid warns you that any published links will break.

Local-canonical, cloud-canonical

Until you publish, the project is local-canonical. The folder on your disk is the truth. The cloud doesn't know it exists. You can move it, rename it, delete it, copy it onto another machine — Orchid is just an app pointing at a directory.

When you hit Publish for the first time, the project becomes cloud-canonical. The slug claims a URL. The cloud row becomes the shared identity that collaborators see. Local copies still run independently, but they're now copies of a published thing rather than the only thing.

Two states. Left: project folder on disk, no cloud presence, the IDE talks only to its local kernel and warehouse. Right: same project folder plus a cloud row that holds the slug, a snapshot, and a collaboration index; the IDE syncs presence and comments through the cloud but still runs the kernel locally./docs-images/concepts/local-to-cloud.png
Publishing doesn't move the kernel. It claims a slug, takes a snapshot, and turns on the collaboration channels.

The flip is one-way for the slug — once it's claimed, it's yours until you unpublish. The rest is reversible: you can stop sharing, you can take down a published artifact, you can delete the cloud row entirely. The local folder is unaffected by any of that.

First publisher wins

If two analysts have a project with the same slug locally and one of them publishes first, they own the cloud row. The second one gets asked to pick a new slug. The slug namespace is global per account.

Working in git

Run git init in the project folder, commit, push. The defaults are sensible: notebooks, dashboards, project metadata, and connection profiles get tracked; outputs and machine-local state get ignored.

# .gitignore that Orchid suggests
.orchid/outputs/
.orchid/state/
.orchid/*.lock
*.pyc
__pycache__/

Anything you want versioned that we excluded — outputs of a key analysis, lockfiles for reproducibility — you can un-ignore. The format works either way; that's your call as the project owner.

Where to read next