This guide is for the person who owns a project's .booth/: you choose what goes into the
booth — tools, ports, credentials, hooks — and keep it working as the project changes.
Everyone else on the project only needs Developing in a Booth.
It follows the job in order. Each section says what the task is, gives the quick way to do it, and links to the detailed document.
AI agents helping a user set up a booth should read
AGENT_SETUP.md.
- The one rule: generated vs yours
- Start
- Choose the tools
- Wire up the runtime
- Beyond the catalog
- Risky options
- Profiles
- Change it later
- Prove it works
- Commit and hand off
- Share an image, and migrate
booth config writes the booth's configuration from a selection of templates and flags. Some
files under .booth/ are its output; the rest are yours. Keep the two apart:
| Files | Who writes them | How to change them |
|---|---|---|
Boothfile, config.toml, .generated |
booth config |
Re-run booth config with different flags |
setups/, startups/ (without a # Generated by: header), home/, home-seed/, shared/, console.json, templates/ |
You | Edit them by hand — a reconfigure copies them, never regenerates them. The exception: a script your own template writes into setups/ is rewritten from the template each time, so edit it there |
./booth, .booth/tools/codingbooth.lock |
booth install |
booth install <version> |
.generated holds a fingerprint of what booth config last wrote. That is how it can tell its
own output from your edits later. An edit it can turn back into flags (a new --env, a changed
port, a bumped version pin) is read back and kept. Anything else, such as a hand-added run line,
makes the file protected: booth config will not overwrite it without --overwrite (which
keeps your copy as .bak) or --beside (which writes its version as .new for you to merge).
So: reach for a flag, not an editor.
More: booth config → What gets generated · Hand-written files
curl -fsSL https://codingbooth.io/install.sh | bash # first time on this machine
cd my-project
booth install # puts ./booth and the lock file hereDocker must work without sudo (rootful Docker Engine on Linux, Docker Desktop on macOS and Windows).
More: booth install
| Start from | Command | When |
|---|---|---|
| Nothing, choosing as you go | booth config (terminal UI), booth config --web (browser) |
Most projects |
| Nothing, in one command | booth config --no-tui --select 'go+linter/python:3.13+uv' |
You know what you want, or are scripting |
| A shipped example | booth example list, then booth example try <name> <folder> |
A known stack (Spring Boot, Django, React, …) to copy from |
| A published showcase | booth showcase list, then booth showcase import <handle>/<slug> <folder> |
Someone has shared a booth for this kind of project |
Run booth config from inside the project folder. The command it records in the files' header
then has no absolute path in it.
More: booth config → Modes · Config TUI · Config web UI · booth example · booth showcase
The variant decides what opening the booth gives you:
| Variant | Opens to |
|---|---|
base (default) |
A browser terminal (the Console UI) |
codeserver |
VS Code in the browser |
notebook |
JupyterLab |
xfce, kde, lxqt, wayland |
A full Linux desktop in the browser |
booth config --no-tui --select go --variant codeserverEveryone can still run ./booth -- bash or ./booth -- <command> without the UI, whatever the
variant.
More: Variants
booth template list # everything selectable (--full adds secondary ones)
booth template search postgres # by name, description or tag
booth template show python # params, extensions, what it requires
booth template show python+uv --detail # also what it writesThe categories are languages, tools, IDEs, frameworks, AI tools, desktops, middlewares, education and VM sizing.
| Syntax | Means | Example |
|---|---|---|
/ |
next template | go/python/claude-code |
+ |
add an extension to the template before it | python+uv+kernel, java+maven+lombok |
: |
set a parameter (usually the version) | python:3.13, java:21,temurin |
booth config --no-tui --dryrun --select 'java:21+maven/claude-code+credential+auto-accept'--dryrun prints what would be written and touches nothing. Use it before every real run.
More: booth config → Selection DSL · Recipes (saved selections)
A :version becomes an arg NAME=VALUE line in the Boothfile, and it survives later
reconfigures. Pinning tool versions is the first of three tiers:
- Pin versions — the same tool versions on every rebuild (convenient, not exact).
- Freeze the resolution — lock files, plus an apt snapshot date (
--apt-snapshot) so system packages resolve the same way. - Store the image — build once, push it, and run that image (section 10). This is the only real guarantee.
More: Reproducibility
All of these are flags on the same booth config command, so they all end up in the generated
files.
booth config --no-tui --select go --expose 8080 # host 8080 → container 8080
booth config --no-tui --select go --expose '+80:8080' # host = booth port + 80
booth config --no-tui --select 'cloudbeaver+expose' # a service template publishes its own portThe +offset form follows the booth port, so two booths of the project never fight over a port.
Servers inside must listen on 0.0.0.0.
More: booth config → Ports · booth expose
booth config --no-tui --select go --env TZ=UTC --env LOG_LEVEL=debugValues that are secret, or differ per person, go in .booth/.env instead. It is gitignored, and
each developer keeps their own.
More: Variable expansion
booth config --no-tui --select go --mount '~/datasets:/home/coder/datasets'A mount whose host path does not exist is skipped with a notice, so it is safe to list paths that
only some machines have. To have booth create a missing host folder instead, add :create
(--mount '~/.cache/mytool:/home/coder/.cache/mytool:create').
Prefer the credential templates to hand-written mounts. Each one copies a host login into the booth's home at start, read-only:
| Select | Brings in |
|---|---|
git-credential |
~/.gitconfig |
openssh+agent |
your host ssh-agent: git over SSH signs with its keys, no key file enters the booth (native engine on Linux) |
openssh+keys |
only the keys in one folder you choose (default ~/.ssh/booth) — e.g. a deploy key |
openssh+credential |
all of ~/.ssh, every private key included — the you-are-on-your-own mode, for code you trust |
gh+token |
GitHub CLI login, from the host GH_TOKEN (GH_TOKEN=$(gh auth token) booth …); git uses it too, an SSH remote included when the booth has no ssh |
envfolio+seed |
chosen items of your host's EnvFolio store, still encrypted, and the store key (passphrase-protected), so folio in the booth opens the secrets itself (envfolio+seed:"gh @app1 --secrets" — the arguments you give folio exec) |
envfolio+store-host |
your host's whole EnvFolio store and gpg keyring, live and writable — every private key included |
gnupg+keys |
chosen GPG keys (passphrase-protected) and your public keyring: gnupg+keys:"me@example.com" |
claude-code+credential, codex+credential, gemini-cli+credential, … |
that AI tool's login |
Bring in only what the project needs. Every credential in the booth is reachable by whatever code runs there.
More: booth home → Credential seeding · Security → Convenience mounts
| Folder | For | Committed? |
|---|---|---|
.booth/cache/ |
Per-machine state that should survive restarts: package caches, tool settings, logins | Never — the booth refuses to start if it is tracked |
.booth/shared/ |
Team state that belongs in git (shared run configs, fixtures) | Yes |
Many templates come with a cache extension already: java+maven+m2 reuses the host's ~/.m2,
rust+cargo-cache reuses Cargo's, claude-code+settings-cache keeps Claude Code's settings.
More: Local cache · Shared state
| Folder | Copied into ~ at start |
Use for |
|---|---|---|
.booth/home/ |
Overwrites what is there | Settings the team must share (.editorconfig, a team .gitconfig section) |
.booth/home-seed/ |
Only if missing | Defaults people may change |
More: booth home
A script in .booth/startups/ named *--startup.sh runs as coder every time the booth starts
(order 50 unless the name starts with NN-). Use it to start a background service or prepare
data. Keep it idempotent: it runs on every boot.
# .booth/startups/dev-server--startup.sh
nohup just dev-server > /tmp/dev-server.log 2>&1 &Don't copy the # Generated by: header from a generated hook into yours. A reconfigure removes
the hooks that carry it.
More: booth config → Startup scripts
Every booth has just. A Justfile at the project root (just run, just test, just build) is
the first thing a developer, or an AI agent, should find when they open the booth.
.booth/console.jsonsets the Console UI's starting panes and Web view tabs.- Any other
config.tomlkey has--set, e.g. shut down idle booths after 30 minutes:
booth config --no-tui --select go --set idle-time=1800More: Console layout · booth idle · booth config → Setting config values
Each package manager has a template that takes a list:
booth config --no-tui --select 'go/apt-pkg:htop,jq'
booth config --no-tui --select 'nodejs+npm-pkg:"typescript","tsx"'
booth config --no-tui --select 'python+uv-pkg:"httpx"'There are apt-pkg and brew-pkg, plus per-language extensions: pip-pkg, uv-pkg,
conda-pkg, npm-pkg, yarn-pkg, bun-pkg, go-pkg, cargo-pkg, gem-pkg, hex-pkg,
cabal-pkg, dotnet-pkg, luarocks-pkg and pecl-pkg; code-ext-pkg and
jetbrains-plugin-pkg handle IDE extensions.
More: booth config → Package management templates
When a tool needs more than a package — env vars, a config file, a background service — write
.booth/setups/<name>--setup.sh. It runs as root at image build. Give it a # cb-template: header
and it becomes a template you can select like any other:
#!/bin/bash
# cb-template: DB seed
# cb-disc: Load fixture data into Postgres
# cb-band: 90
# cb-param: SEED_SET default=small suggests=small,full
set -Eeuo pipefail
SEED_SET="${1:-small}"
...booth config --no-tui --overwrite --add-select db-seed:fullDon't type a setup <name> line into the Boothfile instead. It builds, but the Boothfile becomes
hand-written. A script named after a built-in setup replaces it, so pick a new name unless
that is the point.
More: A setup that is its own template · Setup script conventions · Customization
When one setup line is not enough — a package and a script, run-args, a port — write a project
template. It is a single file, .booth/templates/<name>.toml: no directory, no meta.toml,
and no display keys. This one installs libc++1 and runs a script carried inline:
[segments]
"Boothfile--45" = """
install apt libc++1
setup native-libs
"""
[files.setups]
"native-libs--setup.sh" = """
#!/usr/bin/env bash
set -Eeuo pipefail
ldconfig
"""booth config --no-tui --overwrite --add-select native-libsEvery project template lists under This project in the TUI, named after its file unless you
give it a display-name. booth config writes the inline script to
.booth/setups/native-libs--setup.sh each time, so edit the script in the .toml, not the
copy. A project template with the name of a built-in replaces it, with a warning. An extension
of it is .booth/templates/<name>--<ext>--extension.toml.
More: Project-local templates · Template schema
A .booth/Dockerfile with no Boothfile still works: booth builds from it. You give up booth config, the TUI and the catalog. Use it only if you need something a Boothfile cannot express.
Some settings let code inside the booth reach the host. ./booth warns about them, and asks
before starting the most powerful ones:
| Option | Lets the booth | Asks first? |
|---|---|---|
Docker-in-Docker (dind template, --dind) |
Run containers (privileged — effectively host root) | Yes, every run (--dind-allowed with no terminal) |
--privileged, --cap-add, host namespaces, engine socket mounts |
Act as root on the host | Yes (--privileged-allowed with no terminal) |
--device (e.g. /dev/kvm) |
Use a host device | Some devices are exempt |
Writable mounts of ~ or system paths |
Change host files | Warns |
--public |
Be reached from other machines (with a password) | — |
booth print-security-warning lists what a booth would trigger without starting it. To limit what
the booth can reach on the network, there is --egress (it is not a boundary in a DinD booth).
Turn these on only for code you trust.
More: Security · Security checklist · Egress
When the project needs the booth in more than one shape (day-to-day, a deploy run, tracing), keep one base and add only the differences:
.booth/config.toml # always applied
.booth/dev--config.toml # only with --profile dev
.booth/.dev--env # that profile's secrets
The generated .booth/.gitignore already ignores .*--env. Booth refuses to start with a
profile env file that git would commit, so keep that rule if you write the file yourself.
./booth --profile devMore: booth profiles
Line 2 of the Boothfile records the command that produced it:
# Configured by: booth config --no-tui --overwrite --select go+linter --expose +-1910:8090
That recorded command is the baseline. A later booth config starts from it:
| You pass | Result |
|---|---|
| Nothing for a setting | Keeps the recorded value |
--add-select X, --add-env, --add-expose, --add-mount |
Adds one entry, keeps the rest |
--remove-select X (a template, or X+ext for an extension), --remove-env KEY, --remove-expose PORT, --remove-mount PATH |
Drops one entry |
--select …, --env …, --expose …, --mount … |
Replaces that whole list |
booth config --no-tui --overwrite --add-select docker # add a template
booth config --no-tui --overwrite --add-select go+vscode-ext # add an extension to go
booth config --no-tui --overwrite --remove-select python # drop one
booth config # or open the TUI on the current boothVersion pins survive a reconfigure unless you set them again explicitly.
More: booth config → Reconfiguring · Adding or removing one entry
"It generated" is not "it works". Before you commit:
-
Start it and use every tool. Run
./booth, then compile something, run the tests,gh auth status, open the exposed port. A credential that is mounted but not picked up only shows up when you use it. -
Check the round trip. Re-run
booth configwith no flags and confirm nothing changed:git add .booth && booth config --no-tui --overwrite && git diff --exit-code .booth
No diff means the header fully describes the booth: the next person to open it in the TUI gets exactly these files.
Not covered yet: there is no single
booth verifycommand that does both.
| Commit | Keep out of git (the generated .booth/.gitignore does this) |
|---|---|
./booth |
.booth/.env, .booth/.<profile>--env, .booth/.booth.password |
.booth/Boothfile, config.toml, .generated |
.booth/cache/ |
.booth/tools/codingbooth.lock |
.booth/.tmp/ |
setups/, startups/, home/, home-seed/, shared/, console.json, templates/ |
*.bak, *.new, downloaded binaries |
Without .generated, the next booth config cannot tell your later edits from its own output.
Something like this in the project README is enough:
## Development environment
This project runs in a [CodingBooth](https://codingbooth.io). With Docker installed:
./booth
See [Developing in a Booth](https://github.com/NawaMan/CodingBooth/blob/main/docs/USER_GUIDE.md).booth install <version> # updates the project's lock file
booth config --no-tui --overwrite # regenerate against that release's templatesProve it again (section 8), then commit the lock and the .booth/ changes
together.
More: booth install
For a booth that must be identical on every machine and in CI, build the image once and push it:
./booth build --push ghcr.io/myteam --name my-env --tag v1.0
./booth --image ghcr.io/myteam/my-env:v1.0More: booth build · Reproducibility → Store the image
An existing .booth/Dockerfile runs as it is. To move to booth config, read the Dockerfile and
find a template for each tool it installs (booth template search <tool>). Use package templates
for the plain package installs and a # cb-template: setup script or a project template for the
rest. Check the result
with --dryrun.
Not covered yet: there is no importer for
devcontainer.json. Map it by hand the same way:featuresbecome templates,forwardPortsbecome--expose,containerEnvbecomes--env,mountsbecome--mount, andpostStartCommandbecomes a startup hook.