The settings file

Every repository Catalyst works on can carry one settings file, .catalyst/catalyst.toml, on its default branch. You do not have to write it: the /catalyst-onboard skill reads what your repository needs and proposes the file for you. This page is the reference for what it contains. Catalyst reads no other file; an older catalyst.env.json at the repository root is ignored.

The smallest valid file

#:schema https://staging.catalystcloud.dev/schemas/catalyst.schema.json

[project]
linear_team = "ENG"

[project] with linear_team, the key of the Linear team this repository’s work belongs to, is required. Every other section is optional. The #:schema line lets your editor check the file as you type.

Declaring what a build needs

The cloud builds and tests your repository in a fresh container. It needs the names of the variables and secrets the build reads, and any install or test commands of your own. You write names; you enter values in the app.

[[environment.variables]]
name = "DATABASE_URL"
required = true

[[environment.variables]]
name = "STRIPE_API_KEY"
required = true
secret = true

[[environment.setup]]
name = "install"
run = ["npm", "ci"]

• Each [[environment.variables]] entry names one variable and says whether it is required. Add secret = true for a secret. A value never goes in this file.
• [[environment.setup]] steps are your own install commands, run before the agent’s session starts, in place of the automatic dependency install. run is an argument list, not a shell string. verify steps have the same shape and carry your test commands.
• Leave platform bindings and deploy-only secrets out. Containers build and test; they do not deploy.

The /catalyst-onboard skill drafts this section from your .env.example and your CI workflows, and says which file each name came from. It can also approve the account-wide declaration itself; a repository’s own declaration is approved in the app.

How a change reaches Catalyst

1. Commit the file on the default branch and push. Each push is read by Catalyst.
2. An owner or admin approves the new revision: Settings → Repositories → the repository → Environment → Setup declaration → Approve this revision. Secret values go on the Secrets tab of the same page, write-only; plain values on the Environment variables tab. Leave the Require this declaration switch off for now: with it on, work waits for an environment check that is not yet recorded in production.
3. From then on, a phase gets exactly the secrets the approved declaration names.

Until a declaration is approved, the cloud still runs your repository with its automatic install and every ordinary secret you have stored, so an unapproved file never blocks work. It only narrows what a phase can see once approved.

What else the file can say

The same file can name which provider and model run each stage, when Catalyst stops retrying and asks a person, where your thoughts repository lives, and how Catalyst’s stages map onto your team’s Linear states. Those sections are documented as they open up; the schema link above is always current.