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).
- Default agent: which CLI a task launches by default.
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.
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.
Related
- 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.