Promote a host workspace#

just promote makes a target workspace a self-sufficient claude-sandbox host: a teammate who clones the target only needs the devcontainer to come up, and the installer runs from postCreate.sh with the curated .claude/ already in tree.

Working in an unpromoted workspace?

Running Claude unpromoted is the normal, recommended mode — the shadow and the global integrity guard protect claude in every folder, so a workspace does not need promoting to be safe.

The trade-off is that the just recipes and project commands like /verify-sandbox ship with the claude-sandbox clone, so they are only available when Claude’s working directory is that clone. To use them, cd into the clone (e.g. /workspaces/claude-sandbox), run what you need, then return to your work — dropping back to the clone like this is expected and fine. (Promoting the workspace with just promote makes them available in place, but that is optional.)

just promote                       # promote into $PWD
just promote /workspaces/fastcs    # promote into the named target

What lands in the target#

  1. Curated .claude/ — commands and skills. The integrity guard is not seeded per-repo; it’s global (wired into ~/.claude by install.sh, which the target’s postCreate runs), so promote does not touch the target’s project settings.json, hooks, or statusline.

  2. Install machinery — .devcontainer/claude-sandbox/{install.sh, claude-shadow, promote.sh}, so postCreate can run install.sh directly. The root install shim is not copied.

  3. .devcontainer/postCreate.sh running bash .devcontainer/claude-sandbox/install.sh — created if absent, idempotently appended otherwise.

Wire postCreateCommand yourself#

After it finishes, promote prints a one-line "postCreateCommand" snippet to paste into the target’s .devcontainer/devcontainer.json:

// .devcontainer/devcontainer.json
"postCreateCommand": "bash .devcontainer/postCreate.sh"

promote deliberately does not auto-edit devcontainer.json: it’s JSONC in the wild, structured editing while preserving comments is more code than this repo wants, and you’re the one who knows whether you’ve already wired it or need to combine it with an existing postCreateCommand. This is a one-time edit; subsequent just promote runs are byte-stable.

Idempotency and safety#

  • just promote is idempotent — re-running from this clone re-syncs the copied files byte-equal.

  • It refuses self-targeting (TARGET == clone).

  • It does not touch ~/.claude. The global integrity guard lives in /etc/claude-code/managed-settings.json + /usr/libexec/claude-sandbox/, written by install.sh (which the target’s postCreate runs), not by promote.

For the three-layer model behind what promote seeds versus what the installer establishes globally, see the architecture explanation.