Set up a devcontainer for your project

A devcontainer is a development environment packaged as a container and described by one file in your repo, .devcontainer/devcontainer.json. Open the project and your editor — or a CLI — builds that container and drops you inside it, so everyone who clones the repo gets the same tools and settings, with nothing installed on your host. The containers.dev overview and the VS Code guide explain the idea in full.

claude-sandbox expects one: running Claude inside a throwaway container is the outer layer that keeps a hostile prompt away from your real environment. Getting started assumes you’re already inside a Debian/Ubuntu devcontainer running as root — this page gets you there.

Already have one? If your project opens in a devcontainer today, skip straight back to Getting started.

Use a rootless runtime

claude-sandbox supports rootless containers only. We recommend Podman, which is rootless by default; rootless Docker works too. Rootful containers are not supported.

Rootless is what makes running as root safe. Inside the container you are root and can install packages or change the system freely — but to your computer you’re still just you: files you create in mounted project folders stay owned by your normal account, and that root power can’t reach the rest of your machine.

Using Podman with VS Code? Point the Dev Containers extension at it by setting dev.containers.dockerPath to podman (see alternative runtimes).

A minimal devcontainer

Create .devcontainer/devcontainer.json at the root of your project:

{
  "name": "my-project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "remoteUser": "root",
  "runArgs": ["--device=/dev/net/tun"],
  // Mount the parent folder so your sibling projects are reachable at
  // /workspaces/<project> — handy for working across peer repos.
  "workspaceMount": "source=${localWorkspaceFolder}/..,target=/workspaces,type=bind"
}

That’s enough to run claude-sandbox: a Debian/Ubuntu base, remoteUser: root so the installer can write its system files, the egress jail’s required runArg, and a workspaceMount that puts your sibling projects alongside this one under /workspaces. You may also want to persist your Claude login and settings across rebuilds. Other values you can configure are in the devcontainer.json reference.

You don’t need VS Code

Devcontainers are an open specification, not a VS Code feature. VS Code and GitHub Codespaces are the easiest on-ramps, but the devcontainer CLI builds and enters one straight from a terminal:

npm install -g @devcontainers/cli
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash

You’re now inside the container and can run ./install and claude as Getting started describes.

Next steps

• Getting started — install the sandbox in your new devcontainer and prove it is intact.