Run devbox with Dev Container

Prerequisites#

• Docker, or another engine your Dev Containers tool supports.
• VS Code with the Dev Containers extension, or the CLI: npm install -g @devcontainers/cli.

Open the project#

Copy the file into the project:

mkdir -p .devcontainer
cp devcontainer.json .devcontainer/devcontainer.json

In VS Code, choose Reopen in Container. With the CLI, run from the project root:

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . zsh -l

To use another variant, change image, for example to ghcr.io/hambn/devbox:alpine-browser, or to a digest reference to pin one build. To pass a host variable into terminals, add it under remoteEnv, for example "remoteEnv": { "GH_TOKEN": "${localEnv:GH_TOKEN}" }.

Workspace#

The project folder is mounted at /workspace. Because remoteUser is set, Linux hosts rebuild the image with sysadmin changed to your UID and GID, so new files keep your ownership. Shell history and caches in /home/sysadmin are lost when the container is rebuilt.

Files#

• devcontainer.json sets the image, user, workspace mount, and a 1 GB /dev/shm for the browser tier.

Cleanup#

VS Code stops the container when you close the window. With the CLI, remove it with docker rm -f <containerId>, using the ID that devcontainer up printed.

// Copy to .devcontainer/devcontainer.json in your project.
{
  "name": "devbox",
  "image": "ghcr.io/hambn/devbox:ubuntu-full",
  // Naming the user lets Linux hosts remap sysadmin to your UID, so /workspace files keep your ownership.
  "remoteUser": "sysadmin",
  "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind",
  "workspaceFolder": "/workspace",
  // Headless Chromium on the *-browser variants needs more than the 64 MB default /dev/shm.
  "runArgs": ["--shm-size=1g"]
}