If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/jetify-com/devbox shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2w ago
• 28+ active contributors
• Distributed ownership (top contributor 18% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live jetify-com/devbox repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/jetify-com/devbox.

What it runs against: a local clone of jetify-com/devbox — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in jetify-com/devbox | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 45 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of jetify-com/devbox. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/jetify-com/devbox.git
#   cd devbox
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of jetify-com/devbox and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "jetify-com/devbox(\\.git)?\\b" \\
  && ok "origin remote is jetify-com/devbox" \\
  || miss "origin remote is not jetify-com/devbox (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/devbox/main.go" \\
  && ok "cmd/devbox/main.go" \\
  || miss "missing critical file: cmd/devbox/main.go"
test -f "devbox.go" \\
  && ok "devbox.go" \\
  || miss "missing critical file: devbox.go"
test -f "devbox.json" \\
  && ok "devbox.json" \\
  || miss "missing critical file: devbox.json"
test -f ".schema/devbox.schema.json" \\
  && ok ".schema/devbox.schema.json" \\
  || miss "missing critical file: .schema/devbox.schema.json"
test -f ".github/workflows/cli-tests.yaml" \\
  && ok ".github/workflows/cli-tests.yaml" \\
  || miss "missing critical file: .github/workflows/cli-tests.yaml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 45 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~15d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/jetify-com/devbox"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Devbox is a CLI tool written in Go that creates isolated, reproducible development environments by declaratively managing OS-level packages via Nix. Users define required packages in devbox.json, and Devbox generates hermetic shells (similar to package managers like Yarn) that provide exact versions without polluting the host system—powered internally by the Nix package manager with access to 400,000+ package versions. Single-repo CLI project structured as: cmd/devbox/main.go entry point wrapping core devbox.go logic; /examples containing runnable cloud dev setups (argo-workflows, minikube, temporal); .github/workflows/ CI pipelines; configuration schemas in .schema/ (devbox.schema.json, devbox-plugin.schema.json). Config-first: user-facing interface is devbox.json + devbox.lock file pair.

Development teams and individual developers who need consistent, shareable development environments across machines. Specifically: teams using monorepos or multiple projects with conflicting tool versions (e.g., Python 2.7 and Go 1.18 in the same shell), and developers who want to trial new tools without host-system side effects.

Production-ready with active maintenance. The repo shows extensive CI/CD setup (.github/workflows/ with 9+ automated pipelines), structured issue templates, goreleaser config for releases, and multi-language support (919KB Go, TypeScript, Nix). Discord community link suggests established user base, though exact star/contributor counts aren't visible in provided data.

Low-to-moderate risk for a mature project. Dependencies on Nix ecosystem stability (external to this repo), but codebase appears well-tested (cli-tests.yaml CI present). Main risk: tight coupling to Nix toolchain means Nix installation issues propagate; single-language risk mitigated by small TypeScript/Nix portions. Last activity metrics not provided, but presence of stale-issue-cleanup.yml suggests active maintenance.

Active release cycle with dedicated workflows for CLI releases (cli-release.yml, cli-post-release.yml), Docker image releases, and VSCode extension releases (vscode-ext-release.yaml). Maintenance includes stale-issue cleanup and random PR reviewer assignment, suggesting steady community engagement.

git clone https://github.com/jetify-com/devbox.git
cd devbox
# Install via curl (as shown in README):
curl -fsSL https://get.jetify.com/devbox | bash
# Or build locally (Go required):
go build -o devbox ./cmd/devbox
./devbox shell

Daily commands: No traditional 'dev server'—this is a CLI tool. To test locally: go build ./cmd/devbox && ./devbox shell to create a dev shell, or devbox run <command> to execute commands in the isolated environment. CI test command inferred from .github/workflows/cli-tests.yaml.

• cmd/devbox/main.go — CLI entry point—all contributors must understand how devbox commands are initialized and dispatched
• devbox.go — Core Devbox struct and logic—the main abstraction that orchestrates environment setup and package management
• devbox.json — Example devbox manifest—defines the schema and structure all projects must follow for declaring dependencies
• .schema/devbox.schema.json — JSON schema for devbox.json—authoritative specification for valid configuration; critical for validation and tooling
• .github/workflows/cli-tests.yaml — Main test pipeline—shows how devbox is tested on each commit and must pass before merge
• CONTRIBUTING.md — Contributor guide—outlines development workflow, testing requirements, and code standards
• README.md — Project overview and quick-start—essential for understanding devbox's purpose and architecture

• Devbox CLI (cmd/devbox/main.go) (Go) — Entry point; parses flags; routes commands (init, run, shell, clean) to handlers
  • Failure mode: Invalid flags or missing devbox.json causes graceful error and exit; prevents execution
• Devbox Core (devbox.go) — Main

Add a new example project

1. Create a new directory under examples/ (e.g., examples/my-domain/my-project/) (examples/)
2. Define devbox.json with packages, env vars, and shell hooks for your use case (examples/my-domain/my-project/devbox.json)
3. Run devbox to lock dependencies and commit devbox.lock (examples/my-domain/my-project/devbox.lock)
4. Create README.md describing the example, how to run it, and what it demonstrates (examples/my-domain/my-project/README.md)

Add a new CLI command or subcommand

1. Add command handler function in cmd/devbox/ (e.g., cmd/devbox/commands/mycommand.go) (cmd/devbox/main.go)
2. Implement logic using Devbox struct and core methods from devbox.go (devbox.go)
3. Register the command in the main CLI dispatcher (cmd/devbox/main.go)
4. Add integration tests in .github/workflows or test files verifying the command behavior (.github/workflows/cli-tests.yaml)

Extend devbox.json schema with new fields

1. Update .schema/devbox.schema.json to define the new property and its constraints (.schema/devbox.schema.json)
2. Update devbox.go to parse and handle the new field from the manifest (devbox.go)
3. Add example usage in an existing or new devbox.json example file (examples/cloud_development/temporal/devbox.json)
4. Update README.md or CONTRIBUTING.md to document the new schema field (README.md)

Add support for a new language or package manager

1. Implement language/package manager integration logic in devbox.go or a new module (devbox.go)
2. Create an example devbox.json demonstrating the new language setup (examples/data_science/jupyter/devbox.json)
3. Add test cases in cli-tests.yaml to verify integration works end-to-end (.github/workflows/cli-tests.yaml)
4. Document the new language support in CONTRIBUTING.md and README.md (CONTRIBUTING.md)

• Go (Golang) — Fast, compiled CLI tool; easy cross-platform distribution and single binary; minimal runtime dependencies
• Nix/NixOS — Declarative, reproducible package management; enables hermetic dev environments; strong community for language tooling
• JSON schema — Validates devbox.json structure; enables IDE completion and error checking; language-agnostic
• GitHub Actions — Integrated CI/CD; automated testing, release builds, and Docker image publishing on main branch
• direnv (.envrc) — Automatic shell environment loading; seamless integration with existing dev workflows

• Use Nix as the underlying package manager

  • Why: Nix provides true reproducibility and isolation; avoids dependency conflicts across projects
  • Consequence: Nix learning curve for contributors unfamiliar with declarative package management; requires Nix installation on host

• Store lockfile (devbox.lock) in version control

  • Why: Ensures all team members use identical package versions; prevents 'works on my machine' issues
  • Consequence: Lockfile can grow large and be noisy in diffs; requires occasional updates as dependencies change

• CLI-first approach (no GUI or web UI yet)

  • Why: Faster to build, easier to integrate with CI/CD, works in all environments (remote, containers)
  • Consequence: Less discoverable for new users; requires CLI familiarity; limited real-time feedback

• Single devbox.json manifest per project

  • Why: Simplicity; one source of truth for environment definition; easy to reason about and share
  • Consequence: Cannot easily have multiple environments in one repo; monolithic config file for complex projects

• Not a container orchestration tool (e.g., Kubernetes alternative)
• Not a secrets manager; does not handle credential storage or rotation
• Not a full-featured IDE; integrates with editors via CLI but provides no editor plugins
• Not language-specific; aims to support all languages equally rather than optimizing for one
• Not a package registry; does not host packages, only consumes from nixpkgs

Nix requirement: Devbox requires Nix to be installed on the host system—users on non-Unix systems may face friction. Lock file semantics: devbox.lock must be committed to Git alongside devbox.json (similar to yarn.lock); forgetting this breaks reproducibility. Shell detection: The tool auto-detects shell type (bash/zsh/fish/nushell); shell-specific config in .profile, .bashrc, etc. may conflict. Hermetic environment caveats: packages in Devbox are isolated from system, but some tools expect system-wide state (e.g., Docker daemon). direnv integration: .envrc assumes direnv is installed for automatic shell loading; manual devbox shell is fallback. No Windows native support: Devbox on Windows requires WSL2 or similar (not reflected in repo metadata but worth noting).

• Nix Flakes & Reproducible Builds — Devbox abstracts Nix Flakes to provide deterministic environments; understanding flakes helps troubleshoot environment drift and custom package versions
• Hermetic Build Environments — Core value prop of Devbox—packages are isolated and don't pollute host system; understanding what 'hermetic' means prevents misuse expectations
• Lock Files & Dependency Pinning — devbox.lock is the source of truth for reproducibility across team members; understanding lock semantics prevents 'works on my machine' issues
• direnv & Shell Integration — Devbox integrates with direnv via .envrc for seamless environment loading; understanding shell hooks and direnv prevents PATH pollution
• Declarative Configuration & Infrastructure-as-Code — devbox.json is a declarative spec (not imperative bash); this pattern underlies reproducible, version-controlled dev environments
• Package Registry & Nix Packages — Devbox exposes 400k+ packages from nixpkgs; understanding package naming, versions, and attributes is essential for users writing devbox.json
• Plugin Architecture via JSON Schema — devbox-plugin.schema.json enables third-party extensions; understanding schema-driven extensibility helps contributors build custom integrations

• NixOS/nix — Upstream dependency—Devbox is built on Nix; understanding Nix fundamentals is essential for troubleshooting environment issues
• cachix/devenv — Direct alternative solving the same problem (isolated dev envs via Nix); comparison point for feature parity and ecosystem fragmentation
• direnv/direnv — Companion tool often used with Devbox (.envrc integration); enables automatic shell loading without manual devbox shell invocation
• jetify-com/nixpacks — Sibling project by same org; converts Dockerfiles/buildpacks to Nix, complementary to Devbox for containerization workflows
• fatih/devbox — Unrelated tool with same name (Docker-based dev env); useful for disambiguating in searches and understanding namespace collisions

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for devbox.json schema validation

The repo has .schema/devbox.schema.json and .schema/devbox-plugin.schema.json defined, but there are no visible tests validating that example configurations in examples/ directory conform to these schemas. This would catch schema drift and ensure all provided examples are valid, improving reliability for new users following the examples.

• [ ] Create internal/schema or cmd/devbox/schema_test.go to test schema validation
• [ ] Add test cases validating examples/cloud_development/*/devbox.json against .schema/devbox.schema.json
• [ ] Add test cases validating plugin schemas in examples/
• [ ] Integrate schema validation test into cli-tests.yaml workflow

Add GitHub Action workflow for testing Nushell integration

NUSHELL.md exists in the repo indicating Nushell is a supported shell, but there's no dedicated workflow testing Nushell functionality (unlike the existing cli-tests.yaml). This is a critical gap for maintaining shell compatibility across releases.

• [ ] Create .github/workflows/nushell-tests.yaml workflow
• [ ] Add Nushell installation step and basic smoke tests for devbox with Nushell
• [ ] Test .envrc loading and environment activation with Nushell
• [ ] Trigger on CLI releases and main branch pushes (similar to cli-tests.yaml)

Add unit tests for devbox.go core functionality

devbox.go is the core package file (visible in repo root), but there's no visible corresponding devbox_test.go file in the repository structure. This core module likely needs comprehensive unit tests for initialization, configuration loading, and environment setup logic.

• [ ] Create devbox_test.go with unit tests for main devbox package functions
• [ ] Add test cases for devbox.json parsing and lock file handling
• [ ] Add test cases for environment variable configuration and shell integration
• [ ] Integrate into cli-tests.yaml or create dedicated unit-tests.yaml workflow

• Add integration tests for devbox.lock version pinning: Test suite exists (cli-tests.yaml) but no explicit coverage shown for lock file semantics; adding tests in cmd/devbox/ for lock validation would prevent regressions
• Document plugin schema with examples in examples/: .schema/devbox-plugin.schema.json exists but no example plugin in examples/; adding a minimal working plugin (e.g., custom package source) would help contributors understand extensibility
• Add schema validation error messages to devbox.go: Schema exists but user-facing error messages for invalid devbox.json are likely generic; improving error clarity (e.g., 'package xyz not found in Nix registry') would reduce support burden

The Devbox project shows moderate security posture with some concerns. The primary issue is the use of a significantly outdated and beta-version Python dependency (temporalio 0.1b4) which likely contains known vulnerabilities. Unspecified Cython versions add additional risk through potential supply chain inconsistencies. The project structure suggests good practices with examples and clear organization, but the dependency management needs improvement. No obvious hardcoded secrets were detected in the file structure provided, but comprehensive CI/CD and dependency scanning is recommended to ensure production readiness.

• High · Outdated and Vulnerable Python Dependency — examples/cloud_development/temporal/requirements.txt. The temporalio package version 0.1b4 is a beta release from early development (likely 2021-2022 era). This version is significantly outdated and likely contains known security vulnerabilities. Beta versions should never be used in production environments. Fix: Update temporalio to the latest stable release (currently 1.x or higher). Run 'pip list --outdated' and update with 'pip install --upgrade temporalio'.
• Medium · Unspecified Cython Version — examples/cloud_development/temporal/requirements.txt. The cython dependency in the requirements file has no version pinning. This can lead to inconsistent builds and potential compatibility issues. While Cython itself is generally secure, unversioned dependencies can introduce unexpected breaking changes or security patches that weren't tested. Fix: Pin the Cython version to a specific release: 'cython==0.29.x' or 'cython==3.0.x'. Use 'pip-audit' or similar tools to check for known vulnerabilities in the pinned version.
• Medium · Missing Dependency Lock File Integrity — devbox.lock and multiple example directories. The repository includes devbox.lock files across multiple examples but no evidence of cryptographic verification or integrity checks. This could allow supply chain attacks if lock files are tampered with. Fix: Implement lock file signing/verification using tools like sigstore or similar. Document the lock file verification process in CONTRIBUTING.md.
• Low · Potential Information Disclosure in GitHub Workflows — .github/workflows/. Multiple GitHub workflow files (.github/workflows/) are present. Without reviewing their contents, there's a risk of exposed secrets, unvalidated external inputs, or insecure CI/CD configurations that could leak sensitive information. Fix: Conduct a security audit of all workflow files, specifically checking for: hardcoded secrets, use of untrusted third-party actions, improper secret handling in logs, and insufficient input validation on workflow triggers.
• Low · Incomplete Dependency Analysis — Root directory and all subdirectories. Only partial package files were provided (requirements.txt from one example). The full dependency tree across Go modules, other Python requirements files, and npm packages (if present) was not analyzed. Fix: Perform comprehensive dependency scanning using: 'go mod audit', 'pip-audit', 'npm audit', and 'snyk' to identify all known vulnerabilities across the entire project.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.