feat: provide boundary support for agent modules (#780)

## Description
Enable any agent module to run its AI agent inside Coder's Agent
Boundaries.
The agentapi module handles boundary installation, config setup, and
wrapper
script creation, then exports AGENTAPI_BOUNDARY_PREFIX for consuming
modules
to use in their start scripts.

Supports three boundary installation modes:
- coder boundary subcommand (default, Coder v2.30+)
- Standalone binary via install script (use_boundary_directly)
- Compiled from source (compile_boundary_from_source)

Users must provide a boundary config.yaml with their allowlist and
settings when enabling boundary.

Closes #457

## Type of Change
- [x] Feature/enhancement

## Module Information
**Path:** `registry/coder/modules/agentapi`
**Breaking change:** No

## Testing & Validation
- [x] Tests pass (`bun test`)
- [x] Code formatted (`bun fmt`)
- [x] Changes tested locally

---------

Co-authored-by: Shane White <shane.white@cloudsecure.ltd>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: 35C4n0r <70096901+35C4n0r@users.noreply.github.com>

registry/coder/modules/agentapi/README.md

@@ -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.2.0"
+  version = "2.3.0"
 
   agent_id             = var.agent_id
   web_app_slug         = local.app_slug
@@ -67,8 +67,7 @@ module "agentapi" {
 AgentAPI can save and restore conversation state across workspace restarts.
 This is disabled by default and requires agentapi binary >= v0.12.0.
 
-State and PID files are stored in `$HOME/<module_dir_name>/` alongside other
-module files (e.g. `$HOME/.claude-module/agentapi-state.json`).
+State and PID files are stored in `$HOME/<module_dir_name>/` alongside other module files (e.g. `$HOME/.claude-module/agentapi-state.json`).
 
 To enable:
 
@@ -89,6 +88,47 @@ module "agentapi" {
 }
 ```
 
+## Boundary (Network Filtering)
+
+The agentapi module supports optional [Agent Boundaries](https://coder.com/docs/ai-coder/agent-boundaries)
+for network filtering. When enabled, the module sets up a `AGENTAPI_BOUNDARY_PREFIX` environment
+variable that points to a wrapper script. Agent modules should use this prefix in their
+start scripts to run the agent process through boundary.
+
+Boundary requires a `config.yaml` file with your allowlist, jail type, proxy port, and log
+level. See the [Agent Boundaries documentation](https://coder.com/docs/ai-coder/agent-boundaries)
+for configuration details.
+To enable:
+
+```tf
+module "agentapi" {
+  # ... other config
+  enable_boundary      = true
+  boundary_config_path = "/home/coder/.config/coder_boundary/config.yaml"
+
+  # Optional: install boundary binary instead of using coder subcommand
+  # use_boundary_directly        = true
+  # boundary_version              = "0.6.0"
+  # compile_boundary_from_source  = false
+}
+```
+
+### Contract for agent modules
+
+When `enable_boundary = true`, the agentapi module exports `AGENTAPI_BOUNDARY_PREFIX`
+as an environment variable pointing to a wrapper script. Agent module start scripts
+should check for this variable and use it to prefix the agent command:
+
+```bash
+if [ -n "${AGENTAPI_BOUNDARY_PREFIX:-}" ]; then
+  agentapi server -- "${AGENTAPI_BOUNDARY_PREFIX}" my-agent "${ARGS[@]}" &
+else
+  agentapi server -- my-agent "${ARGS[@]}" &
+fi
+```
+
+This ensures only the agent process is sandboxed while agentapi itself runs unrestricted.
+
 ## For module developers
 
 For a complete example of how to use this module, see the [Goose module](https://github.com/coder/registry/blob/main/registry/coder/modules/goose/main.tf).

registry/coder/modules/agentapi/main.test.ts

@@ -613,4 +613,109 @@ describe("agentapi", async () => {
       expect(result.stdout).toContain("Sending SIGTERM to AgentAPI");
     });
   });
+
+  describe("boundary", async () => {
+    test("boundary-disabled-by-default", async () => {
+      const { id } = await setup();
+      await execModuleScript(id);
+      await expectAgentAPIStarted(id);
+      // Config file should NOT exist when boundary is disabled
+      const configCheck = await execContainer(id, [
+        "bash",
+        "-c",
+        "test -f /home/coder/.config/coder_boundary/config.yaml && echo exists || echo missing",
+      ]);
+      expect(configCheck.stdout.trim()).toBe("missing");
+      // AGENTAPI_BOUNDARY_PREFIX should NOT be in the mock log
+      const mockLog = await readFileContainer(
+        id,
+        "/home/coder/agentapi-mock.log",
+      );
+      expect(mockLog).not.toContain("AGENTAPI_BOUNDARY_PREFIX:");
+    });
+
+    test("boundary-enabled", async () => {
+      const { id } = await setup({
+        moduleVariables: {
+          enable_boundary: "true",
+          boundary_config_path: "/tmp/test-boundary.yaml",
+        },
+      });
+      // Write boundary config to the path before running the module
+      await execContainer(id, [
+        "bash",
+        "-c",
+        `cat > /tmp/test-boundary.yaml <<'EOF'
+jail_type: landjail
+proxy_port: 8087
+log_level: warn
+allowlist:
+  - "domain=api.example.com"
+EOF`,
+      ]);
+      // Add mock coder binary for boundary setup
+      await writeExecutable({
+        containerId: id,
+        filePath: "/usr/bin/coder",
+        content: `#!/bin/bash
+if [ "$1" = "boundary" ]; then
+ shift; shift; exec "$@"
+fi
+echo "mock coder"`,
+      });
+      await execModuleScript(id);
+      await expectAgentAPIStarted(id);
+      // Verify the config file exists at the specified path
+      const config = await readFileContainer(id, "/tmp/test-boundary.yaml");
+      expect(config).toContain("jail_type: landjail");
+      expect(config).toContain("proxy_port: 8087");
+      expect(config).toContain("domain=api.example.com");
+      // AGENTAPI_BOUNDARY_PREFIX should be exported
+      const mockLog = await readFileContainer(
+        id,
+        "/home/coder/agentapi-mock.log",
+      );
+      expect(mockLog).toContain("AGENTAPI_BOUNDARY_PREFIX:");
+      // E2E: start script should have used the wrapper
+      const startLog = await readFileContainer(
+        id,
+        "/home/coder/test-agentapi-start.log",
+      );
+      expect(startLog).toContain("Starting with boundary:");
+    });
+
+    test("boundary-enabled-no-coder-binary", async () => {
+      const { id } = await setup({
+        moduleVariables: {
+          enable_boundary: "true",
+          boundary_config_path: "/tmp/test-boundary.yaml",
+        },
+      });
+      // Write boundary config
+      await execContainer(id, [
+        "bash",
+        "-c",
+        `cat > /tmp/test-boundary.yaml <<'EOF'
+jail_type: landjail
+proxy_port: 8087
+log_level: warn
+EOF`,
+      ]);
+      // Remove coder binary to simulate it not being available
+      await execContainer(
+        id,
+        [
+          "bash",
+          "-c",
+          "rm -f /usr/bin/coder /usr/local/bin/coder 2>/dev/null; hash -r",
+        ],
+        ["--user", "root"],
+      );
+      const resp = await execModuleScript(id);
+      // Script should fail because coder binary is required
+      expect(resp.exitCode).not.toBe(0);
+      const scriptLog = await readFileContainer(id, "/home/coder/script.log");
+      expect(scriptLog).toContain("Boundary cannot be enabled");
+    });
+  });
 });

registry/coder/modules/agentapi/main.tf

@@ -164,6 +164,36 @@ variable "module_dir_name" {
   description = "Name of the subdirectory in the home directory for module files."
 }
 
+variable "enable_boundary" {
+  type        = bool
+  description = "Enable coder boundary for network filtering. Requires boundary_config to be set."
+  default     = false
+}
+
+variable "boundary_config_path" {
+  type        = string
+  description = "Path to boundary config.yaml inside the workspace. If provided, exposed as BOUNDARY_CONFIG env var."
+  default     = ""
+}
+
+variable "boundary_version" {
+  type        = string
+  description = "Boundary version. When use_boundary_directly is true, a release version should be provided or 'latest' for the latest release. When compile_boundary_from_source is true, a valid git reference should be provided (tag, commit, branch)."
+  default     = "latest"
+}
+
+variable "compile_boundary_from_source" {
+  type        = bool
+  description = "Whether to compile boundary from source instead of using the official install script."
+  default     = false
+}
+
+variable "use_boundary_directly" {
+  type        = bool
+  description = "Whether to use boundary binary directly instead of coder boundary subcommand. When false (default), uses coder boundary subcommand. When true, installs and uses boundary binary from release."
+  default     = false
+}
+
 variable "enable_state_persistence" {
   type        = bool
   description = "Enable AgentAPI conversation state persistence across restarts."
@@ -182,6 +212,13 @@ variable "pid_file_path" {
   default     = ""
 }
 
+resource "coder_env" "boundary_config" {
+  count    = var.enable_boundary && var.boundary_config_path != "" ? 1 : 0
+  agent_id = var.agent_id
+  name     = "BOUNDARY_CONFIG"
+  value    = var.boundary_config_path
+}
+
 locals {
   # we always trim the slash for consistency
   workdir                            = trimsuffix(var.folder, "/")
@@ -200,6 +237,7 @@ locals {
   main_script             = file("${path.module}/scripts/main.sh")
   shutdown_script         = file("${path.module}/scripts/agentapi-shutdown.sh")
   lib_script              = file("${path.module}/scripts/lib.sh")
+  boundary_script         = file("${path.module}/scripts/boundary.sh")
 }
 
 resource "coder_script" "agentapi" {
@@ -214,6 +252,9 @@ resource "coder_script" "agentapi" {
     echo -n '${base64encode(local.main_script)}' | base64 -d > /tmp/main.sh
     chmod +x /tmp/main.sh
     echo -n '${base64encode(local.lib_script)}' | base64 -d > /tmp/agentapi-lib.sh
+    
+    echo -n '${base64encode(local.boundary_script)}' | base64 -d > /tmp/agentapi-boundary.sh
+    chmod +x /tmp/agentapi-boundary.sh
 
     ARG_MODULE_DIR_NAME='${var.module_dir_name}' \
     ARG_WORKDIR="$(echo -n '${base64encode(local.workdir)}' | base64 -d)" \
@@ -228,6 +269,10 @@ resource "coder_script" "agentapi" {
     ARG_AGENTAPI_CHAT_BASE_PATH='${local.agentapi_chat_base_path}' \
     ARG_TASK_ID='${try(data.coder_task.me.id, "")}' \
     ARG_TASK_LOG_SNAPSHOT='${var.task_log_snapshot}' \
+    ARG_ENABLE_BOUNDARY='${var.enable_boundary}' \
+    ARG_BOUNDARY_VERSION='${var.boundary_version}' \
+    ARG_COMPILE_BOUNDARY_FROM_SOURCE='${var.compile_boundary_from_source}' \
+    ARG_USE_BOUNDARY_DIRECTLY='${var.use_boundary_directly}' \
     ARG_ENABLE_STATE_PERSISTENCE='${var.enable_state_persistence}' \
     ARG_STATE_FILE_PATH='${var.state_file_path}' \
     ARG_PID_FILE_PATH='${var.pid_file_path}' \

registry/coder/modules/agentapi/scripts/boundary.sh

@@ -0,0 +1,95 @@
+#!/bin/bash
+# boundary.sh - Boundary installation and setup for agentapi module.
+# Sourced by main.sh when ENABLE_BOUNDARY=true.
+# Exports AGENTAPI_BOUNDARY_PREFIX for use by module start scripts.
+
+validate_boundary_subcommand() {
+  if command_exists coder; then
+    if coder boundary --help > /dev/null 2>&1; then
+      return 0
+    else
+      echo "Error: 'coder' command found but does not support 'boundary' subcommand. Please enable install_boundary."
+      exit 1
+    fi
+  else
+    echo "Error: ENABLE_BOUNDARY=true, but 'coder' command not found. Boundary cannot be enabled." >&2
+    exit 1
+  fi
+}
+
+# Install boundary binary if needed.
+# Uses one of three strategies:
+#   1. Compile from source (compile_boundary_from_source=true)
+#   2. Install from release (use_boundary_directly=true)
+#   3. Use coder boundary subcommand (default, no installation needed)
+install_boundary() {
+  if [ "${COMPILE_BOUNDARY_FROM_SOURCE}" = "true" ]; then
+    echo "Compiling boundary from source (version: ${BOUNDARY_VERSION})"
+
+    # Remove existing boundary directory to allow re-running safely
+    if [ -d boundary ]; then
+      rm -rf boundary
+    fi
+
+    echo "Cloning boundary repository"
+    git clone https://github.com/coder/boundary.git
+    cd boundary || exit 1
+    git checkout "${BOUNDARY_VERSION}"
+
+    make build
+
+    sudo cp boundary /usr/local/bin/
+    sudo chmod +x /usr/local/bin/boundary
+    cd - || exit 1
+  elif [ "${USE_BOUNDARY_DIRECTLY}" = "true" ]; then
+    echo "Installing boundary using official install script (version: ${BOUNDARY_VERSION})"
+    curl -fsSL https://raw.githubusercontent.com/coder/boundary/main/install.sh | bash -s -- --version "${BOUNDARY_VERSION}"
+  else
+    validate_boundary_subcommand
+    echo "Using coder boundary subcommand (provided by Coder)"
+  fi
+}
+
+# Set up boundary: install, write config, create wrapper script.
+# Exports AGENTAPI_BOUNDARY_PREFIX pointing to the wrapper script.
+setup_boundary() {
+  local module_path="$1"
+
+  echo "Setting up coder boundary..."
+
+  # Install boundary binary if needed
+  install_boundary
+
+  # Determine which boundary command to use and create wrapper script
+  BOUNDARY_WRAPPER_SCRIPT="$module_path/boundary-wrapper.sh"
+
+  if [ "${COMPILE_BOUNDARY_FROM_SOURCE}" = "true" ] || [ "${USE_BOUNDARY_DIRECTLY}" = "true" ]; then
+    # Use boundary binary directly (from compilation or release installation)
+    cat > "${BOUNDARY_WRAPPER_SCRIPT}" << 'WRAPPER_EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+exec boundary -- "$@"
+WRAPPER_EOF
+  else
+    # Use coder boundary subcommand (default)
+    # Copy coder binary to strip CAP_NET_ADMIN capabilities.
+    # This is necessary because boundary doesn't work with privileged binaries
+    # (you can't launch privileged binaries inside network namespaces unless
+    # you have sys_admin).
+    CODER_NO_CAPS="$module_path/coder-no-caps"
+    if ! cp "$(which coder)" "$CODER_NO_CAPS"; then
+      echo "Error: Failed to copy coder binary to ${CODER_NO_CAPS}. Boundary cannot be enabled." >&2
+      exit 1
+    fi
+    cat > "${BOUNDARY_WRAPPER_SCRIPT}" << 'WRAPPER_EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "${SCRIPT_DIR}/coder-no-caps" boundary -- "$@"
+WRAPPER_EOF
+  fi
+
+  chmod +x "${BOUNDARY_WRAPPER_SCRIPT}"
+  export AGENTAPI_BOUNDARY_PREFIX="${BOUNDARY_WRAPPER_SCRIPT}"
+  echo "Boundary wrapper configured: ${AGENTAPI_BOUNDARY_PREFIX}"
+}

registry/coder/modules/agentapi/scripts/main.sh

@@ -16,6 +16,10 @@ AGENTAPI_PORT="$ARG_AGENTAPI_PORT"
 AGENTAPI_CHAT_BASE_PATH="${ARG_AGENTAPI_CHAT_BASE_PATH:-}"
 TASK_ID="${ARG_TASK_ID:-}"
 TASK_LOG_SNAPSHOT="${ARG_TASK_LOG_SNAPSHOT:-true}"
+ENABLE_BOUNDARY="${ARG_ENABLE_BOUNDARY:-false}"
+BOUNDARY_VERSION="${ARG_BOUNDARY_VERSION:-latest}"
+COMPILE_BOUNDARY_FROM_SOURCE="${ARG_COMPILE_BOUNDARY_FROM_SOURCE:-false}"
+USE_BOUNDARY_DIRECTLY="${ARG_USE_BOUNDARY_DIRECTLY:-false}"
 ENABLE_STATE_PERSISTENCE="${ARG_ENABLE_STATE_PERSISTENCE:-false}"
 STATE_FILE_PATH="${ARG_STATE_FILE_PATH:-}"
 PID_FILE_PATH="${ARG_PID_FILE_PATH:-}"
@@ -109,9 +113,18 @@ export LC_ALL=en_US.UTF-8
 
 cd "${WORKDIR}"
 
+# Set up boundary if enabled
+export AGENTAPI_BOUNDARY_PREFIX=""
+if [ "${ENABLE_BOUNDARY}" = "true" ]; then
+  # shellcheck source=boundary.sh
+  source /tmp/agentapi-boundary.sh
+  setup_boundary "$module_path"
+fi
+
 export AGENTAPI_CHAT_BASE_PATH="${AGENTAPI_CHAT_BASE_PATH:-}"
 # Disable host header check since AgentAPI is proxied by Coder (which does its own validation)
 export AGENTAPI_ALLOWED_HOSTS="*"
+
 export AGENTAPI_PID_FILE="${PID_FILE_PATH:-$module_path/agentapi.pid}"
 # Only set state env vars when persistence is enabled and the binary supports
 # it. State persistence requires agentapi >= v0.12.0.

registry/coder/modules/agentapi/testdata/agentapi-mock.js

@@ -31,6 +31,15 @@ for (const v of [
     );
   }
 }
+// Log boundary env vars.
+for (const v of ["AGENTAPI_BOUNDARY_PREFIX"]) {
+  if (process.env[v]) {
+    fs.appendFileSync(
+      "/home/coder/agentapi-mock.log",
+      `\n${v}: ${process.env[v]}`,
+    );
+  }
+}
 
 // Write PID file for shutdown script.
 if (process.env.AGENTAPI_PID_FILE) {

registry/coder/modules/agentapi/testdata/agentapi-start.sh

@@ -17,6 +17,16 @@ if [ -n "$AGENTAPI_CHAT_BASE_PATH" ]; then
   export AGENTAPI_CHAT_BASE_PATH
 fi
 
-agentapi server --port "$port" --term-width 67 --term-height 1190 -- \
-  bash -c aiagent \
-  > "$log_file_path" 2>&1
+# Use boundary wrapper if configured by agentapi module.
+# AGENTAPI_BOUNDARY_PREFIX is set by the agentapi module's main.sh
+# and points to a wrapper script that runs the command through coder boundary.
+if [ -n "${AGENTAPI_BOUNDARY_PREFIX:-}" ]; then
+  echo "Starting with boundary: ${AGENTAPI_BOUNDARY_PREFIX}" >> /home/coder/test-agentapi-start.log
+  agentapi server --port "$port" --term-width 67 --term-height 1190 -- \
+    "${AGENTAPI_BOUNDARY_PREFIX}" bash -c aiagent \
+    > "$log_file_path" 2>&1
+else
+  agentapi server --port "$port" --term-width 67 --term-height 1190 -- \
+    bash -c aiagent \
+    > "$log_file_path" 2>&1
+fi

registry/coder/modules/mux/README.md

@@ -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 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.
+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`. The launcher now keeps watching the mux process after startup and appends signal/exit-code diagnostics to the mux log when the server is killed outside the Node runtime. 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.3.1"
+  version  = "1.4.0"
   agent_id = coder_agent.main.id
 }
 ```
@@ -37,7 +37,7 @@ module "mux" {
 module "mux" {
   count    = data.coder_workspace.me.start_count
   source   = "registry.coder.com/coder/mux/coder"
-  version  = "1.3.1"
+  version  = "1.4.0"
   agent_id = coder_agent.main.id
 }
 ```
@@ -48,7 +48,7 @@ module "mux" {
 module "mux" {
   count    = data.coder_workspace.me.start_count
   source   = "registry.coder.com/coder/mux/coder"
-  version  = "1.3.1"
+  version  = "1.4.0"
   agent_id = coder_agent.main.id
   # Default is "latest"; set to a specific version to pin
   install_version = "0.4.0"
@@ -63,7 +63,7 @@ Start Mux with `mux server --add-project /path/to/project`:
 module "mux" {
   count       = data.coder_workspace.me.start_count
   source      = "registry.coder.com/coder/mux/coder"
-  version     = "1.3.1"
+  version     = "1.4.0"
   agent_id    = coder_agent.main.id
   add_project = "/path/to/project"
 }
@@ -78,7 +78,7 @@ The module parses quoted values, so grouped arguments remain intact.
 module "mux" {
   count                = data.coder_workspace.me.start_count
   source               = "registry.coder.com/coder/mux/coder"
-  version              = "1.3.1"
+  version              = "1.4.0"
   agent_id             = coder_agent.main.id
   additional_arguments = "--open-mode pinned --add-project '/workspaces/my repo'"
 }
@@ -90,7 +90,7 @@ module "mux" {
 module "mux" {
   count    = data.coder_workspace.me.start_count
   source   = "registry.coder.com/coder/mux/coder"
-  version  = "1.3.1"
+  version  = "1.4.0"
   agent_id = coder_agent.main.id
   port     = 8080
 }
@@ -104,7 +104,7 @@ Force a specific package manager instead of auto-detection:
 module "mux" {
   count           = data.coder_workspace.me.start_count
   source          = "registry.coder.com/coder/mux/coder"
-  version         = "1.3.1"
+  version         = "1.4.0"
   agent_id        = coder_agent.main.id
   package_manager = "pnpm" # or "npm", "bun"
 }
@@ -118,7 +118,7 @@ Use a private or mirrored npm registry:
 module "mux" {
   count        = data.coder_workspace.me.start_count
   source       = "registry.coder.com/coder/mux/coder"
-  version      = "1.3.1"
+  version      = "1.4.0"
   agent_id     = coder_agent.main.id
   registry_url = "https://npm.pkg.github.com"
 }
@@ -132,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.3.1"
+  version    = "1.4.0"
   agent_id   = coder_agent.main.id
   use_cached = true
 }
@@ -146,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.3.1"
+  version  = "1.4.0"
   agent_id = coder_agent.main.id
   install  = false
 }
@@ -163,3 +163,4 @@ module "mux" {
 - 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
+- Appends best-effort signal and external-kill diagnostics to `log_path` if the mux process dies after startup

registry/coder/modules/mux/main.test.ts

@@ -96,6 +96,55 @@ chmod +x /tmp/mux/mux`,
     }
   }, 60000);
 
+  it("logs signal-based exits after startup", async () => {
+    const state = await runTerraformApply(import.meta.dir, {
+      agent_id: "foo",
+      install: false,
+      log_path: "/tmp/mux.log",
+    });
+
+    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
+target_pid="$$"
+(
+  sleep 1
+  kill -9 "$target_pid"
+) &
+while true; do
+  sleep 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 2"]);
+      const log = await readFileContainer(id, "/tmp/mux.log");
+      expect(log).toContain("shell exit code 137");
+      expect(log).toContain(
+        "SIGKILL usually means the process was killed externally or by the OOM killer.",
+      );
+    } finally {
+      await removeContainer(id);
+    }
+  }, 60000);
+
   it("runs with npm present", async () => {
     const state = await runTerraformApply(import.meta.dir, {
       agent_id: "foo",

registry/coder/modules/mux/mux.tftest.hcl

@@ -93,6 +93,24 @@ run "custom_additional_arguments" {
   }
 }
 
+run "launcher_logs_external_kills" {
+  command = plan
+
+  variables {
+    agent_id = "foo"
+  }
+
+  assert {
+    condition     = strcontains(resource.coder_script.mux.script, "shell exit code $exit_code")
+    error_message = "mux launcher must log the shell exit code when the server dies unexpectedly"
+  }
+
+  assert {
+    condition     = strcontains(resource.coder_script.mux.script, "SIGKILL usually means the process was killed externally or by the OOM killer.")
+    error_message = "mux launcher must explain SIGKILL exits in the log"
+  }
+}
+
 run "custom_version" {
   command = plan
 

registry/coder/modules/mux/run.sh

@@ -15,6 +15,9 @@ function run_mux() {
   if [ -z "$port_value" ]; then
     port_value="4000"
   fi
+
+  mkdir -p "$(dirname "${LOG_PATH}")"
+
   # Build args for mux (POSIX-compatible, avoid bash arrays)
   set -- server --port "$port_value"
   if [ -n "${ADD_PROJECT}" ]; then
@@ -31,16 +34,93 @@ function run_mux() {
     while IFS= read -r parsed_arg; do
       [ -n "$parsed_arg" ] || continue
       set -- "$@" "$parsed_arg"
-    done << EOF
+    done << EOF_ARGS
 $${parsed_additional_arguments}
-EOF
+EOF_ARGS
   fi
 
   echo "🚀 Starting mux server on port $port_value..."
   echo "Check logs at ${LOG_PATH}!"
-  MUX_SERVER_AUTH_TOKEN="$auth_token_value" PORT="$port_value" "$MUX_BINARY" "$@" > "${LOG_PATH}" 2>&1 &
+  echo "ℹ️ Unexpected exits will be appended to ${LOG_PATH} by the launcher."
+
+  nohup env \
+    LOG_PATH="${LOG_PATH}" \
+    MUX_BINARY="$MUX_BINARY" \
+    AUTH_TOKEN="$auth_token_value" \
+    PORT_VALUE="$port_value" \
+    bash -s -- "$@" > /dev/null 2>&1 << 'EOF_LAUNCHER' &
+signal_name() {
+  local signal_number="$1"
+  local resolved_signal
+
+  resolved_signal="$(kill -l "$signal_number" 2> /dev/null || true)"
+  if [ -n "$resolved_signal" ]; then
+    printf '%s' "$resolved_signal"
+    return 0
+  fi
+
+  printf 'SIG%s' "$signal_number"
 }
 
+append_kernel_kill_context() {
+  local mux_pid="$1"
+  local kernel_context=""
+
+  if command -v dmesg > /dev/null 2>&1; then
+    kernel_context="$(dmesg -T 2> /dev/null | grep -Ei "Killed process $mux_pid|out of memory|oom-killer|oom reaper" | tail -n 10 || true)"
+  fi
+
+  if [ -z "$kernel_context" ] && command -v journalctl > /dev/null 2>&1; then
+    kernel_context="$(journalctl -k -n 200 --no-pager 2> /dev/null | grep -Ei "Killed process $mux_pid|out of memory|oom-killer|oom reaper" | tail -n 10 || true)"
+  fi
+
+  if [ -n "$kernel_context" ]; then
+    echo "Recent kernel kill context:"
+    echo "$kernel_context"
+  else
+    echo "No kernel OOM/kill context was available (dmesg/journalctl unavailable or permission denied)."
+  fi
+}
+
+log_mux_exit() {
+  local mux_pid="$1"
+  local exit_code="$2"
+  local timestamp
+
+  timestamp="$(date -Iseconds 2> /dev/null || date)"
+
+  if [ "$exit_code" -eq 0 ]; then
+    echo "[$timestamp] mux server exited cleanly."
+    return 0
+  fi
+
+  if [ "$exit_code" -gt 128 ]; then
+    local signal_number=$((exit_code - 128))
+    local signal_label
+
+    signal_label="$(signal_name "$signal_number")"
+    echo "[$timestamp] mux server exited due to signal $signal_label ($signal_number); shell exit code $exit_code."
+
+    if [ "$signal_number" -eq 9 ]; then
+      echo "[$timestamp] SIGKILL usually means the process was killed externally or by the OOM killer."
+      append_kernel_kill_context "$mux_pid"
+    fi
+
+    echo "[$timestamp] Check the earlier mux log lines for any in-process crash breadcrumbs from mux itself."
+    return 0
+  fi
+
+  echo "[$timestamp] mux server exited with code $exit_code."
+  echo "[$timestamp] Check the earlier mux log lines for any in-process crash breadcrumbs from mux itself."
+}
+
+MUX_SERVER_AUTH_TOKEN="$AUTH_TOKEN" PORT="$PORT_VALUE" "$MUX_BINARY" "$@" >> "$LOG_PATH" 2>&1 &
+mux_pid=$!
+wait "$mux_pid"
+exit_code=$?
+log_mux_exit "$mux_pid" "$exit_code" >> "$LOG_PATH" 2>&1
+EOF_LAUNCHER
+}
 # Check if mux is already installed for offline mode
 if [ "${OFFLINE}" = true ]; then
   if [ -f "$MUX_BINARY" ]; then