Coder Architecture & Implementation Guide — Self-Hosted CDE & AI Agent Sandboxes

💡 1. Executive Summary: What is Coder?

Core Philosophy

Coder is a self-hosted developer platform that shifts development off local physical laptops onto isolated, disposable workspaces running on your private infrastructure (Docker, Colima, Kubernetes, or Cloud VMs). Rather than paying GitHub Codespaces or Gitpod $50/month per seat, Coder lets you provision full-fidelity Linux development environments on your own Apple Silicon M4 hardware with zero egress costs.

🛡️ Coder Agents & AI Isolation

Runs autonomous agents (Claude Code, Hermes, Codex, OpenCode) in sandboxed workspaces. The agent loop runs in the control plane—zero API keys exist inside the workspace container.

📐 Terraform-Defined Workspaces

Templates are written in standard Terraform. CPU, RAM, disk, network access, and pre-installed packages are version-controlled in Git and identical for every run.

🌐 Universal Access & WireGuard

Connect seamlessly via browser (code-server / VS Code Web), local desktop VS Code, JetBrains, or direct SSH over an encrypted peer-to-peer WireGuard tunnel (tailnet).

⏱️ Auto-Stop & Resource Governance

Workspaces automatically shut down when idle, preserving CPU/RAM on your Mac Mini and instantly spinning back up with persistent volume state intact.

🏗️ 2. Architectural Blueprint for Viral's Rig

Host: M4 Mac Mini (Nashua NH)

┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                 CONTROL PLANE (Host / Coder Daemon)                             │
├─────────────────────────────────────────────────────────────────────────────────────────────────┤
│  [Viral (iPad / Laptop / Web)]      [Hermes Multi-Agent Fleet]      [Claude Code / Codex CLI]   │
│                 │                                │                              │               │
│                 ▼                                ▼                              ▼               │
│  ┌───────────────────────────────────────────────────────────────────────────────────────────┐  │
│  │                              coder server (Port 3000 / Zero Trust)                        │  │
│  │  - Auth & RBAC (GitHub OAuth / Local Admin)      - WireGuard Encrypted Tailnet Hub        │  │
│  │  - Terraform Provisioner Daemon (provisionerd)   - Control Plane AI Proxy (Stateless)     │  │
│  └──────────────────────────────────────────┬────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────┼───────────────────────────────────────────────────┘
                                              │ (DOCKER_HOST unix://~/.colima/default/docker.sock)
                                              ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│                               ISOLATED WORKSPACES RUNTIME (Colima Docker)                       │
├─────────────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                                 │
│  ┌─────────────────────────────┐   ┌─────────────────────────────┐   ┌───────────────────────┐  │
│  │ WORKSPACE 1: ToFrom Core    │   │ WORKSPACE 2: Hermes Agent   │   │ WORKSPACE 3: Sandbox  │  │
│  │ - Ubuntu 24.04 ARM64        │   │ - Python 3.11 / venv        │   │ - Disposable Temp Env │  │
│  │ - PAS Spooler Interceptor   │   │ - Safe Bash Execution       │   │ - Zero Host Access    │  │
│  │ - code-server (Browser IDE) │   │ - Isolated Git Worktree     │   │ - Auto-stop after 30m │  │
│  │ - Persistent Volume Mount   │   │ - Resource Capped (4GB RAM) │   │ - Auto-destroy on exit│  │
│  └─────────────────────────────┘   └─────────────────────────────┘   └───────────────────────┘  │
│                                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────────────────────┘

🚀 3. Step-by-Step Implementation Guide

10-Minute Setup

1

Install Coder Server Binary on macOS

Install the standalone Coder CLI via Homebrew or official shell script.

# Install via Homebrew
brew install coder/coder/coder

# Or via official curl installer
curl -L https://coder.com/install.sh | sh

# Verify installation
coder --version

2

Connect Coder to Existing Colima Docker Runtime

Viral's Mac Mini is already running Colima Docker (context: colima). Point Coder to Colima's socket:

# Export Colima Docker socket for Coder
export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"

# Verify Docker socket is responding
docker info

3

Launch Coder Server (Single Binary)

Start the server. On initial run, Coder uses embedded SQLite and generates a local access URL:

# Start Coder server locally
coder server --http-address 127.0.0.1:3000

# Open browser at http://localhost:3000 and create initial admin credentials

4

Create a Docker Workspace Template (Terraform)

Create a reusable template for isolated development environments:

# Initialize built-in Docker template
coder templates init

# Select 'docker' from list, then push template
cd docker
coder template create tofrom-dev-env

5

Expose via Cloudflare Tunnel (Optional Remote Access)

Route traffic securely through Cloudflare Access to reach Coder on your iPad at coder.vdesai.com:

cloudflared tunnel route dns vdesai-tunnel coder.vdesai.com

🎯 4. High-Leverage Use Cases Across Viral's Ventures

Immediate ROI

💼 1. ToFrom PAS Sandbox

Test custom AFP/IPDS print spoolers, Guidewire XML feeds, and PDF statutory generation engines in sterile containers without polluting host macOS with print drivers or Java dependencies.

🤖 2. Safe AI Agent Sandbox

When Hermes or an autonomous coding subagent clones untrusted repos or runs complex package installations, execute inside an ephemeral Coder workspace. Total isolation from host credentials.

📱 3. iPad Remote Dev Station

Connect to coder.vdesai.com from an iPad Pro. Access full desktop VS Code in the browser with terminal, zsh, Git, and extensions running natively on the M4 Mac Mini in Nashua.

🎬 4. VibeCraft Render Worker

Spin up dedicated multi-core ffmpeg rendering containers for vertical video mastering without locking up host CPU threads.

📄 5. Production Terraform Template (`main.tf`)

Drop-in Terraform blueprint configured for Apple Silicon Colima Docker with Python 3.11, Node.js, and web-based VS Code (code-server):

terraform {
  required_providers {
    coder = {
      source  = "coder/coder"
      version = "~> 2.11"
    }
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 3.0"
    }
  }
}

provider "docker" {
  host = "unix://${pathexpand("~")}/.colima/default/docker.sock"
}

data "coder_workspace" "me" {}

resource "coder_agent" "main" {
  arch           = "arm64"
  os             = "linux"
  startup_script = <<-EOT
    set -e
    # Start code-server IDE in the background
    code-server --auth none --port 13337 &
  EOT
}

resource "coder_app" "code_server" {
  agent_id     = coder_agent.main.id
  slug         = "code-server"
  display_name = "VS Code Web"
  url          = "http://localhost:13337/"
  icon         = "/icon/code.svg"
  subdomain    = false
  share        = "owner"
}

resource "docker_volume" "home_volume" {
  name = "coder-${data.coder_workspace.me.id}-home"
}

resource "docker_container" "workspace" {
  count = data.coder_workspace.me.start_count
  image = "codercom/enterprise-base:ubuntu"
  name  = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}"
  hostname = data.coder_workspace.me.name

  entrypoint = ["sh", "-c", coder_agent.main.init_script]
  env = [
    "CODER_AGENT_TOKEN=${coder_agent.main.token}",
  ]
  volumes {
    container_path = "/home/coder"
    volume_name    = docker_volume.home_volume.name
    read_only      = false
  }
}