Devbox

/devbox

Create and manage Namespace devboxes. Each box gets its own name, SSH alias, and forwarded ports.

When the request involves agent work (an issue, ad-hoc task, or variant comparison), follow the OpenCode profile after the base lifecycle:

• OpenCode profile for boxes with opencode serve

Parsing the /devbox argument

Lifecycle

Identifiers

Compute before starting. Report connection details to the user immediately.

Step 0: Resolve image

Before creating the devbox, determine which image to use. Check in this order:

1. User-specified image ("use my opencode image", "use the rails image") — look it up:

   devbox image list -o json | jq -r '.[] | .name'
   

2. Dockerfile.devbox in the project root — if it exists, this project defines its own devbox image. Check if a matching image is already built, and build/rebuild if needed:

   if [ -f Dockerfile.devbox ]; then
     IMAGE_NAME="${REPO_NAME}-devbox"
     EXISTING=$(devbox image list -o json | jq -r --arg name "$IMAGE_NAME" '.[] | select(.name==$name) | .name')
     if [ -z "$EXISTING" ]; then
       echo "Building image $IMAGE_NAME from Dockerfile.devbox..."
       devbox image build ./ -f Dockerfile.devbox --name "$IMAGE_NAME" \
         --secrets OPENCODE_API_KEY=<sec_id>
     fi
   fi
   

   The <sec_id> comes from nsc vault list or a prior vault add. Check the agent profile for secret setup.

3. No Dockerfile.devbox, no user preference — fall back to the spec's default (builtin:agents).

Override the spec's image: line via sed if using a non-default image.

Custom images: Namespace supports any Docker base image — you are not limited to builtin:agents or builtin:base. If the project needs a specific runtime (e.g. ruby:3.3.9-slim, node:22), create a Dockerfile.devbox in the project root. Namespace converts any image into its optimized format.

Do NOT install Docker in Dockerfile.devbox. Namespace devboxes provide Docker automatically (setup_docker_client: true). Only add application-level dependencies (runtimes, libraries, tools) to the image. Docker commands like docker compose up work out of the box in session commands.

Step 1: Create

Resolve the repo from --repo flag or git remote get-url origin. Derive REPO_NAME (the final path segment) for use in session commands.

If the project has a devbox.yaml in the root, use it directly — it already contains the image, sessions, and repo config. Only rewrite name_prefix::

mkdir -p .devbox-tmp
REPO=$(git remote get-url origin 2>/dev/null | sed 's|.*github.com[:/]||;s|\.git$||')
REPO_NAME=$(basename "$REPO")

if [ -f devbox.yaml ]; then
  sed 's/^name_prefix:.*/name_prefix: <PREFIX>/' devbox.yaml > .devbox-tmp/spec.yaml
else
  # No project spec — build one from the skill's base template
  sed 's/^name_prefix:.*/name_prefix: <PREFIX>/' .agents/skills/devbox/devbox.yaml > .devbox-tmp/spec.yaml
  [ -n "$IMAGE_NAME" ] && sed -i 's/^image:.*/image: '"$IMAGE_NAME"'/' .devbox-tmp/spec.yaml
  [ -n "$REPO" ] && echo "repository: github.com/$REPO" >> .devbox-tmp/spec.yaml
  # Append sessions per the OpenCode profile instructions
fi

devbox create --from .devbox-tmp/spec.yaml 2>&1 | tee .devbox-tmp/create.log
NAME=$(grep -oE 'ssh [^ ]+\.devbox\.namespace' .devbox-tmp/create.log | head -1 | awk '{print $2}' | sed 's/\.devbox\.namespace$//')
echo "devbox: $NAME"

When a project devbox.yaml exists, skip the "Add sessions to spec" step in the agent profile — sessions are already defined.

Step 2: Configure

devbox configure-ssh "$NAME" >/dev/null
devbox setup-github "$NAME" || echo "setup-github skipped (gh CLI not on image)"

setup-github requires gh on the devbox. It ships with builtin:agents / builtin:base but not with custom base images (e.g. ruby:*-slim). The command is non-critical — repo cloning works via the spec's repository: line regardless.

Step 3: Open tunnels

Forward ports from the devbox to localhost. Adjust the remote targets to match whatever the devbox runs (values below are defaults from the Constants table).

ssh -fN -o LogLevel=ERROR -o ExitOnForwardFailure=yes \
  -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
  -L <TUNNEL_PORT>:localhost:<TUNNEL_REMOTE_PORT> \
  -L <APP_PORT>:<APP_BIND_HOST>:<APP_PORT_INTERNAL> \
  "$NAME.devbox.namespace"

For plain devbox requests, stop here. Report the box name + SSH alias.

For agent dispatch requests, continue with the relevant profile.

Teardown

Lookup

Box names encode the dispatch identity via name_prefix:

• Issue: issue-<N>-<random> (e.g. issue-32-rsep2bmaq4)
• Ad-hoc: <slug>-<random>

devbox list -o json | jq -r '.[] | select(.name | startswith("issue-32-")) | .name'

Or by deterministic port (issue mode): lsof -iTCP:40032 -sTCP:LISTEN.

Constants

Change these when the spec's session command moves to a different stack or agent runtime.

Common overrides by framework:

Files

• devbox.yaml - static Namespace devbox spec. name_prefix: is rewritten per dispatch via sed.
• profiles/opencode.md - OpenCode agent dispatch and monitoring.
• prompts/issue.md, prompts/adhoc.md - prompt templates (used by agent profiles).

Host env

• gh auth status green; GitHub auth is forwarded into the box.