Coder Tasks, Workspaces und OpenCode

Coder ist leichter zu verstehen, wenn man aufhört, es nur als Remote-IDE-Plattform zu betrachten. Im Kern liefert Coder reproduzierbare Entwicklungsumgebungen auf Abruf. Ein Nutzer klickt auf einen Button oder führt einen CLI-Befehl aus, und Coder stellt einen Workspace aus einem vordefinierten Template bereit. Dieser Workspace kann in einem Docker-Container, einem Kubernetes-Cluster, einer Cloud-VM oder einem anderen Infrastrukturziel laufen. Der Entwickler verbindet sich mit Tools wie VS Code, JetBrains IDEs, einem Terminal oder einem Browser-Editor.

Coder Tasks bauen auf derselben Grundlage auf, nutzen sie aber für KI-Programmieragenten. Anstatt einen Workspace für einen menschlichen Entwickler zu erstellen, erzeugt ein Task einen isolierten, kurzlebigen Workspace, in dem ein autonomer Agent läuft. Dieser Unterschied matters. Coder Tasks sind keine separate Ausführungsplattform. Sie sind Standard-Coder-Workspaces mit einer auf KI-Agenten ausgerichteten Oberfläche.

Das grundlegende Coder-Modell

Für Coder braucht man drei Konzepte: Workspaces, Templates und Provisioner.

Ein Workspace ist eine isolierte Entwicklungsumgebung. Das ist die Computerentität, mit der der Entwickler oder KI-Agent interagiert. Ein Template definiert, wie dieser Workspace aufgebaut wird. Coder-Templates sind in Terraform geschrieben, was bedeutet, dass sie lokale Container, Kubernetes-Pods, Cloud-VMs, persistente Volumes, Agenten, freigegebene Anwendungen, Metadaten und nutzerkonfigurierbare Parameter beschreiben können.

Ein Provisioner ist der Prozess, der den Terraform-Code ausführt. Dieses Detail ist wichtiger, als es wirkt. Die Infrastrukturanbieter, die Sie in Ihren Templates angeben, laufen dort, wo der Provisioner läuft, nicht im neu erstellten Workspace.

Coder server -> Provisioner runs Terraform -> Docker, Kubernetes, or cloud provider creates workspace

Wenn Ihr Template den Docker-Provider nutzt, muss Docker-Zugriff auf der Maschine vorhanden sein, auf der der Provisioner läuft. Wenn der Provisioner selbst in einem Container läuft, benötigt dieser Container direkten Zugriff auf den Docker-Socket des Hosts, einen entfernten Docker-Host oder welche Docker-Verbindung Sie auch konfiguriert haben.

Templates sind Terraform mit Coder-Datenquellen

Ein minimales Template deklariert normalerweise den Coder-Provider, einen Infrastrukturanbieter, Workspace-Datenquellen, einen Coder-Agenten und die Ressourcen, die den Workspace bilden.

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

provider "docker" {}

data "coder_provisioner" "me" {}
data "coder_workspace" "me" {}
data "coder_workspace_owner" "me" {}

resource "coder_agent" "main" {
  arch = data.coder_provisioner.me.arch
  os   = "linux"
}

Der Coder-Agent ermöglicht es dem Coder-Server, sich in den Workspace zu verbinden, laufende Web-Apps zugänglich zu machen, Startskripte auszuführen und Status zu melden. Der Infrastrukturanbieter erstellt die Umgebung. Bei Docker bedeutet das Container und Volumes. Bei Kubernetes Pods und Persistent Volume Claims. Bei Cloud-Anbietern VMs und persistente Festplatten.

Terraform-Variablen vs. Coder-Parameter

Eine der leichtesten Stellen, um verwirrt zu werden, ist der Unterschied zwischen Terraform-Variablen und Coder-Parametern.

Terraform-Variablen werden vom Template-Administrator gesetzt, wenn das Template auf den Server gepusht wird. Sie sind nützlich für Infrastruktur-Konfiguration und um statische Werte durchzusetzen, die Nutzer nicht wählen sollten. Coder-Parameter werden dem Nutzer angezeigt, wenn er einen Workspace oder Task erstellt. Sie lassen Nutzer Dinge wie ein Container-Image, eine geografische Region, CPU-Größe, ein LLM-Modell oder ein Arbeitsverzeichnis wählen.

Dieses Beispiel zeigt beide nebeneinander:

variable "anthropic_api_key" {
  type      = string
  sensitive = true
}

data "coder_parameter" "container_image" {
  name         = "container_image"
  display_name = "Container Image"
  type         = "string"
  default      = "ubuntu:22.04"
  mutable      = false
}

Der coder_parameter-Block ist eine Datenquelle. Während der Workspace-Erstellung ruft er den gewählten Wert aus der Coder-UI ab.

