Use devbox

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.

When to reach for it

• The directory has a devbox.json.
• Before concluding a tool is unavailable, check for a devbox.json — the project may install that tool through devbox.
• The user explicitly mentions devbox.

Check it's installed

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.

How to detect

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

How to run

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

Project scripts

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.

Choosing where a binary comes from

When you need a binary, decide its source in this order:

1. 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].

2. Provided by the system but not devbox — use the system binary.

3. 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.)

Services

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

Global packages

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.

Discovering more

• 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).
• To see what binaries devbox is adding, run devbox install and then inspect the .devbox/nix/profile/default/bin/ directory.

Key facts

• devbox is not always installed — check with command -v devbox and install via curl -fsSL https://get.jetify.com/devbox | bash if missing.
• Only directories with a devbox.json use it.
• devbox.json may live in the repo root or a subdir root — check both.
• Packages/scripts defined in devbox.json are only on PATH inside devbox run/devbox shell, not the plain shell.
• Prefer devbox run over devbox shell for non-interactive, one-off commands.
• The first run after adding packages or in a fresh checkout can be slow (downloading/building); subsequent runs are cached.