zlh-grind/Session_Summaries/2026-03-15_IDE-Proxy-Implementation.md

2026-03-15 – Dev IDE proxy implementation

Summary

DNS/Traefik routing experiment for dev IDEs was abandoned and replaced with a secure API proxy model. IDE access is now fully implemented in the API with a short-lived token system.

---

What Was Removed from API

Deleted files:

• src/services/devRouting.js
• src/services/devDePublisher.js

Removed dev-routing hooks from:

• src/api/provisionAgent.js
• src/routes/containers.js

src/services/proxyClient.js was intentionally not deleted — it is still used by the game edge publish path. Removing it would break game routing.

Dev provisioning now only performs: container creation, agent configuration, runtime installation, optional enable_code_server flag. No DNS or Traefik routing is created for dev containers.

---

What Was Implemented

Dev IDE Proxy (src/routes/devProxy.js)

Mounted in src/app.js.

Routes:

GET /api/dev/:id/ide
GET /api/dev/:id/ide/*

Behavior:

• validates authentication
• verifies container ownership
• requires ctype === "dev"
• requires container IP
• proxies to http://<container-ip>:6000
• rewrites /api/dev/:id/ide/... → /...
• WebSocket support via http-proxy-middleware (ws: true)
• server.on("upgrade") handler wired for WS proxy

Dependency added: http-proxy-middleware

---

IDE Token System (POST /api/dev/:id/ide-token)

Problem: opening /api/dev/:id/ide in a new tab loses Authorization: Bearer header.

Solution: short-lived signed IDE tokens.

Response:

{
  "token": "<signed-token>",
  "url": "/api/dev/6062/ide?token=<signed-token>",
  "expiresIn": 300
}

Token details:

• signed by API
• payload: sub, vmid, type: "dev-ide"
• default TTL: 300 seconds
• env overrides: API_AUTH_IDE_TTL_SECONDS, API_AUTH_IDE_SECRET

Proxy accepts either Authorization: Bearer or ?token=<ide-token>. WebSocket upgrades validate the same token.

---

Server Status Endpoint (GET /api/servers/:id/status)

File: src/routes/serverStatus.js

Mounted in src/app.js.

Behavior:

• requires authentication
• verifies container ownership
• loads Redis key agent:<vmid>
• returns cached agent status fields

Fields include: state, runtimeInstalled, devProvisioned, devReadyAt, codeServerInstalled, codeServerRunning, workspaceRoot, serverRoot, lastCrashClassification.

Source: src/utils/agentPoller.js polls agent /status and caches to Redis.

---

Frontend Flow

1. Portal calls POST /api/dev/:id/ide-token
2. API returns { url, token, expiresIn }
3. Portal opens new tab at returned URL
4. API validates token and proxies to container

---

What Was NOT Changed

• game provisioning flow
• game edge publish path
• game mod APIs
• game telemetry polling
• agent poller logic
• game file routes
• console transport

Game infrastructure remains exactly as before.

---

Next Session — Agent Change Required

code-server currently launches with --auth password.

Must be changed to:

code-server \
  --bind-addr 0.0.0.0:6000 \
  --auth none \
  --base-path /api/dev/<vmid>/ide \
  /home/dev/workspace

Reasons:

• removes password prompt (API token is now sole auth)
• --base-path required for correct asset loading through proxy path

This is an agent-side change to the code-server addon launch script.