diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..c31dd5b
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,21 @@
+{
+  "name": "starter",
+  "dockerComposeFile": "docker-compose.yml",
+  "service": "workspace",
+  "workspaceFolder": "/workspace",
+
+  "forwardPorts": [5173, 4983],
+  "portsAttributes": {
+    "5173": { "label": "Vite dev", "onAutoForward": "notify" },
+    "4983": { "label": "Drizzle Studio", "onAutoForward": "silent" }
+  },
+
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+  },
+
+  "postCreateCommand": ".devcontainer/post-create.sh",
+  "postStartCommand": "docker compose -f /workspace/docker-compose.yml up -d --wait",
+
+  "remoteUser": "node"
+}
diff --git a/.devcontainer/docker-compose.yml b/.devcontainer/docker-compose.yml
new file mode 100644
index 0000000..61d1fd9
--- /dev/null
+++ b/.devcontainer/docker-compose.yml
@@ -0,0 +1,17 @@
+services:
+  workspace:
+    image: mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm
+    command: sleep infinity
+    privileged: true
+    environment:
+      TESTCONTAINERS_RYUK_DISABLED: 'true'
+    volumes:
+      - ..:/workspace:cached
+      - node-modules:/workspace/node_modules
+      - pnpm-store:/home/node/.local/share/pnpm/store
+      - dind-storage:/var/lib/docker
+
+volumes:
+  node-modules:
+  pnpm-store:
+  dind-storage:
diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh
new file mode 100755
index 0000000..f9b9446
--- /dev/null
+++ b/.devcontainer/post-create.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+corepack enable
+corepack prepare pnpm@10.32.1 --activate
+
+pnpm config set store-dir /home/node/.local/share/pnpm/store
+
+pnpm install
+
+pnpm exec playwright install --with-deps
+
+docker version >/dev/null
+docker compose -f /workspace/docker-compose.yml up -d --wait
diff --git a/README.md b/README.md
index 202d4d8..7fc284a 100644
--- a/README.md
+++ b/README.md
@@ -18,11 +18,17 @@ This README is both **descriptive** (what the repo enforces today) and **prescri
 
 ## Getting started
 
+This repo is developed exclusively inside a dev container. The container owns the inner loop — Postgres, the Vite dev server, Vitest, Playwright browsers, and the testcontainers daemon all run inside it, so two workspaces side-by-side never collide on host ports or share state. Local `pnpm install` / `pnpm dev` on the host is unsupported.
+
+Open the workspace and **Reopen in Container** (VS Code / Cursor with the Dev Containers extension), or:
+
 ```sh
-pnpm install
-pnpm dev
+devcontainer up --workspace-folder .
+devcontainer exec --workspace-folder . pnpm dev
 ```
 
+The first build runs `.devcontainer/post-create.sh`, which installs pnpm deps and Playwright browsers into per-workspace named volumes, then runs `docker compose up -d --wait` against the root `docker-compose.yml` on the container's nested docker daemon. Postgres (and any future app services) are reachable inside the container at `localhost:5432` and are not published to the real host.
+
 Run the test suites:
 
 ```sh