wrktr.json

wrktr.json sits at the repo root, committed, so every worktree and teammate shares it. Every field is optional.

{
  "copy": [".env"],
  "install": "npm ci",
  "quietMs": 30000,
  "maxFileBytes": 5242880,
  "ci": {
    "setup": "npm ci",
    "cacheKeyFiles": ["package-lock.json"],
    "checks": [{ "name": "test", "run": "npm test" }]
  },
  "environments": {
    "dev": {
      "on": "land",
      "url": "https://dev.example.com",
      "secrets": ["CLOUDFLARE_API_TOKEN"],
      "steps": [{ "name": "deploy", "run": "npm run deploy:dev" }]
    }
  }
}

Worktrees and the daemon

Read by the CLI on your machine.

Field	What it is
copy	Gitignored files to copy from the main checkout into each new worktree, such as .env.
install	A command run in each new worktree, such as npm ci.
quietMs	How long a worktree must go without file changes before the daemon commits it. Default 30000.
maxFileBytes	Files larger than this are never committed by the daemon. Default 5242880 (5 MB).

ci

What every push runs, read at the commit being checked. See Checks.

Field	What it is
setup	Runs once per checkout before the checks; its result is snapshotted and reused.
cacheKeyFiles	Files whose content decides whether a snapshot of the setup can be reused (e.g. the lockfile).
instance	standard-1, standard-2, standard-3 or standard-4. Default standard-2.
checks	1 to 20 checks, each run in its own container.
checks[].name	Letters, digits, space, ., _ and -, up to 64 characters. Unique.
checks[].run	The command.
checks[].timeoutSeconds	1 to 1800. Default 600.
checks[].required	Default true. A failing required check holds the land; set false for one that shouldn’t.

environments

Where the project deploys, read from the default branch at the commit being deployed. A map from each environment’s name (lowercase letters, digits, - and _) to its settings; up to 10. See Environments.

Field	What it is
on	"land" (the default): deploys every land. "promote": deploys the commit a person promotes.
from	For promote: the environment a commit must have passed first, and what a promotion takes by default.
url	Where it’s served. Shown and linked, and checked after each run (see verify).
verify	Default on when there’s a url. false turns off the manifest and the check; { "check": "/health" } also requires a 2xx there.
changed	For land: only deploy lands that touch one of these paths (globs). Empty or absent: every land.
secrets	The project secrets its steps may use (capitals, digits and _). Until all are set, it isn’t set up.
steps	1 to 20 steps, { "name", "run" }, run in order in one fresh container. A failing step ends the run.
run	Instead of steps: one command, as a single step named deploy.
timeoutSeconds	Each step’s limit, 1 to 1800. Default 900.
instance	standard-1 to standard-4. Default standard-2.

Environments can’t come from themselves or from each other in a loop. When wrktr.json can’t be read, wrktr env ls and the Environments page say why.