.agents/skills/use-devbox/SKILL.md
devbox applies to directories that have a devbox.json (at the directory root or a subdir root). Outside such directories, devbox does nothing useful.
devbox creates isolated, reproducible development environments from a devbox.json file. The packages it lists come from the Nix package registry and are made available inside the devbox environment — not the bare shell.
devbox.json.devbox.json — the project may install that tool through devbox.devbox is not always installed. Check first:
command -v devbox
If that prints nothing, install it (non-interactive):
curl -fsSL https://get.jetify.com/devbox | bash
devbox installs to ~/.local/bin (or /usr/local/bin). If devbox still isn't found after installing, ensure that directory is on PATH. devbox itself requires the Nix package manager; the install script sets it up if missing.
Look for a devbox.json in the working directory or an ancestor:
ls devbox.json 2>/dev/null || find . -maxdepth 2 -name devbox.json 2>/dev/null
If one exists, the packages it lists are available inside the devbox environment (not the bare shell).
Run any command inside the devbox environment with:
devbox run [cmd]
Examples:
devbox run psql "$MASTER_DB_URL" -c 'SHOW wal_level;'
devbox run python script.py
devbox run gcloud sql instances describe <instance>
devbox run is the right choice for agents and scripts: it loads the environment, runs one command non-interactively, and exits. The first run in a fresh environment may be slow while packages download/build; later runs are cached and fast.
If a directory other than the cwd holds the devbox.json, run from that directory (e.g. devbox run --config path/to/devbox.json [cmd] or cd into it first).
devbox.json can define named scripts under a "shell": { "scripts": { ... } } block. Run them by name — devbox run <script-name> — instead of retyping the underlying command. For example, this repo defines test, lint, fmt, build, and tidy, so devbox run test runs the project's test suite inside the environment.
To see what's defined, run devbox run with no script name (it lists available scripts) or inspect devbox.json.
When you need a binary, decide its source in this order:
Provided by devbox for the current project — if the project's devbox.json supplies it, prefer the devbox version over any system install. Run it via devbox run [cmd].
Provided by the system but not devbox — use the system binary.
Not provided by devbox or the system — check whether devbox can supply it:
devbox search [pkg]
If it's available, ask the user whether they want to install it into the current project before doing so. Only on their confirmation:
devbox add [pkg]
Don't add packages to a project's devbox.json without the user's go-ahead. (devbox rm [pkg] removes one.)
Some projects define long-running services (databases, queues, etc.) in their devbox config:
devbox services ls # list defined services
devbox services up # start services (add -b to run in background)
devbox services stop # stop them
devbox global manages a machine-wide environment that's independent of any project (devbox global add/rm/list). Prefer per-project packages unless the user explicitly wants something available everywhere.
devbox --help — full command list (shell, run, add, services, etc.).devbox run without args, or inspect devbox.json, to see project-defined scripts.devbox shell opens an interactive subshell with the environment loaded (prefer devbox run for one-off, non-interactive commands).devbox install and then inspect the .devbox/nix/profile/default/bin/ directory.command -v devbox and install via curl -fsSL https://get.jetify.com/devbox | bash if missing.devbox.json use it.devbox.json may live in the repo root or a subdir root — check both.devbox.json are only on PATH inside devbox run/devbox shell, not the plain shell.devbox run over devbox shell for non-interactive, one-off commands.