Kits
Set a project up in one command instead of writing its Dockerfile, egress hosts and plugin list by hand. This page covers applying kits, what they change in your files, and keeping your own.
A kit is a reusable setup you apply to a project: a language toolchain, plugins, egress hosts, even a set of project rules. Applying one writes into your project’s own files, shows you the whole change first, and never deletes anything you wrote.
odette ships kits for common tools, so you don’t have to look up download URLs, checksums or package names:
- Languages:
bun,deno,go,python,rust,uv. - Go project tools:
golangci-lint,templ,goose,lefthook. playwright: Playwright’s Chromium and the system libraries it needs.- Ubuntu packages:
build-essential(makeand a C compiler, which Go’s race detector needs),sqlite(thesqlite3CLI) andtesseract(OCR with English language data).kit listshows these by Ubuntu release, since they come from the base image’s package archive.
odette kit # what is available, and what this project has appliedodette kit apply go rust # apply (no names: a picker, pre-checked with what is applied)odette kit update # move applied kits to their current versionodette kit add <git source> # register a repository of kits, pinned to the commit fetchedodette kit rm <repository> # forget a repositoryodette init --kit go # scaffold .odette/, then applyodette kit and each launch tell you when a repository you registered has a
newer version than the commit it is pinned to, and how to take it
(odette kit update). A launch only mentions it for repositories your applied
kits come from, and once per new version. odette asks at most every few hours;
when the repository cannot be reached it waits longer and longer before
asking again, so being offline never slows a launch for long.
Before anything is written, odette prints the complete change: each file it
would touch (new or modified) and any egress host it would add. It prints no
diff; use git diff afterwards. Answer y to apply it.
Without a terminal nothing is written unless you pass --yes.
After writing, odette checks each GitHub marketplace the kit brings: it asks
whether it may read a private one with your GitHub login, and lists the
plugins the marketplace offers and which of them the kit enables. On a
terminal:
- A marketplace your project did not have before always asks which of its plugins to enable, with the kit’s own already ticked.
- A marketplace you already had offers the plugins that appeared in it since odette last showed it (none ticked, so nothing turns on by itself), and points out an enabled plugin it no longer offers.
- A plugin the kit used to enable and no longer does is offered for removal. Say no and it stays, as yours. A plugin you enabled before the kit did is never offered for removal.
Without a terminal, or with --yes, nothing is asked: the kit’s own plugins
are enabled and the rest is only printed. Kits can be
named <kit>@<repository>; a bare name works when only one repository has it.
A kit can include other kits, which are applied first.
What a kit can set, and how it touches each file:
| A kit sets | In | How |
|---|---|---|
| a toolchain or Dockerfile text | .odette/Dockerfile |
a block between marker lines |
| startup code | .odette/startup.sh |
a block between marker lines |
| egress hosts | .odette/domains.allow, .odette/domains.deny |
hosts are added |
| overlay folders | .odette/volumes.json |
entries are added |
| marketplaces and the plugins to enable | .odette/marketplaces.json |
entries are added; plugins are added to an existing entry |
| Claude Code settings | .claude/settings.json |
keys are added; a value you already set stays |
files (for example AGENTS.md, .claude/rules/) |
your project | created if missing; if one exists and differs, odette lists it as differing and asks before replacing it |
A kit never sets mounts: those are paths on your machine, and a kit shared by a team can’t know them.
A block is the text between # >>> odette:kit <kit>@<repository> v<version> …
and # <<< odette:kit <kit>@<repository>. odette only changes text between
those markers; the rest of the file is left alone. To drop a kit’s block,
delete those lines.
.odette/kits.lock records what you applied: each kit, the repository it came
from, the commit, and the version of each block. Commit it. kit update reads
it and touches only the kits it lists. An external repository stays on the
commit it was added at until kit update moves it.
To use a kit as a starting point rather than something that keeps following its
repository, apply it with --once: the files are written as usual, but nothing
is recorded in kits.lock, so kit update never touches them. A kit that is
already in the lock is refused; take it out first with odette kit detach <kit>, which lists the kits, asks, and removes only their entries from the
lock. Neither command changes what the kit wrote: files, blocks and their
markers stay as they are, and applying the same kit again rewrites its
blocks and records it in the lock again. Both take --global for the kits
applied to the machine.
odette kit apply --global applies only a kit’s marketplaces and egress hosts,
to your machine instead of the project, and says what it skipped. odette setup offers the kits of your registered repositories that have something
for the whole machine.
To keep your own setup, put kits in a git repository: one folder per kit, each
with a kit.json. A kit’s includes lists other kits to apply first. On a
new machine:
odette kit add <git source or local path> # register your repositoryodette kit apply <kit> --global # your marketplaces and egress hosts, for every projectodette kit apply <kit> # in a project: files, Dockerfile blocks, settingsKeep the machine-wide part (marketplaces) in its own kit and apply it with
--global; applying it inside a project would also copy those marketplaces
into the project’s committed .odette/marketplaces.json. A repository added
from a local path is pinned to a commit: commit your changes, then run
odette kit update.
Choosing a kit repository is a decision you make, like adding a marketplace: read the change odette shows, especially the egress hosts, before you confirm. A kit’s Dockerfile and startup text run inside the container, never on your machine.
Playwright only works with the browser build its own release expects, so the
playwright kit installs the version your project already locks. odette reads
it from package-lock.json, pnpm-lock.yaml, yarn.lock or bun.lock, at
the project root or one folder down (for example e2e/). If no lockfile has
Playwright yet, odette uses its own default version and prints a warning. After
you add or upgrade Playwright in the project, run
odette kit update playwright and rebuild.
Projects set up before kits carry odette:toolchain blocks. They keep
building, and a launch only warns about them. The first odette kit apply or
odette kit update rewrites them to kit blocks and records them in the lock.