Tareas de Coder, Espacios de trabajo y OpenCode

Coder es más fácil de entender cuando dejas de pensar en él solo como una plataforma IDE remota. En su núcleo, Coder te da entornos de desarrollo reproducibles bajo demanda. Un usuario hace clic en un botón o ejecuta un comando CLI, y Coder aprovisiona un espacio de trabajo desde una plantilla predefinida. Ese espacio puede correr en un contenedor Docker, un clúster Kubernetes, una VM en la nube u otro objetivo de infraestructura. El desarrollador se conecta usando herramientas como VS Code, JetBrains IDEs, una terminal o un editor basado en navegador.

Las Tareas de Coder (Coder Tasks) se construyen sobre esa misma base, pero la repuropian para agentes de programación de IA. En vez de crear un espacio para que un desarrollador humano lo use de forma interactiva, una tarea crea un espacio aislado y efímero para que un agente autónomo corra dentro. Esa distinción importa. Las Tareas de Coder no son una plataforma de ejecución separada. Son espacios de trabajo de Coder estándar con una interfaz orientada a agentes de IA.

El Modelo Básico de Coder

Para entender Coder necesitas tres conceptos: espacios de trabajo (workspaces), plantillas (templates) y aprovisionadores (provisioners).

Un espacio de trabajo es un entorno de desarrollo aislado. Es la entidad con la que el desarrollador o el agente de IA interactúa. Una plantilla define cómo se construye ese espacio. Las plantillas de Coder se escriben en Terraform, lo que significa que pueden describir contenedores locales, pods de Kubernetes, VMs en la nube, volúmenes persistentes, agentes, aplicaciones expuestas, metadatos y parámetros configurables por el usuario.

Un aprovisionador es el proceso que ejecuta el código Terraform. Este detalle importa más de lo que parece. Los proveedores de infraestructura que especificas en tus plantillas corren donde el aprovisionador corre, no dentro del espacio recién creado.

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

Si tu plantilla usa el proveedor de Docker, el acceso a Docker debe estar disponible en la máquina que corre el aprovisionador. Si el aprovisionador está containerizado, ese contenedor necesita acceso directo al socket de Docker del host, a un host Docker remoto, o a la conexión Docker que hayas configurado.

Las Plantillas son Terraform con Fuentes de Datos de Coder

Una plantilla mínima normalmente declara el proveedor de Coder, un proveedor de infraestructura, fuentes de datos del espacio, un agente de Coder y los recursos que constituyen el espacio.

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"
}

El agente de Coder es lo que permite al servidor Coder conectarse al espacio, exponer aplicaciones web en ejecución, ejecutar scripts de inicio y reportar estado. El proveedor de infraestructura crea el entorno. Con Docker, eso significa contenedores y volúmenes. Con Kubernetes, pods y persistent volume claims. Con proveedores de nube, VMs y discos persistentes.

Variables de Terraform vs. Parámetros de Coder

Uno de los puntos más fáciles para confundirse es la diferencia entre variables de Terraform y parámetros de Coder.

Las variables de Terraform las establece el administrador de la plantilla cuando se envía al servidor. Son útiles para configuración a nivel de infraestructura y para imponer valores estáticos que los usuarios no deberían elegir. Los parámetros de Coder, por otro lado, se muestran al usuario cuando crea un espacio o una tarea. Permiten al usuario elegir cosas como una imagen de contenedor, una región geográfica, el tamaño de CPU, un modelo LLM o un directorio de trabajo personalizado.

Este ejemplo muestra ambos lado a lado:

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
}

El bloque coder_parameter es una fuente de datos. Durante la creación del espacio, obtiene el valor elegido por el usuario desde la interfaz de Coder.

Hay un detalle de seguridad que vale la pena conocer. Marcar una variable como sensitive = true evita que los logs de Terraform y Coder impriman el valor, pero no protege el valor una vez dentro de un espacio en ejecución. Si inyectas un secreto en un contenedor como variable de entorno simple, cualquiera con acceso shell a ese contenedor puede leerlo.

Las Dos Fases de Ejecución de la Plantilla

Las plantillas de Coder se comportan distinto durante la importación que durante la creación del espacio. Durante coder templates push, Coder analiza el código Terraform, extrae los parámetros definidos, construye el formulario de la interfaz, pide valores para las variables de Terraform y detecta si la plantilla soporta tareas de IA.

Durante la creación del espacio, Coder muestra ese formulario al usuario, almacena los valores de parámetros elegidos, ejecuta terraform apply y deja que los bloques data "coder_parameter" obtengan esos valores durante la ejecución. Esta división es por lo que los parámetros de Coder pueden parecer extraños al principio. No son variables normales de Terraform. Son valores gestionados por Coder que Terraform solo lee durante la fase apply.

Los parámetros efímeros añaden una regla estricta. Si declaras ephemeral = true, ese parámetro debe marcarse también como mutable y debe tener un valor por defecto.

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

Los parámetros efímeros son útiles cuando quieres un valor sensible o temporal suministrado al momento de la creación sin almacenarlo en los metadatos a largo plazo del espacio.

Lo que Aportan las Tareas de Coder

Las Tareas de Coder proporcionan una interfaz simplificada para correr agentes de programación de IA dentro de espacios aislados. Un usuario crea una tarea con un prompt en lenguaje natural. Coder almacena el prompt. Terraform aprovisiona el espacio. La plantilla obtiene el prompt almacenado y lo pasa a la integración del agente dentro del entorno.

