# Use your devcontainer.json

> Run a repo's devcontainer.json on a Prized box with the Dev Containers CLI or VS Code's Reopen in Container: image, features, Docker Compose, Docker in Docker, and create commands, with nothing Prized-specific in the file.

URL: https://prized.dev/docs/devcontainers

A box runs Docker, so the [Dev Containers CLI](https://github.com/devcontainers/cli), the open-source reference implementation of the spec Codespaces and Ona read, builds your repo's `.devcontainer/devcontainer.json` there, with nothing Prized-specific in it. The box keeps its disk, so the container is built once.

## 1. Get a box [#1-get-a-box]

Sign up at [prized.dev](https://prized.dev/sign-in): the tour starts a box on $30 of free credit with no card, then shows one command that installs the CLI and signs this machine in ([Quickstart](https://prized.dev/docs/quickstart)). Most dev containers want a Small (4 vCPU, 16 GB) or larger ([Box size](#box-size)); to resize a smaller box, using your box's name for `mango`:

```bash
prized box resize mango Small
```

## 2. Install the Dev Containers CLI on the box [#2-install-the-dev-containers-cli-on-the-box]

Open a shell on the box with `prized ssh`, then:

```bash title="you@box ~"
sudo snap install node --classic --channel=22
sudo npm install -g @devcontainers/cli
```

The CLI needs Node.js 20 or later, newer than Ubuntu's own `nodejs` package. Both lines take about 15 seconds.

## 3. Start the container [#3-start-the-container]

```bash title="you@box ~"
git clone https://github.com/you/myproject ~/code/myproject
cd ~/code/myproject
devcontainer up --workspace-folder .
```

It pulls or builds the image, installs the features, runs `onCreateCommand` and `postCreateCommand`, and ends with `"outcome":"success"`. A first build takes two to five minutes; after that, and after the box restarts, `devcontainer up` starts the same container in seconds. If `prized setup` already syncs the project to `~/code/myproject`, skip the clone; for a private repo, clone with `gh repo clone owner/name ~/code/myproject`.

## 4. Work in it [#4-work-in-it]

```bash title="you@box ~/code/myproject"
devcontainer exec --workspace-folder . npm test
```

`devcontainer exec` runs a command in the container as its `remoteUser`, in its workspace folder; `devcontainer exec --workspace-folder . bash` opens a shell there. The repo folder is mounted into the container, so edits on the box, by you, an agent, or [sync](https://prized.dev/docs/sync) from your laptop, are in the container at once. An agent on the box runs the tests the same way: say so in your `CLAUDE.md` or `AGENTS.md`.

## 5. Open its ports on your machine [#5-open-its-ports-on-your-machine]

The CLI does not act on `forwardPorts`; an editor does that. Publish the port with `appPort`, then recreate the container, which reruns its create commands:

```json title=".devcontainer/devcontainer.json"
"appPort": [8080]
```

```bash title="you@box ~/code/myproject"
devcontainer up --workspace-folder . --remove-existing-container
```

Port 8080 then opens on your machine's localhost like any port on the box ([Ports](https://prized.dev/docs/ports)), once the app listens on `0.0.0.0` inside the container, as any published Docker port needs (`vite --host`, for one). `prized ports share 8080` makes a link for your workspace's members. A Docker Compose config publishes a port with `ports` in its compose file instead.

## Or open it in VS Code [#or-open-it-in-vs-code]

Clone the repo on the box as in step 3. Then install Microsoft's **Remote - SSH** and **Dev Containers** extensions, run **Remote-SSH: Connect to Host** and pick your box ([steps](https://prized.dev/docs/cursor-remote-ssh)), open `~/code/myproject`, and run **Dev Containers: Reopen in Container**. VS Code builds the container with the box's Docker, so it needs neither step 2 nor Docker on your machine, and forwards the container's `forwardPorts` to your machine itself ([VS Code's guide](https://code.visualstudio.com/remote/advancedcontainers/develop-remote-host#connect-using-the-remote-ssh-extension)).

## Box size [#box-size]

* **Memory decides the size.** On a Small, a Spring Boot app's tests, with MySQL and Postgres in Docker in Docker, ran in 95 seconds in under 4 GB, and a Node monorepo's API tests in under 8 GB. A Nano ran the same Spring Boot tests in about 4 minutes, using swap; give a monorepo or several services a Small or larger.
* **Disk:** a dev container image is often 2.5 to 3.5 GB, with as much again in build cache, which `docker builder prune` frees ([Machines](https://prized.dev/docs/machines#disk)).

## If it fails [#if-it-fails]

* **A feature stops on a newer base image.** `docker-in-docker:2` with its default `"moby": true` fails on `mcr.microsoft.com/devcontainers/base:ubuntu`, which is now Ubuntu 26.04: move to `docker-in-docker:4` or set `"moby": false` in its options. A stale `onCreateCommand` or `workspaceFolder` fails on any host the same way; fix it in the file.
* **To fix it without a commit,** keep a corrected copy outside the repo, `appPort` included, and name it on every command: `devcontainer up --workspace-folder . --override-config ~/devcontainer.json`, and the same for `devcontainer exec`. Adding a feature with `devcontainer up --additional-features` does not change the options of one the file already has.
* **Docker in Docker works:** privileged containers, cgroup v2, Testcontainers, and Compose inside the container run as they do elsewhere.
* **amd64 only:** an image or feature with no amd64 build does not run, since boxes are x86\_64 ([Machines](https://prized.dev/docs/machines#architecture-and-virtualization)).