diff --git a/DEV_CONTAINER_SPEC.md b/DEV_CONTAINER_SPEC.md
new file mode 100644
index 0000000..441ec9e
--- /dev/null
+++ b/DEV_CONTAINER_SPEC.md
@@ -0,0 +1,310 @@
+# ZeroLagHub Developer Container Architecture
+
+This document describes how developer containers are provisioned and managed by the zlh-agent.
+
+It is intended for engineers and AI assistants working on the ZeroLagHub platform.
+
+---
+
+## Overview
+
+Developer containers provide ephemeral development environments for building and testing software.
+
+They support multiple runtimes and optional development tooling.
+
+Provisioning is performed by the zlh-agent using an artifact-driven runtime system.
+
+---
+
+## Dev Container Lifecycle
+
+Provisioning flow:
+
+1. Portal sends dev container request
+2. API builds agent provisioning payload
+3. Agent validates request
+4. Agent creates dev environment
+5. Agent installs runtime from artifact server
+6. Agent optionally installs addons
+7. Agent marks container ready
+
+High-level architecture:
+
+```
+Portal
+  ↓
+zlh-api
+  ↓
+zlh-agent
+  ↓
+Artifact Server
+```
+
+---
+
+## Dev Provisioning Payload
+
+The API sends configuration to the agent via:
+
+```
+POST http://<agent-ip>:18888/config
+```
+
+Dev payload example:
+
+```json
+{
+  "container_type": "dev",
+  "runtime": "node",
+  "version": "22",
+  "memory_mb": 2048,
+  "enable_code_server": true
+}
+```
+
+Fields:
+
+| Field | Description |
+|-------|-------------|
+| `container_type` | must be `"dev"` |
+| `runtime` | runtime id |
+| `version` | runtime version |
+| `memory_mb` | container memory |
+| `enable_code_server` | optional addon |
+
+---
+
+## Runtime Catalog
+
+All dev runtimes are defined by the artifact server catalog.
+
+Catalog location:
+
+```
+http://<artifact-server>/devcontainer/_catalog.json
+```
+
+Example catalog:
+
+```json
+{
+  "runtimes": [
+    { "id": "go",     "versions": ["1.22", "1.25"] },
+    { "id": "java",   "versions": ["17", "19", "21"] },
+    { "id": "node",   "versions": ["20", "22", "24"] },
+    { "id": "python", "versions": ["3.10", "3.11", "3.12", "3.13"] },
+    { "id": "dotnet", "versions": ["8.0", "10.0"] }
+  ]
+}
+```
+
+The agent validates runtime/version against this catalog before installation.
+
+Invalid combinations cause provisioning to fail.
+
+---
+
+## Artifact Server Layout
+
+Dev runtime artifacts:
+
+```
+devcontainer/
+  _catalog.json
+  go/
+  node/
+  python/
+  java/
+  dotnet/
+```
+
+Example runtime artifact:
+
+```
+devcontainer/node/22/node-22.tar.xz
+```
+
+Addon artifacts:
+
+```
+addons/
+  code-server/
+```
+
+Artifacts are downloaded at provisioning time.
+
+Nothing is preinstalled inside containers.
+
+---
+
+## Runtime Installation
+
+Runtime install 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.
+
+---
+
+## Dev Environment
+
+Every dev container has a dedicated development user.
+
+```
+user:      dev
+home:      /home/dev
+workspace: /home/dev/workspace
+ownership: dev:dev
+```
+
+The workspace is where developers store source code.
+
+---
+
+## Console Behavior
+
+Dev console sessions run as the dev user.
+
+Shell properties:
+
+```
+user: dev
+cwd:  /home/dev/workspace
+HOME=/home/dev
+TERM=xterm-256color
+```
+
+This prevents root access in development environments.
+
+---
+
+## File System Access
+
+Dev containers expose a file browser rooted at:
+
+```
+/home/dev/workspace
+```
+
+Portal displays this as `workspace/`.
+
+Uploads and file operations are restricted to this directory.
+
+Dev containers have unrestricted read/write access inside `/home/dev/workspace`. No allowlist. The only hard rule is the root sandbox — nothing can escape the workspace.
+
+---
+
+## Dotnet Runtime
+
+Dotnet uses the official installer script.
+
+Installer source:
+
+```
+http://artifact-server/devcontainer/dotnet/dotnet-install.sh
+```
+
+Installation:
+
+```bash
+./dotnet-install.sh --channel 8.0
+```
+
+Installed to:
+
+```
+/opt/zlh/runtimes/dotnet/8.0
+```
+
+Supported channels: `8.0`, `10.0`
+
+---
+
+## Code Server Addon
+
+Code-server provides a browser IDE.
+
+Enabled via provisioning flag:
+
+```json
+"enable_code_server": true
+```
+
+Artifact location:
+
+```
+http://artifact-server/addons/code-server/code-server.zip
+```
+
+Installed to:
+
+```
+/opt/zlh/services/code-server
+```
+
+Launched as:
+
+```bash
+code-server --bind-addr 0.0.0.0:8080 /home/dev/workspace
+```
+
+**Current blocker:** artifact currently contains source repository, not a compiled release. Artifact server must provide a runnable release archive with the following layout:
+
+```
+code-server/
+  bin/code-server
+  lib/
+  node_modules/
+```
+
+---
+
+## Security Model
+
+Dev containers are isolated LXC containers.
+
+Security controls:
+
+- Runtime installs limited to `/opt/zlh`
+- File browser limited to workspace
+- Shell runs as non-root `dev` user
+- Artifacts fetched only from trusted artifact server
+
+---
+
+## 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
+
+---
+
+## Future Enhancements
+
+- Runtime checksum validation
+- Runtime upgrades / removal
+- Artifact metadata support
+- Service port auto-detection
+- Dev service routing / proxy exposure
+- IDE launch integration from portal
+
+---
+
+## Summary
+
+Developer containers in ZeroLagHub provide isolated development environments with multiple runtime support, artifact-driven installs, optional browser IDE, and consistent reproducible provisioning.