Tasks Migration Guide

Migrating Task Templates for Coder version 2.28.0

> [!WARNING] > Starting June 2, 2026, Coder Tasks will move to a 12-month Extended Support Release (ESR) for Premium customers. > > Tasks will be removed from new Coder releases beginning with v2.37 (September 1, 2026) and will only be available via the ESR during the support period. > > We recommend transitioning to Coder Agents, the long-term replacement.

Prior to Coder version 2.28.0, the definition of a Coder task was different to the above. It required the following to be defined in the template:

A Coder parameter specifically named "AI Prompt",
A coder_workspace_app that runs the coder/agentapi binary,
A coder_ai_task resource in the template that sets sidebar_app.id. This was generally defined in Coder modules specific to AI Tasks.

Note that 2 and 3 were generally handled by the coder/agentapi Terraform module.

> [!IMPORTANT] > The pre-2.28.0 definition is no longer supported as of Coder 2.30.0. You must update your Tasks-enabled templates to use the new format described below.

You can view an example migration here. Alternatively, follow the steps below:

Upgrade Steps

Update the Coder Terraform provider to at least version 2.13.0:

terraform {
  required_providers {
    coder = {
      source = "coder/coder"
-      version = "x.y.z"
+      version = "&gt;= 2.13"
    }
  }
}

Define a coder_ai_task resource and coder_task data source in your template:

+data "coder_task" "me" {}
+resource "coder_ai_task" "task" {}

Update the version of the respective AI agent module (e.g. claude-code) to at least 4.0.0 and provide the prompt from data.coder_task.me.prompt instead of the "AI Prompt" parameter.

module "claude-code" {
  source              = "registry.coder.com/coder/claude-code/coder"
-  version             = "4.0.0"
+  version             = "4.0.0"
    ...
-  ai_prompt           = data.coder_parameter.ai_prompt.value
+  ai_prompt           = data.coder_task.me.prompt
}

Add the coder_ai_task resource and set app_id to the task_app_id output of the Claude module.

> [!NOTE] > Refer to the documentation for the specific module you are using for the exact name of the output.

resource "coder_ai_task" "task" {
+ app_id = module.claude-code.task_app_id
}

Coder Tasks format pre-2.28

Below is a minimal illustrative example of a Coder Tasks template pre-2.28.0. Note that this is NOT a full template.

terraform {
  required_providers {
    coder = {
      source = "coder/coder
    }
  }
}

data "coder_workspace" "me" {}

resource "coder_agent" "main" { ... }

# The prompt is passed in via the specifically named "AI Prompt" parameter.
data "coder_parameter" "ai_prompt" {
  name    = "AI Prompt"
  mutable = true
}

# This coder_app is the interface to the Coder Task.
# This is assumed to be a running instance of coder/agentapi
resource "coder_app" "ai_agent" {
  ...
}

# Assuming that the below script runs `coder/agentapi` with the prompt
# defined in ARG_AI_PROMPT
resource "coder_script" "agentapi" {
  agent_id     = coder_agent.main.id
  run_on_start = true
  script       = &lt;= 2.13.0
    }
  }
}

data "coder_workspace" "me" {}

# The prompt is now available in the coder_task data source.
data "coder_task" "me" {}

resource "coder_agent" "main" { ... }

# This coder_app is the interface to the Coder Task.
# This is assumed to be a running instance of coder/agentapi (for instance, started via `coder_script`).
resource "coder_app" "ai_agent" {
  ...
}

# Assuming that the below script runs `coder/agentapi` with the prompt
# defined in ARG_AI_PROMPT
resource "coder_script" "agentapi" {
  agent_id     = coder_agent.main.id
  run_on_start = true
  script       = &lt;