Hier ist ein Sicherheitsdetail, das man kennen sollte. Das Markieren einer Variablen als sensitive = true verhindert, dass Terraform- und Coder-Logs den Wert ausgeben. Es schützt den Wert aber nicht, sobald er in einem laufenden Workspace ist. Wenn Sie ein Geheimnis als einfache Umgebungsvariable in einen Container injizieren, kann jeder mit Shell-Zugriff auf diesen Container es lesen.

Die zwei Phasen der Template-Ausführung

Coder-Templates verhalten sich beim Template-Import anders als bei der Workspace-Erstellung. Bei coder templates push parst Coder den Terraform-Code, extrahiert definierte Parameter, baut das UI-Formular, fragt nach Terraform-Variablen-Werten und erkennt, ob das Template KI-Tasks unterstützt.

Bei der Workspace-Erstellung zeigt Coder dem Nutzer das Formular, speichert die gewählten Parameterwerte, führt terraform apply aus und lässt die data "coder_parameter"-Blöcke die Werte während der Ausführung abrufen. Diese Aufteilung ist der Grund, warum Coder-Parameter anfangs seltsam wirken können. Sie sind keine normalen Terraform-Variablen. Sie sind Coder-verwaltete Werte, die Terraform nur während der Apply-Phase liest.

Ephemere Parameter fügen eine strenge Regel hinzu. Wenn Sie ephemeral = true deklarieren, muss dieser Parameter auch als mutable markiert sein und einen Standardwert haben.

data "coder_parameter" "api_key" {
  name      = "api_key"
  type      = "string"
  mutable   = true
  ephemeral = true
  default   = ""
}

Ephemere Parameter sind nützlich, wenn Sie einen sensiblen oder temporären Wert zur Erstellungszeit wollen, ohne ihn in den langfristigen Metadaten des Workspaces zu speichern.

Was Coder Tasks hinzufügen

Coder Tasks bieten eine vereinfachte Oberfläche, um KI-Programmieragenten in isolierten Workspaces laufen zu lassen. Ein Nutzer erstellt einen Task mit einem Prompt in natürlicher Sprache. Coder speichert den Prompt. Terraform stellt den Workspace bereit. Das Template ruft den gespeicherten Prompt ab und leitet ihn an die Agenten-Integration im Workspace weiter.

Benutzer reicht Task-Prompt ein
        |
        v
Coder speichert Prompt
        |
        v
Terraform stellt Workspace bereit
        |
        v
Agent erhält Prompt und läuft im Workspace

Jeder Task bekommt seinen eigenen Workspace. Das gibt dem KI-Agenten ein isoliertes Dateisystem, saubere Abhängigkeiten, Zugang zu Tools und eine Laufzeitumgebung. Der Workspace braucht normalerweise keine GPUs, weil der Agent über das Netzwerk mit externen LLM-APIs spricht. Ein Coder-Template wird taskfähig, wenn es eine coder_ai_task-Ressource definiert.

resource "coder_ai_task" "task" {
  app_id = module.opencode.task_app_id
}

Der gespeicherte Task-Prompt kann über die Datenquelle data "coder_task" abgerufen werden.

data "coder_task" "me" {}

module "opencode" {
  ai_prompt = data.coder_task.me.prompt
}

Aus Sicht des Endnutzers kann ein Task so einfach sein wie dieser Befehl:

coder tasks create \
  --template my-template \
  --parameter container_image="python:3.12" \
  "Refactor the authentication module"

Der wesentliche Teil ist, dass der Task-Prompt zur Infrastruktur-Eingabe wird. Der Workspace wird um den Job herum erstellt, den der Agent ausführen soll.

Wo OpenCode ins Spiel kommt

Das OpenCode-Coder-Modul integriert OpenCode in einen Coder-Workspace. Es kann OpenCode als interaktive App zugänglich machen, im Hintergrund-Task-Modus laufen, Prompts weiterleiten und Authentifizierung oder Modelleinstellungen konfigurieren.

Eine einfache Modulkonfiguration sieht so aus:

module "opencode" {
  source   = "registry.coder.com/coder-labs/opencode/coder"
  version  = "0.1.1"
  agent_id = coder_agent.main.id
  workdir  = "/home/coder/project"
}

Für Task-Nutzung verbindet es sich mit data.coder_task.me.prompt und der coder_ai_task-Ressource.

data "coder_task" "me" {}

resource "coder_ai_task" "task" {
  app_id = module.opencode.task_app_id
}

module "opencode" {
  source           = "registry.coder.com/coder-labs/opencode/coder"
  version          = "0.1.1"
  agent_id         = coder_agent.main.id
  workdir          = "/home/coder/project"
  ai_prompt        = data.coder_task.me.prompt
  auth_json        = data.coder_parameter.opencode_auth_json.value
  config_json      = data.coder_parameter.opencode_config_json.value
  opencode_version = "latest"
}

Das Modul unterstützt auch einen CLI-Modus, wenn Sie OpenCode im Workspace-Terminal wollen, ohne Web-UI oder Task-Reporting.

module "opencode" {
  source       = "registry.coder.com/coder-labs/opencode/coder"
  version      = "0.1.1"
  agent_id     = coder_agent.main.id
  workdir      = "/home/coder"
  report_tasks = false
  cli_app      = true
}

