# 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