Commit a .termic.yaml file to your repo so scripts, the preview URL, sandbox allowlist and files-to-copy travel with the project, and teammates inherit the same Termic setup without redoing it.

Most of a project’s Termic configuration can live in the app’s settings, on your machine. But settings on your machine don’t help your teammates. .termic.yaml is a file you commit to the repo, so the project’s setup, how to install it, how to run it, what hosts the sandbox needs, travels with the code. A colleague clones the repo, opens it in Termic, and everything’s already configured.

Why commit it

The alternative to a committed config is everyone rediscovering the same setup independently: which setup script to run, which port the dev server wants, which private registry the sandbox has to allow. .termic.yaml makes that a one-time decision, captured in version control, that the whole team inherits. It’s the same instinct as committing a Makefile or a .editorconfig.

What goes in it

.termic.yaml can hold the parts of a project’s configuration that are worth sharing:

Scripts: the setup and run commands.
Preview URL: the template (with $TERMIC_PORT) that Open expands.
Sandbox allowlist: the extra network hosts and filesystem paths this project needs on top of Termic’s built-in defaults.
Files to copy: globs of files seeded into each new worktree (see below).
Hidden files: globs kept out of the file tree for everyone on the team.
Extra named ports: a second and third port per task, under names you choose.

These are extras layered on Termic’s built-in defaults, especially for the sandbox, the baseline allowlist (vendor APIs, GitHub, package registries) is already built in, so you only list what’s specific to your project. That keeps the file short.

The file

Every key is optional, and anything you leave out falls back to Termic’s own default. A real file is usually a handful of lines, not this:

version: 1

scripts:
  setup: npm ci
  run: npm run dev
  archive: docker compose down
  preview_url: http://localhost:$TERMIC_PORT
  files_to_copy:
    - .env
    - .env.local
  run_scripts:
    - label: Storybook
      command: npm run storybook
    - label: E2E
      command: npm run test:e2e

sandbox:
  enabled_by_default: true
  allowed_hosts:
    - registry.mycompany.internal
  allowed_paths:
    - $HOME/.cache/pnpm

exclude:
  - dist
  - "*.generated.ts"

extra_named_ports:
  - API_PORT
  - DB_PORT

Key	What it is
`version`	Schema version. `1` today.
`scripts.setup`	Run once when a task is created.
`scripts.run`	What the Run button runs.
`scripts.archive`	Run when a task is archived, to tear down what setup built.
`scripts.preview_url`	The template Open expands. `$TERMIC_PORT` is the task’s own port.
`scripts.files_to_copy`	Globs seeded into each new worktree from your main checkout.
`scripts.run_scripts`	Extra named commands, `label` plus `command`, listed beside the Run button.
`sandbox.enabled_by_default`	New tasks in this repo start sandboxed.
`sandbox.allowed_hosts`	Extra hosts, on top of the built-in allowlist.
`sandbox.allowed_paths`	Extra writable paths. `$HOME` and `$WORKSPACE` expand at spawn.
`exclude`	Globs hidden from the file tree, unioned with each person’s own list. `.git` is always hidden.
`extra_named_ports`	Env var names. Every task gets its own port for each, frozen at creation.

A list written as an empty key (exclude: with nothing under it) reads as an empty list rather than an error, so you can leave a section in place while you empty it.

Files to copy

Some files a task needs aren’t in git: a .env, local credentials, a config.local.json. When you create a worktree, it’s a clean checkout and those files aren’t there. The files to copy globs tell Termic which untracked files to seed into each new worktree from your main checkout, so a fresh worktree is actually runnable instead of missing its environment.

.termic.yaml vs Personal

Not everything should be committed. Your personal API token for a staging environment isn’t something the team shares. Termic has a .termic.yaml / Personal toggle when you edit scripts and sandbox settings: committed config goes in .termic.yaml, while machine-specific or private values stay in your personal (uncommitted) settings. You edit both inline from the same place; the toggle decides where a given value lands.

Editing it

You can edit .termic.yaml inline from Termic (Settings → Repository, with the .termic.yaml / Personal toggle), or just edit the file directly in your editor, it’s a plain YAML file in your main checkout. Either way it’s version-controlled, so changes go through your normal review process like any other config.

Scripts: setup & run: the scripts and variables you’ll put here.
Network allowlist: the sandbox hosts you’ll commit.
Settings reference: per-machine settings vs committed config.

.termic.yaml