diff --git a/docs/reference/DEV_CONTAINER_SPEC.md b/docs/reference/DEV_CONTAINER_SPEC.md
new file mode 100644
index 0000000..db3b7c2
--- /dev/null
+++ b/docs/reference/DEV_CONTAINER_SPEC.md
@@ -0,0 +1,217 @@
+# ZeroLagHub Developer Container Architecture
+
+This document describes how developer containers are provisioned and accessed.
+
+---
+
+## Overview
+
+Developer containers provide ephemeral development environments.
+
+Provisioning is performed by the **zlh-agent** using runtime artifacts.
+
+Supported runtimes:
+
+- node
+- python
+- go
+- java
+- dotnet
+
+---
+
+## Dev Container Lifecycle
+
+Provisioning flow:
+
+1. Portal sends dev request
+2. API builds provisioning payload
+3. Agent installs runtime
+4. Agent installs addons
+5. Agent marks container ready
+
+Architecture:
+
+```
+Portal
+  ↓
+zpack-api
+  ↓
+zlh-agent
+  ↓
+Artifact Server
+```
+
+---
+
+## Dev Environment
+
+```
+user:      dev
+home:      /home/dev
+workspace: /home/dev/workspace
+```
+
+Console sessions run as the dev user.
+
+---
+
+## Runtime Installation
+
+Runtime path:
+
+```
+/opt/zlh/runtimes/<runtime>/<version>
+```
+
+Examples:
+
+```
+/opt/zlh/runtimes/node/22
+/opt/zlh/runtimes/python/3.12
+/opt/zlh/runtimes/go/1.25
+/opt/zlh/runtimes/dotnet/8.0
+```
+
+Install guards prevent reinstall — if the directory already exists, installation is skipped.
+
+---
+
+## Code Server Addon
+
+Code-server provides browser IDE access.
+
+Install location:
+
+```
+/opt/zlh/services/code-server
+```
+
+Port: `6000`
+
+Observed process:
+
+```bash
+/opt/zlh/services/code-server/lib/node /opt/zlh/services/code-server \
+  --bind-addr 0.0.0.0:6000 \
+  --auth password \
+  /home/dev/workspace
+```
+
+---
+
+## Dev IDE Access Model
+
+The previous model using Cloudflare DNS, Traefik, and per-container subdomains has been removed.
+
+---
+
+### Browser IDE Access (Primary)
+
+IDE is accessed through the API proxy.
+
+```
+Browser
+  ↓
+Portal
+  ↓
+API
+  ↓
+container:6000
+```
+
+URL format: `/dev/<vmid>/ide`
+
+code-server launch flags required:
+
+```
+--base-path /dev/<vmid>/ide --auth none
+```
+
+Portal JWT authentication gates access. The API verifies container ownership before proxying.
+
+WebSocket support is mandatory — code-server is heavily WebSocket-based:
+
+- `http-proxy-middleware` with `ws: true`
+- `server.on('upgrade', proxy.upgrade)` must be wired up
+
+---
+
+### Local Development Access (Advanced Users)
+
+Advanced users may connect via **Headscale/Tailscale**.
+
+Benefits:
+
+- SSH
+- VS Code Remote
+- full local tooling
+
+Implementation:
+
+- dev container installs `tailscaled` as an addon
+- API generates Headscale auth key on provisioning
+- customer joins tailnet once, gets stable container IP
+
+Restrictions:
+
+- no exit nodes
+- `magic_dns: false`
+- no DNS takeover on customer machine
+
+Headscale server: `zlh-ctl` (status to be confirmed)
+
+---
+
+## Security Model
+
+- Portal authentication controls IDE access
+- API verifies container ownership before proxying
+- Containers are never exposed directly to the public internet
+- Shell runs as non-root `dev` user
+- File browser limited to workspace root
+
+---
+
+## File Browser
+
+Workspace root: `/home/dev/workspace`
+
+Portal displays this as `workspace/`.
+
+Uploads cannot escape this directory.
+
+---
+
+## Agent Status
+
+Status is polled by API via `/status`. Agent does not push state.
+
+Dev fields in `/status`:
+
+- `workspaceRoot`
+- `runtimeInstallPath`
+- `runtimeInstalled`
+- `codeServerInstalled`
+- `codeServerRunning`
+
+---
+
+## Design Principles
+
+1. No local runtime assumptions
+2. All runtimes are artifact-driven
+3. Runtime catalog is the source of truth
+4. Installs must be idempotent
+5. Containers must remain reproducible
+6. Dev services are never publicly exposed directly
+
+---
+
+## Future Enhancements
+
+- Runtime checksum validation
+- Runtime upgrades / removal
+- Artifact metadata support
+- Tailscale addon implementation
+- Headscale auth key portal UI