## Context

code-server is a VS Code instance running in a browser. The platform needs to spawn it as a Docker container with proper mounts, auth, and routing. This builds on the tool registry (FN-003) and deployment config (FN-006).

Current state:
- code-server manifest exists in apps/api/app/tools/manifests/code-server.yml
- ToolInstance model exists with status field
- No spawn orchestration logic
- No frontend UI for spawning

## Goals / Non-Goals

**Goals:**
- Spawn code-server containers via Docker Compose
- Mount user workspace, configs, secrets, and SSH keys
- Route via Traefik subdomain
- Track container status (creating, running, stopped, error)
- Provide spawn UI in frontend

**Non-Goals:**
- Support for other IDEs (deferred post-MVP)
- Container resource limits (CPU/memory) - basic only
- Automatic workspace backup
- Multi-instance load balancing

## Decisions

**1. Docker Compose API for container management**
- Rationale: Higher-level than Docker SDK, handles networking and volumes declaratively
- Alternative: Docker SDK directly - more control but more complex

**2. code-server runs with platform auth proxy**
- Rationale: Don't manage separate code-server passwords. Traefik middleware handles auth.
- Implementation: Traefik forwardAuth to platform API for session validation

**3. Workspace mounted from host directory**
- Rationale: Persistent storage between restarts. Easy backup.
- Path: `/data/workspaces/{user_slug}/{project_slug}`

**4. SSH keys mounted as read-only volume**
- Rationale: code-server needs Git access but shouldn't modify keys
- Mount: `/home/coder/.ssh/` with 0400 permissions

**5. Spawn is synchronous (blocking) API**
- Rationale: Simpler UX. Container creation is fast (< 5s).
- Alternative: Async with polling - more complex, unnecessary for MVP

## Risks / Trade-offs

**[Risk] Docker socket exposure is a security risk**
→ Mitigation: Run API with limited Docker access. Consider Docker socket proxy in production.

**[Risk] Container failures leave dangling resources**
→ Mitigation: Implement cleanup on error. Periodic garbage collection of orphaned containers.

**[Risk] code-server auth bypass**
→ Mitigation: Disable code-server auth (PASSWORD: ""). Rely entirely on Traefik forwardAuth.

## Migration Plan

No migration. New feature.

## Open Questions

1. Should we pre-pull Docker images or let Compose handle it?
2. Do we need container health checks before marking as "running"?
3. Should spawned containers auto-stop after inactivity?