# 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.