From b3af17ffd161deb66487e20bb34b31b29ba48f71 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 25 Jun 2026 14:10:12 +0000
Subject: [PATCH 1/2] docs(contributing): document how to debug Devbox locally

Many commands (e.g. `devbox shell`, `devbox services up`) re-exec a nested
`devbox` subprocess that does the real work. That subprocess is resolved from
PATH, so it is typically the installed Devbox rather than your local build,
which is why debug logs/breakpoints added to a local build don't fire.

Add a "Debugging Devbox Locally" section to CONTRIBUTING.md describing the two
workarounds: pointing the launcher at a local build via DEVBOX_USE_VERSION
(most faithful), and the hidden `--run-in-current-shell` flag (quick).

Fixes #2699

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014fiBLNEAEGUcCJPZ1qpGp6
---
 CONTRIBUTING.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2bee544a437..5c733acf3cc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -63,6 +63,43 @@ environment by following the steps below.
        go build ./cmd/devbox
        ./devbox run -- echo hello, world
 
+### Debugging Devbox Locally
+
+Several Devbox commands (for example `devbox shell` and `devbox services up`)
+do little work themselves. Instead, they re-exec a nested `devbox` subprocess
+inside the project's shell environment, and that subprocess does the real work.
+The nested process is resolved from your `PATH`, so it is usually the *installed*
+version of Devbox rather than the local build you are editing. As a result,
+`devbox run build && dist/devbox services up` may not pick up your changes, and
+debug logs (`DEVBOX_DEBUG=1`) or breakpoints you add won't fire, because the
+interesting work happens in a different binary.
+
+There are two ways to work around this:
+
+1. **Make the launcher use your local build (most faithful).** The Devbox
+   launcher selects which CLI binary to run based on the `DEVBOX_USE_VERSION`
+   environment variable, looking it up in its binary cache. Place your build
+   there and point the launcher at it:
+
+       devbox run build
+       mkdir -p "$HOME/.cache/devbox/bin/0.0.0-dev_$(go env GOOS)_$(go env GOARCH)"
+       cp dist/devbox "$HOME/.cache/devbox/bin/0.0.0-dev_$(go env GOOS)_$(go env GOARCH)/devbox"
+       export DEVBOX_USE_VERSION=0.0.0-dev
+
+   With `DEVBOX_USE_VERSION` exported, every `devbox` invocation — including the
+   nested subprocesses — runs your local build, so debug logs and breakpoints
+   work end to end. Rebuild and re-copy the binary whenever you change the code.
+
+2. **Run the work in the current process (quick).** Many commands accept a
+   hidden `--run-in-current-shell` flag that skips the nested re-exec and does
+   the work in place:
+
+       dist/devbox services up --run-in-current-shell
+
+   This is fast to iterate on, but because it bypasses the nested subprocess its
+   behavior differs slightly from a normal invocation, so some issues won't
+   reproduce this way.
+
 ## Pull Request Process
 
 1. For new features or non-trivial changes, consider first filing an issue to

From 139577263c9a9d8bce173a346ff1ef40dd1d5d7a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 25 Jun 2026 14:14:58 +0000
Subject: [PATCH 2/2] docs(contributing): honor XDG_CACHE_HOME in local debug
 instructions

The launcher's binary cache lives under XDG_CACHE_HOME (falling back to
~/.cache), so use ${XDG_CACHE_HOME:-$HOME/.cache} instead of hard-coding
$HOME/.cache. Factor the path into a variable to avoid repetition.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014fiBLNEAEGUcCJPZ1qpGp6
---
 CONTRIBUTING.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5c733acf3cc..b8700444c58 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -82,8 +82,9 @@ There are two ways to work around this:
    there and point the launcher at it:
 
        devbox run build
-       mkdir -p "$HOME/.cache/devbox/bin/0.0.0-dev_$(go env GOOS)_$(go env GOARCH)"
-       cp dist/devbox "$HOME/.cache/devbox/bin/0.0.0-dev_$(go env GOOS)_$(go env GOARCH)/devbox"
+       cache_dir="${XDG_CACHE_HOME:-$HOME/.cache}/devbox/bin/0.0.0-dev_$(go env GOOS)_$(go env GOARCH)"
+       mkdir -p "$cache_dir"
+       cp dist/devbox "$cache_dir/devbox"
        export DEVBOX_USE_VERSION=0.0.0-dev
 
    With `DEVBOX_USE_VERSION` exported, every `devbox` invocation — including the