Usuario envía prompt de la tarea
        |
        v
Coder almacena el prompt
        |
        v
Terraform aprovisiona el espacio
        |
        v
El agente recibe el prompt y corre en el espacio

Cada tarea obtiene su propio espacio. Eso le da al agente de IA un sistema de archivos aislado, un conjunto limpio de dependencias, acceso a herramientas y un entorno de ejecución. El espacio normalmente no necesita GPUs porque el agente habla con APIs LLM externas por la red. Una plantilla de Coder se vuelve capaz de tareas cuando define un recurso coder_ai_task.

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

El prompt de la tarea almacenado se puede obtener usando la fuente de datos data "coder_task".

data "coder_task" "me" {}

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

Desde la perspectiva del usuario final, iniciar una tarea puede ser tan simple como este comando:

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

La parte clave es que el prompt de la tarea se convierte en entrada de infraestructura. El espacio se crea alrededor del trabajo que el agente debe realizar.

Dónde Encaja OpenCode

El módulo OpenCode Coder integra OpenCode en un espacio de Coder. Puede exponer OpenCode como una aplicación interactiva, correrlo en modo tarea en segundo plano, pasar prompts y configurar autenticación o ajustes de modelo.

Una configuración simple del módulo se ve así:

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

Para uso con tareas, se conecta a data.coder_task.me.prompt y al recurso coder_ai_task.

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"
}

El módulo también soporta un modo solo CLI si quieres OpenCode en la terminal del espacio sin la interfaz web ni el reporte de tareas.

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
}

La conclusión: Coder proporciona el espacio y gestiona su ciclo de vida, mientras OpenCode proporciona la experiencia del agente dentro de ese espacio.

Problemas Comunes del Proveedor de Docker

Muchas configuraciones locales de Coder dependen de Docker, así que el proveedor Docker de Terraform se vuelve una parte grande de la lógica de la plantilla. Por defecto, este proveedor habla con el socket Unix local.

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

También se puede configurar para conectarse a un host remoto por SSH.

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

El detalle crítico es que las claves SSH y el acceso a Docker deben existir donde el aprovisionador corre. Si el aprovisionador corre en un contenedor, montar tu clave SSH en tu laptop no es suficiente. El contenedor del aprovisionador necesita acceso montado a ella.

Los permisos del socket de Docker son otro problema común. Si Coder corre en una sandbox de Docker pero necesita crear contenedores hermanos a través del socket de Docker del host, el contenedor de Coder necesita acceso a /var/run/docker.sock con los permisos de grupo correctos.

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

El ID de grupo debe coincidir con el grupo Docker en la máquina host.

La red también puede sorprender. Si un contenedor de espacio necesita alcanzar el servidor Coder que está bound a localhost en el host, resolver localhost desde dentro del contenedor apunta al contenedor mismo. Una solución común es usar host.docker.internal con un mapeo manual de host gateway.

Imágenes Base y Ciclo de Vida del Espacio

Las imágenes base que provee Coder existen por una razón. Incluyen un usuario coder preconfigurado, el comportamiento esperado del directorio home, dependencias del agente, archivos skeleton y herramientas de desarrollo comunes.

Usar una imagen plana como ubuntu:latest puede funcionar, pero significa que te haces cargo de más setup. Tienes que crear el usuario, instalar herramientas, configurar el directorio home y asegurar que el agente de Coder arranque correctamente.

El ciclo de vida del espacio también importa. Algunos recursos solo deberían existir cuando el espacio está iniciado. Coder expone una métrica start_count, que las plantillas asocian con el meta-argumento count de Terraform.

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

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

Los volúmenes persistentes son un asunto separado. Si quieres que el directorio home de un usuario o los datos del espacio sobrevivan paradas y reconstrucciones, protege el volumen.

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

  lifecycle {
    ignore_changes = all
  }
}

Poniéndolo Junto

Coder es un plano de control para gestionar entornos de desarrollo reproducibles. Terraform es el lenguaje que describe esos entornos. Los aprovisionadores ejecutan el código Terraform. Los espacios son las VMs, contenedores o pods resultantes. Las tareas son espacios especializados creados alrededor de prompts de agentes de IA.

OpenCode encaja en ese modelo como una herramienta que corre dentro del espacio. No es la capa de infraestructura misma; es la capa de agente encima. Una vez que esa separación es clara, las partes confusas se depuran más fácil.

Si un recurso de Docker falla, mira el aprovisionador y el host Docker. Si falta un parámetro de usuario, rastrea el flujo de parámetros de Coder. Si un prompt de tarea no llega al agente, revisa data "coder_task" y el cableado del módulo. Si un secreto aparece dentro de un contenedor en ejecución, recuerda que el concepto de sensibilidad de Terraform no equivale a secreto en tiempo de ejecución.

Las Tareas de Coder son potentes porque combinan infraestructura reproducible con ejecución aislada del agente. El coste de esa potencia es que necesitas entender ambas mitades: el modelo de aprovisionamiento de Coder/Terraform y la integración del agente corriendo dentro del espacio.

Referencias

• Documentación de Coder
• Tareas de Coder
• Plantillas de Coder
• Módulo OpenCode
• Configuración de OpenCode
• Proveedor de Docker
• Registro de Coder