Das Fazit: Coder stellt den Workspace bereit und verwaltet seinen Lebenszyklus, während OpenCode die Agenten-Erfahrung im Workspace liefert.

Docker-Provider-Stolperfallen

Viele lokale Coder-Setups nutzen Docker, daher wird der Docker-Terraform-Provider ein großer Teil der Template-Logik. Standardmäßig spricht dieser Provider mit dem lokalen Unix-Socket.

provider "docker" {
  host = "unix:///var/run/docker.sock"
}

Er kann auch so konfiguriert werden, dass er sich über SSH mit einem entfernten Host verbindet.

provider "docker" {
  host     = "ssh://user@remote-host:22"
  ssh_opts = ["-o", "StrictHostKeyChecking=no"]
}

Das kritische Detail ist, dass SSH-Schlüssel und Docker-Zugriff dort existieren müssen, wo der Provisioner läuft. Wenn der Provisioner in einem Container läuft, reicht es nicht, den SSH-Schlüssel auf dem Laptop zu mounten. Der Provisioner-Container braucht gemounteten Zugriff darauf.

Docker-Socket-Berechtigungen sind ein weiteres häufiges Problem. Wenn Coder in Docker in einer Sandbox läuft, aber über den Docker-Socket des Hosts Geschwister-Container erstellen muss, braucht der Coder-Container Zugriff auf /var/run/docker.sock mit den korrekten Gruppenberechtigungen.

services:
  coder:
    image: ghcr.io/coder/coder:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    group_add:
      - "998"

Die Gruppen-ID muss mit der Docker-Gruppe auf dem Host übereinstimmen.

Netzwerk kann einen auch überraschen. Wenn ein Workspace-Container den Coder-Server erreichen muss, der an localhost auf dem Host gebunden ist, verweist localhost aus dem Container auf den Container selbst. Ein üblicher Fix ist host.docker.internal mit einem manuellen Host-Gateway-Mapping.

Basis-Images und Workspace-Lebenszyklus

Coder-Basis-Images existieren aus einem Grund. Sie enthalten einen vorkonfigurierten coder-Nutzer, das erwartete Home-Verzeichnis-Verhalten, Agenten-Abhängigkeiten, Skeleton-Dateien und gängige Entwicklungstools.

Ein einfaches Image wie ubuntu:latest kann funktionieren, bedeutet aber, dass Sie mehr Setup selbst übernehmen. Sie müssen den Nutzer erstellen, Tools installieren, das Home-Verzeichnis konfigurieren und sicherstellen, dass der Coder-Agent korrekt startet.

Der Workspace-Lebenszyklus matters auch. Einige Ressourcen sollten nur existieren, wenn der Workspace gestartet ist. Coder stellt eine start_count-Metrik zur Verfügung, die Templates mit dem Terraform-Meta-Argument count paaren.

resource "docker_container" "workspace" {
  count = data.coder_workspace.me.start_count
}

module "opencode" {
  count = data.coder_workspace.me.start_count
}

Persistente Volumes sind eine separate Frage. Wenn das Home-Verzeichnis eines Nutzers oder Workspace-Daten Stopps und Rebuilds überstehen sollen, schützen Sie das Volume.

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

  lifecycle {
    ignore_changes = all
  }
}

Zusammenfassung

Coder ist eine Control Plane zur Verwaltung reproduzierbarer Entwicklungsumgebungen. Terraform ist die Sprache, die diese Umgebungen beschreibt. Provisioner führen den Terraform-Code aus. Workspaces sind die resultierenden VMs, Container oder Pods. Tasks sind spezialisierte Workspaces, die um KI-Agenten-Prompts erstellt werden.

OpenCode fügt sich als Tool in den Workspace ein. Es ist nicht die Infrastrukturschicht selbst; es ist die Agentenschicht obendrauf. Sobald diese Trennung klar ist, fallen die verwirrenden Teile leichter.

Wenn eine Docker-Ressource fehlschlägt, schauen Sie auf Provisioner und Docker-Host. Wenn ein Nutzer-Parameter fehlt, verfolgen Sie den Coder-Parameter-Fluss. Wenn ein Task-Prompt den Agenten nicht erreicht, prüfen Sie data "coder_task" und die Modul-Verkabelung. Wenn ein Geheimnis in einem laufenden Container auftaucht, erinnern Sie sich, dass Terraforms Sensitivität nicht Laufzeit-Geheimhaltung bedeutet.

Coder Tasks sind mächtig, weil sie reproduzierbare Infrastruktur mit isolierter Agenten-Ausführung kombinieren. Der Preis dafür ist, dass man beide Hälften verstehen muss: das Coder/Terraform-Bereitstellungsmodell und die Agenten-Integration im Workspace.

Referenzen

• Coder Docs
• Coder Tasks
• Coder Templates
• OpenCode Module
• OpenCode Config
• Docker Provider
• Coder Registry