Skip to content

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 (make and a C compiler, which Go’s race detector needs), sqlite (the sqlite3 CLI) and tesseract (OCR with English language data). kit list shows these by Ubuntu release, since they come from the base image’s package archive.
Terminal window
odette kit # what is available, and what this project has applied
odette kit apply go rust # apply (no names: a picker, pre-checked with what is applied)
odette kit update # move applied kits to their current version
odette kit add <git source> # register a repository of kits, pinned to the commit fetched
odette kit rm <repository> # forget a repository
odette init --kit go # scaffold .odette/, then apply

odette 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:

Terminal window
odette kit add <git source or local path> # register your repository
odette kit apply <kit> --global # your marketplaces and egress hosts, for every project
odette kit apply <kit> # in a project: files, Dockerfile blocks, settings

Keep 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.

Theme