Skip to content

Commit c0b87d6

Browse files
mikeland73claude
mikeland73
and
claude
committed
Add agent skill for devbox
Packages devbox usage guidance as a SKILL.md so AI coding agents (Claude Code, Cursor, Copilot, etc.) have structured, production-ready reference material for authoring devbox.json, managing Nix packages, writing scripts/services, and generating Dockerfiles or devcontainers. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 52670c4 commit c0b87d6

5 files changed

Lines changed: 552 additions & 0 deletions

File tree

‎skills/devbox/SKILL.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
name: devbox
3+
description: Devbox expert guidance. Use when creating isolated development environments, managing project dependencies with Nix packages, authoring devbox.json, writing scripts or services, or generating Dockerfiles and devcontainers from a devbox project.
4+
metadata:
5+
docs:
6+
- "https://www.jetify.com/devbox/docs"
7+
- "https://github.com/jetify-com/devbox"
8+
pathPatterns:
9+
- 'devbox.json'
10+
- 'devbox.lock'
11+
- '.devbox/**'
12+
bashPatterns:
13+
- '^\s*devbox(?:\s|$)'
14+
---
15+
16+
# Devbox Skill
17+
18+
[Devbox](https://github.com/jetify-com/devbox) creates isolated, reproducible development environments powered by Nix. You declare packages and scripts in a `devbox.json`; Devbox materializes a shell where everyone on the team gets the exact same tool versions without polluting the host machine. Use `devbox <command> -h` for full flag details on any command.
19+
20+
## Quick Start
21+
22+
```bash
23+
curl -fsSL https://get.jetify.com/devbox | bash # install devbox
24+
devbox init # create devbox.json in cwd
25+
devbox add go@1.22 nodejs@20 # add packages (name@version)
26+
devbox shell # enter the isolated shell
27+
devbox run <script> # run a script from devbox.json
28+
```
29+
30+
Packages resolve against the Nix package registry. Browse versions at [nixhub.io](https://www.nixhub.io).
31+
32+
## The `devbox.json` File
33+
34+
The project's source of truth. Minimum viable file:
35+
36+
```json
37+
{
38+
"packages": ["go@1.22", "nodejs@20"],
39+
"shell": {
40+
"init_hook": ["echo 'Welcome'"],
41+
"scripts": {
42+
"test": "go test ./...",
43+
"build": ["go build ./...", "echo done"]
44+
}
45+
},
46+
"env": {
47+
"GOENV": "off",
48+
"PATH": "$PWD/bin:$PATH"
49+
}
50+
}
51+
```
52+
53+
- `packages`: array of `name@version` strings, or an object with per-package `platforms` / `excluded_platforms` / `outputs` / `patch` settings.
54+
- `shell.init_hook`: commands run every time the environment starts (both `devbox shell` and `devbox run`). Keep it fast — it runs often.
55+
- `shell.scripts`: named commands invoked with `devbox run <name>`. A value can be a string or an array of strings executed in order.
56+
- `env`: extra env vars. Only `$PATH` and `$PWD` are expanded; no other variable expansion or command substitution.
57+
- `include`: plugin references (e.g. `"plugin:nginx"`, `"path:./mydir"`, `"github:owner/repo"`).
58+
59+
See `references/devbox-json.md` for the full schema.
60+
61+
## Decision Tree
62+
63+
Use this to route to the correct sub-topic:
64+
65+
- **Add or remove a package** → `devbox add <pkg>@<ver>` / `devbox rm <pkg>`. See `references/packages.md`.
66+
- **Enter an isolated shell** → `devbox shell`. Add `--pure` for a shell that inherits almost nothing from the host.
67+
- **Run a task** → `devbox run <script>`. Pass arguments after `--` (e.g. `devbox run -- cowsay -d hi`). See `references/scripts-services.md`.
68+
- **Install all packages in CI** → `devbox install` (no shell). Pair with `actions/cache` keyed on `devbox.lock`.
69+
- **Update packages** → `devbox update` (all) or `devbox update <pkg>` (one). Use `--no-install` to update the lockfile only.
70+
- **Find a package** → `devbox search <pkg>`.
71+
- **Inspect installed packages** → `devbox list` / `devbox info <pkg>`.
72+
- **Long-running services (dbs, workers)** → `devbox services start|stop|ls|attach`. See `references/scripts-services.md`.
73+
- **Global tools (available everywhere)** → `devbox global add|rm|list`. See `references/global-and-templates.md`.
74+
- **Bootstrap from a template** → `devbox create --template <name>` (use `--show-all` to list templates).
75+
- **Generate Dockerfile / devcontainer / direnv** → `devbox generate dockerfile|devcontainer|direnv|alias|readme`.
76+
- **Load env into the host shell** → `eval "$(devbox shellenv)"`, or `devbox generate direnv` for automatic loading.
77+
- **Secrets (Jetify Cloud)** → `devbox secrets init|set|list|download|upload`.
78+
- **Multiple envs (dev/prod/preview)** → `--environment <name>` flag.
79+
- **Multi-project repos** → `--all-projects` on `run` and `update`; `--sync-lock` on `update`.
80+
81+
## Critical: Lockfile Hygiene
82+
83+
`devbox.lock` pins exact Nix store paths for every package. **Always commit it.** Without it, teammates and CI will get different versions.
84+
85+
- `devbox install --tidy-lockfile` repairs missing store paths.
86+
- `devbox update --sync-lock` reconciles lockfiles across multiple projects in one repo.
87+
- Do not hand-edit `devbox.lock`.
88+
89+
## Integrating with the Host Shell
90+
91+
`devbox shell` spawns a subshell, which is noisy for daily work. Two better options:
92+
93+
1. **direnv**: `devbox generate direnv` writes a `.envrc` so entering the directory auto-loads the environment. Requires `direnv` installed on the host.
94+
2. **shellenv**: `eval "$(devbox shellenv)"` inline-loads the environment into the current shell. Useful in CI or one-off scripts.
95+
96+
## CI/CD
97+
98+
Typical GitHub Actions pattern:
99+
100+
```yaml
101+
- uses: jetify-com/devbox-install-action@v0.13.0
102+
with:
103+
enable-cache: 'true'
104+
- run: devbox run test
105+
```
106+
107+
Without the action, use `devbox install` + cache `~/.nix-*` and `.devbox/` keyed on `devbox.lock`. Avoid `devbox shell` in CI — use `devbox run <cmd>` (non-interactive) or `eval "$(devbox shellenv)"` instead.
108+
109+
## Anti-Patterns
110+
111+
- **Running devbox without a lockfile committed.** Defeats reproducibility. Commit `devbox.lock` alongside `devbox.json`.
112+
- **Using unversioned packages in production configs** (e.g. `"go"` instead of `"go@1.22"`). The resolver will pick whatever `@latest` resolves to the day you first install it; `devbox update` is the only way to bump it. Pin versions.
113+
- **Shell substitution in `env` values.** Only `$PATH` / `$PWD` expand. Put dynamic logic in `init_hook` instead.
114+
- **Heavy work in `init_hook`.** It runs on *every* `devbox run`, not just shell entry. Keep it to env mutations; move builds to scripts.
115+
- **`devbox shell` inside scripts or CI.** Blocks on an interactive prompt. Use `devbox run` or `devbox shellenv` instead.
116+
- **Editing `devbox.lock` by hand.** Let `devbox update`, `devbox install --tidy-lockfile`, or `devbox add` regenerate it.
117+
- **Forgetting `--` before flags to the target command.** `devbox run cowsay -d hi` tries to parse `-d` as a devbox flag. Use `devbox run -- cowsay -d hi`.
118+
- **Mixing `devbox` and `devbox global`.** `global` manages a separate config at `devbox global path` — project installs never leak into it, and vice versa.
119+
120+
## Common Recipes
121+
122+
- **New Go project**: `devbox init && devbox add go@latest && devbox shell`
123+
- **Dockerize**: `devbox generate dockerfile` produces a `Dockerfile` that replicates the shell.
124+
- **Reproduce in a devcontainer**: `devbox generate devcontainer` writes `.devcontainer/` for VS Code.
125+
- **Share a global toolset**: `devbox global push` (to Jetify Cloud or a git repo); teammates run `devbox global pull`.
126+
- **Run Postgres for local dev**: `devbox add postgresql` then `devbox services up postgresql`.

‎skills/devbox/references/devbox-json.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# `devbox.json` Reference
2+
3+
Full schema is at `.schema/devbox.schema.json` in the devbox repo. This is the practical subset.
4+
5+
## Top-level fields
6+
7+
| Field | Type | Notes |
8+
|---|---|---|
9+
| `$schema` | string | Schema version URL. Optional. |
10+
| `name` | string | Project name. Optional. |
11+
| `description` | string | Human-readable description. Optional. |
12+
| `packages` | array \| object | Packages to install. See below. |
13+
| `env` | object | Extra env vars. Only `$PATH` / `$PWD` expand. |
14+
| `shell.init_hook` | string \| array<string> | Runs on every shell/run entry. |
15+
| `shell.scripts` | object | Named commands; value is string or array<string>. |
16+
| `include` | array<string> | Plugin includes. See below. |
17+
| `env_from` | string | Inherit env from another devbox project path. |
18+
19+
## `packages` — two forms
20+
21+
**Array form** (simple, most common):
22+
23+
```json
24+
"packages": ["go@1.22", "nodejs@20", "postgresql@15"]
25+
```
26+
27+
**Object form** (per-package metadata):
28+
29+
```json
30+
"packages": {
31+
"go": "1.22",
32+
"postgresql": { "version": "15", "excluded_platforms": ["aarch64-darwin"] },
33+
"ffmpeg": { "version": "latest", "outputs": ["bin", "lib"], "patch": "always" }
34+
}
35+
```
36+
37+
Per-package options:
38+
39+
- `version`: semver or `latest`.
40+
- `platforms`: only install on these platforms (allowlist).
41+
- `excluded_platforms`: skip on these platforms (denylist). Cannot be combined with `platforms`.
42+
- `outputs`: Nix outputs to install (most packages need only the default). Useful for libraries.
43+
- `patch`: `auto` (default), `always`, or `never`. Controls glibc patching on Linux.
44+
- `glibc_patch`: boolean shorthand for forcing glibc patching.
45+
- `allow_insecure`: mark a CVE-flagged package as allowed. Pair with `devbox add --allow-insecure`.
46+
- `disable_plugin`: skip any built-in plugin registered for this package.
47+
48+
Platform values: `i686-linux`, `aarch64-linux`, `aarch64-darwin`, `x86_64-darwin`, `x86_64-linux`, `armv7l-linux`.
49+
50+
## `env` — environment variables
51+
52+
```json
53+
"env": {
54+
"GOENV": "off",
55+
"PATH": "$PWD/bin:$PATH",
56+
"DATABASE_URL": "postgres://localhost/dev"
57+
}
58+
```
59+
60+
Only `$PATH` and `$PWD` are expanded. **No command substitution, no other variable expansion.** Put dynamic logic in `init_hook` instead.
61+
62+
## `shell` — scripts and hooks
63+
64+
```json
65+
"shell": {
66+
"init_hook": [
67+
"unset GOROOT GOTOOLCHAIN",
68+
"export PROJECT_ROOT=$PWD"
69+
],
70+
"scripts": {
71+
"test": "go test ./...",
72+
"build": ["go mod tidy", "go build -o bin/app ./cmd/app"],
73+
"dev": "air"
74+
}
75+
}
76+
```
77+
78+
- `init_hook` runs on every `devbox shell` AND every `devbox run`. Keep it cheap.
79+
- Script values can be a single string or an array of strings executed sequentially, stopping on first non-zero exit.
80+
- Invoke with `devbox run <name>`. Arguments after `--` are passed to the final command.
81+
82+
## `include` — plugins
83+
84+
```json
85+
"include": [
86+
"plugin:nginx",
87+
"path:./plugins/my-plugin",
88+
"github:jetify-com/devbox-plugins#path/to/plugin"
89+
]
90+
```
91+
92+
- `plugin:<name>` — built-in plugin shipped with devbox (see `pkg` directory in the devbox repo).
93+
- `path:<dir>` — local plugin directory containing a `plugin.json`.
94+
- `github:owner/repo[#path]` — plugin from a GitHub repo.
95+
96+
Plugins can contribute packages, env vars, services, and files. See `.schema/devbox-plugin.schema.json` for the plugin schema.
97+
98+
## `env_from`
99+
100+
```json
101+
"env_from": "../shared-env"
102+
```
103+
104+
Inherits env and packages from another devbox project on disk. Useful for monorepos with a shared base environment.
105+
106+
## Full example
107+
108+
```json
109+
{
110+
"$schema": "https://raw.githubusercontent.com/jetify-com/devbox/0.17.2/.schema/devbox.schema.json",
111+
"name": "my-api",
112+
"description": "Backend service",
113+
"packages": [
114+
"go@1.22",
115+
"postgresql@15",
116+
"redis@7"
117+
],
118+
"env": {
119+
"CGO_ENABLED": "0",
120+
"PATH": "$PWD/bin:$PATH"
121+
},
122+
"shell": {
123+
"init_hook": [
124+
"test -d bin || mkdir bin"
125+
],
126+
"scripts": {
127+
"build": "go build -o bin/api ./cmd/api",
128+
"test": "go test -race ./...",
129+
"dev": ["devbox services up -b", "air"]
130+
}
131+
},
132+
"include": ["plugin:postgresql", "plugin:redis"]
133+
}
134+
```

‎skills/devbox/references/global-and-templates.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Global Packages, Templates, and Generators
2+
3+
## `devbox global` — machine-wide tools
4+
5+
`devbox global` manages a separate config (kept at `$(devbox global path)`) that's always on your PATH, independent of any project. Mirror of the per-project commands:
6+
7+
```bash
8+
devbox global add jq ripgrep fzf # add tools
9+
devbox global list # show installed
10+
devbox global rm jq
11+
devbox global install # reinstall from config
12+
devbox global update # update all
13+
devbox global path # print config directory
14+
```
15+
16+
To make it live in your shell, add one of:
17+
18+
```bash
19+
eval "$(devbox global shellenv)" # in ~/.zshrc or ~/.bashrc
20+
```
21+
22+
### Sharing a global config
23+
24+
```bash
25+
devbox global push # push to Jetify Cloud
26+
devbox global push git@github.com:me/dotfiles-devbox.git # or your own git repo
27+
devbox global pull <url-or-file> # pull on another machine
28+
```
29+
30+
Useful for keeping the same CLI toolkit across laptops.
31+
32+
**Global and project configs never mix.** A project's `devbox.json` doesn't see global packages unless you explicitly run `eval "$(devbox global shellenv)"` in your shell first.
33+
34+
## `devbox create` — templates
35+
36+
```bash
37+
devbox create --show-all # list templates
38+
devbox create my-proj --template go # scaffold into ./my-proj
39+
devbox create . --template python # scaffold into cwd
40+
```
41+
42+
Templates are starter `devbox.json` + supporting files for common stacks (go, python, node, rust, etc.). Use when starting fresh.
43+
44+
## `devbox generate` — supporting files
45+
46+
```bash
47+
devbox generate readme # regenerate the project README from devbox.json
48+
devbox generate dockerfile # Dockerfile that replicates the shell
49+
devbox generate devcontainer # .devcontainer/ for VS Code
50+
devbox generate direnv # .envrc for direnv auto-loading
51+
devbox generate alias # shell aliases for scripts
52+
```
53+
54+
### `generate dockerfile`
55+
56+
Produces a `Dockerfile` that installs Nix, runs `devbox install`, and sets the entrypoint. The resulting image reproduces the dev shell. Pair with `.dockerignore` to avoid shipping `.devbox/` build artifacts.
57+
58+
### `generate devcontainer`
59+
60+
Writes `.devcontainer/devcontainer.json` and `.devcontainer/Dockerfile`. VS Code's Remote-Containers will pick it up and build an identical environment inside Docker.
61+
62+
### `generate direnv`
63+
64+
Writes a `.envrc` at the project root that runs `use devbox`. After `direnv allow`, the devbox environment activates automatically when you `cd` into the directory and deactivates when you leave. The recommended daily-use setup.
65+
66+
### `generate readme`
67+
68+
Regenerates the auto-generated README section (the `<!-- gen-readme start -->` block) from the current `devbox.json` — scripts, packages, env, init hook. Run after changing `devbox.json` to keep docs fresh.
69+
70+
## Secrets
71+
72+
`devbox secrets` integrates with Jetify Cloud for encrypted secret storage per environment:
73+
74+
```bash
75+
devbox secrets init # link project to a Jetify secrets store
76+
devbox secrets set API_KEY=sk-... # store a secret
77+
devbox secrets list --environment prod # list for an environment
78+
devbox secrets download .env.local # materialize to a file
79+
devbox secrets upload .env # bulk import from a .env file
80+
devbox secrets remove API_KEY
81+
```
82+
83+
Environments (`dev` / `prod` / `preview`) scope secrets separately. Pass `--environment <name>` on `run`, `shell`, and `secrets` commands.
84+
85+
## Auth
86+
87+
```bash
88+
devbox auth login # log in to Jetify Cloud (needed for secrets, global push)
89+
devbox auth logout
90+
devbox auth whoami
91+
```

0 commit comments

Comments
 (0)