From c2cf0f86598bb4e7cf600b97b6abd4c94928654d Mon Sep 17 00:00:00 2001
From: Randy Fay <randy@randyfay.com>
Date: Mon, 26 Oct 2026 11:07:00 -0600
Subject: [PATCH 1/2] Revert PHP2Shell workaround (#222), fixed in DDEV v1.25.5

DDEV v1.25.5 ships ddev-webserver images with fixed PHP, and the v0.6
image installs it, so the per-start Dockerfile.php2shell upgrade step is
no longer needed.

This reverts commit cd5e8997f48aa92245bb96088946cc1d2d97a38f.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 drupal-contrib/template.tf      | 18 ------------------
 drupal-core/template.tf         | 18 ------------------
 freeform/template.tf            | 22 ----------------------
 image/scripts/.gitignore_global |  1 -
 4 files changed, 59 deletions(-)

diff --git a/drupal-contrib/template.tf b/drupal-contrib/template.tf
index 11b2580..31c1656 100644
--- a/drupal-contrib/template.tf
+++ b/drupal-contrib/template.tf
@@ -335,13 +335,6 @@ resource "coder_agent" "main" {
       grep -qxF 'config.coder.yaml' "$HOME/.gitignore_global" || \
         echo 'config.coder.yaml' >> "$HOME/.gitignore_global"
     fi
-    # PHP2Shell workaround (written into the project's .ddev/web-build below).
-    # Outside the if/elif so a fresh copy from an older image also gets it.
-    # Remove together with the Dockerfile.php2shell step after DDEV v1.25.5.
-    if [ -f "$HOME/.gitignore_global" ]; then
-      grep -qxF 'Dockerfile.php2shell' "$HOME/.gitignore_global" || \
-        echo 'Dockerfile.php2shell' >> "$HOME/.gitignore_global"
-    fi
     if [ -n "$CODER_WORKSPACE_OWNER_NAME" ]; then
       git config --global user.name "$CODER_WORKSPACE_OWNER_NAME"
     fi
@@ -629,17 +622,6 @@ hooks:
     - exec-host: 'echo "" && echo "  Site:    https://drupal-site--$${CODER_WORKSPACE_NAME}--$${CODER_WORKSPACE_OWNER_NAME}.$CODER_DOMAIN" && echo "  Mailpit: https://mailpit--$${CODER_WORKSPACE_NAME}--$${CODER_WORKSPACE_OWNER_NAME}.$CODER_DOMAIN" && echo ""'
 CODER_YAML_EOF
 
-      # PHP2Shell (CVE-2026-109618/CVE-2026-109619): upgrade PHP in the web image
-      # until DDEV v1.25.5 ships a fixed ddev-webserver. Remove after that upgrade.
-      # https://ddev.com/blog/php2shell-what-ddev-users-need-to-know/
-      mkdir -p .ddev/web-build
-      cat > .ddev/web-build/Dockerfile.php2shell << 'PHP2SHELL_EOF'
-# Auto-generated by coder-ddev workspace startup -- do not edit.
-# PHP2Shell fix; safe to delete after upgrading to DDEV v1.25.5.
-RUN (apt-get update || true) && apt-get install -y --only-upgrade 'php*'
-PHP2SHELL_EOF
-      log_setup "✓ .ddev/web-build/Dockerfile.php2shell written (PHP2Shell fix)"
-
       # For themes, set symlink target path via config.local.yaml
       if [ "$PROJECT_TYPE" = "theme" ]; then
         cat > .ddev/config.local.yaml << 'THEME_YAML_EOF'
diff --git a/drupal-core/template.tf b/drupal-core/template.tf
index 623a461..87cbe25 100644
--- a/drupal-core/template.tf
+++ b/drupal-core/template.tf
@@ -396,13 +396,6 @@ resource "coder_agent" "main" {
       grep -qxF 'config.zzz-coder-test-env.yaml' "$HOME/.gitignore_global" || \
         echo 'config.zzz-coder-test-env.yaml' >> "$HOME/.gitignore_global"
     fi
-    # PHP2Shell workaround (written into the project's .ddev/web-build below).
-    # Outside the if/elif so a fresh copy from an older image also gets it.
-    # Remove together with the Dockerfile.php2shell step after DDEV v1.25.5.
-    if [ -f "$HOME/.gitignore_global" ]; then
-      grep -qxF 'Dockerfile.php2shell' "$HOME/.gitignore_global" || \
-        echo 'Dockerfile.php2shell' >> "$HOME/.gitignore_global"
-    fi
     if [ -n "$CODER_WORKSPACE_OWNER_NAME" ]; then
       git config --global user.name "$CODER_WORKSPACE_OWNER_NAME"
     fi
@@ -718,17 +711,6 @@ hooks:
 CODER_YAML_EOF
     log_setup "✓ .ddev/config.coder.yaml written"
 
-    # PHP2Shell (CVE-2026-109618/CVE-2026-109619): upgrade PHP in the web image
-    # until DDEV v1.25.5 ships a fixed ddev-webserver. Remove after that upgrade.
-    # https://ddev.com/blog/php2shell-what-ddev-users-need-to-know/
-    mkdir -p .ddev/web-build
-    cat > .ddev/web-build/Dockerfile.php2shell << 'PHP2SHELL_EOF'
-# Auto-generated by coder-ddev workspace startup -- do not edit.
-# PHP2Shell fix; safe to delete after upgrading to DDEV v1.25.5.
-RUN (apt-get update || true) && apt-get install -y --only-upgrade 'php*'
-PHP2SHELL_EOF
-    log_setup "✓ .ddev/web-build/Dockerfile.php2shell written (PHP2Shell fix)"
-
     if ddev config --project-type="$DDEV_PROJECT_TYPE" $DDEV_DOCROOT_ARG --project-name="$${CODER_WORKSPACE_NAME}--$${CODER_WORKSPACE_OWNER_NAME}" >> "$SETUP_LOG" 2>&1; then
       log_setup "✓ DDEV configured (project-type=$DDEV_PROJECT_TYPE)"
       update_status "✓ DDEV config: Success"
diff --git a/freeform/template.tf b/freeform/template.tf
index 76bc52e..6efcd8b 100644
--- a/freeform/template.tf
+++ b/freeform/template.tf
@@ -247,13 +247,6 @@ resource "coder_agent" "main" {
       grep -qxF 'config.coder.yaml' "$HOME/.gitignore_global" || \
         echo 'config.coder.yaml' >> "$HOME/.gitignore_global"
     fi
-    # PHP2Shell workaround (written into each project's .ddev/web-build below).
-    # Outside the if/elif so a fresh copy from an older image also gets it.
-    # Remove together with the Dockerfile.php2shell step after DDEV v1.25.5.
-    if [ -f "$HOME/.gitignore_global" ]; then
-      grep -qxF 'Dockerfile.php2shell' "$HOME/.gitignore_global" || \
-        echo 'Dockerfile.php2shell' >> "$HOME/.gitignore_global"
-    fi
     mkdir -p ~/.ddev
     if [ -n "$CODER_WORKSPACE_OWNER_NAME" ]; then
       git config --global user.name "$CODER_WORKSPACE_OWNER_NAME"
@@ -310,21 +303,6 @@ resource "coder_agent" "main" {
       tail -20 /tmp/ddev-download-images.log || true
     fi
 
-    # PHP2Shell (CVE-2026-109618/CVE-2026-109619): upgrade PHP in every known
-    # project's web image until DDEV v1.25.5 ships a fixed ddev-webserver. Takes
-    # effect on each project's next `ddev start`/`ddev restart`. Remove after
-    # that upgrade. https://ddev.com/blog/php2shell-what-ddev-users-need-to-know/
-    ddev list -j 2>/dev/null | jq -r '.raw[]?.approot // empty' 2>/dev/null | while read -r _root; do
-      [ -d "$_root/.ddev" ] || continue
-      mkdir -p "$_root/.ddev/web-build"
-      cat > "$_root/.ddev/web-build/Dockerfile.php2shell" << 'PHP2SHELL_EOF'
-# Auto-generated by coder-ddev workspace startup -- do not edit.
-# PHP2Shell fix; safe to delete after upgrading to DDEV v1.25.5.
-RUN (apt-get update || true) && apt-get install -y --only-upgrade 'php*'
-PHP2SHELL_EOF
-      echo "✓ PHP2Shell fix written: $_root/.ddev/web-build/Dockerfile.php2shell"
-    done
-
     # Ensure yq and linuxbrew are in PATH for this session
     export PATH="$PATH:/home/linuxbrew/.linuxbrew/bin"
 
diff --git a/image/scripts/.gitignore_global b/image/scripts/.gitignore_global
index 7bfafcb..1930893 100644
--- a/image/scripts/.gitignore_global
+++ b/image/scripts/.gitignore_global
@@ -1,7 +1,6 @@
 # DDEV Coder integration
 config.coder.yaml
 config.zzz-coder-test-env.yaml
-Dockerfile.php2shell
 
 # macOS
 .DS_Store

From bc65c222f7df21b1d145de5499edba898b01d0db Mon Sep 17 00:00:00 2001
From: Randy Fay <randy@randyfay.com>
Date: Mon, 26 Oct 2026 11:12:36 -0600
Subject: [PATCH 2/2] feat: SSH agent relay for DDEV containers, Coder key in
 an agent, fixes #220, fixes #210

DDEV's containers couldn't use the Coder key or the user's forwarded
agent, and a forwarded agent's socket dies on every VS Code reconnect.
DDEV v1.25.5 adds ssh_agent_upstream and resolves symlinked sockets.

- Image (v0.6, DDEV v1.25.5): add socat, fzf, zstd, and ship
  ssh-agent-relay/connect and bashrc.sh in /home/coder-files.
- shared/ssh-agent-setup.sh (vendored by make sync-ssh-agent-setup,
  included in all three startup scripts):
  - loads the Coder key into ssh-agent at ~/.coder-ssh-agent/agent.sock
  - runs a socat relay at ~/.ssh-agent-relay/agent.sock that, per
    connection, uses the first live agent of: the most recent shell's
    forwarded agent (current), the newest /tmp/auth-agent*/listener.sock,
    the Coder-key agent
  - sets ddev ssh_agent_upstream to the relay socket
  - sources bashrc.sh from ~/.bashrc, which retargets current from shells
    with a live forwarded agent and points SSH_AUTH_SOCK at the relay
- Liveness checks use timeout 2 ssh-add -l (exit 0/1 = live).
- OpenSpec change add-ssh-agent-relay, user docs, template tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CLAUDE.md                                     |  2 +-
 Makefile                                      |  9 +++-
 VERSION                                       |  2 +-
 docs/user/using-workspaces.md                 | 22 +++++++++
 drupal-contrib/ssh-agent-setup.sh             | 49 +++++++++++++++++++
 drupal-contrib/template.tf                    |  2 +
 drupal-contrib/tests/validate.tftest.hcl      | 12 +++++
 drupal-core/ssh-agent-setup.sh                | 49 +++++++++++++++++++
 drupal-core/template.tf                       |  2 +
 drupal-core/tests/validate.tftest.hcl         | 15 ++++++
 freeform/ssh-agent-setup.sh                   | 49 +++++++++++++++++++
 freeform/template.tf                          |  2 +
 freeform/tests/validate.tftest.hcl            | 12 +++++
 image/Dockerfile                              |  9 +++-
 image/scripts/ssh-agent-relay/bashrc.sh       | 28 +++++++++++
 image/scripts/ssh-agent-relay/connect         | 37 ++++++++++++++
 .../changes/add-ssh-agent-relay/proposal.md   | 23 +++++++++
 .../specs/workspace-ssh-agent/spec.md         | 31 ++++++++++++
 openspec/changes/add-ssh-agent-relay/tasks.md | 12 +++++
 shared/ssh-agent-setup.sh                     | 49 +++++++++++++++++++
 20 files changed, 411 insertions(+), 5 deletions(-)
 create mode 100644 drupal-contrib/ssh-agent-setup.sh
 create mode 100644 drupal-core/ssh-agent-setup.sh
 create mode 100644 freeform/ssh-agent-setup.sh
 create mode 100644 image/scripts/ssh-agent-relay/bashrc.sh
 create mode 100644 image/scripts/ssh-agent-relay/connect
 create mode 100644 openspec/changes/add-ssh-agent-relay/proposal.md
 create mode 100644 openspec/changes/add-ssh-agent-relay/specs/workspace-ssh-agent/spec.md
 create mode 100644 openspec/changes/add-ssh-agent-relay/tasks.md
 create mode 100644 shared/ssh-agent-setup.sh

diff --git a/CLAUDE.md b/CLAUDE.md
index dc0122f..4c3cff1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -79,7 +79,7 @@ make test-templates
 
 ## Shared Terraform Assets
 
-Some Terraform config (currently `modules/claude-remote-control` and `shared/vscode-extensions.tf`) is shared across all three templates but must exist as a **physical copy inside each template directory** — `coder templates push` and CI's `terraform validate`/`test` only ever operate on a single template directory, so a relative `../modules` or `../shared` reference would not survive the push and would not be visible to CI.
+Some Terraform config (currently `modules/claude-remote-control`, `modules/docker-daemon`, `shared/vscode-extensions.tf`, `shared/bashrc-symlink-guard.sh` and `shared/ssh-agent-setup.sh`) is shared across all three templates but must exist as a **physical copy inside each template directory** — `coder templates push` and CI's `terraform validate`/`test` only ever operate on a single template directory, so a relative `../modules` or `../shared` reference would not survive the push and would not be visible to CI.
 
 - **Edit only the canonical source**: `modules/claude-remote-control/` or `shared/vscode-extensions.tf` at the repo root. Never hand-edit the vendored copies (`<template>/modules/claude-remote-control/`, `<template>/vscode-extensions.tf`) — they get overwritten the next time anyone runs the sync.
 - **Always resync through `make`**, never by hand-copying: `make sync-shared` (or `make sync-claude-module` / `make sync-vscode-extensions` individually). `make validate`, `make test-templates`, and every `make push-template-*` / `make push-all-templates` target already depend on `sync-shared`, so day-to-day you rarely need to invoke it directly.
diff --git a/Makefile b/Makefile
index ab52604..7fbc36e 100644
--- a/Makefile
+++ b/Makefile
@@ -138,8 +138,15 @@ sync-bashrc-guard: ## Vendor shared/bashrc-symlink-guard.sh into each template d
 	done
 	@echo "Synced shared/bashrc-symlink-guard.sh into: $(TEMPLATES)"
 
+.PHONY: sync-ssh-agent-setup
+sync-ssh-agent-setup: ## Vendor shared/ssh-agent-setup.sh into each template dir (same reason as sync-vscode-extensions: push only bundles the given --directory)
+	@for t in $(TEMPLATES); do \
+		cp shared/ssh-agent-setup.sh $$t/ssh-agent-setup.sh; \
+	done
+	@echo "Synced shared/ssh-agent-setup.sh into: $(TEMPLATES)"
+
 .PHONY: sync-shared
-sync-shared: sync-claude-module sync-vscode-extensions sync-docker-daemon-module sync-bashrc-guard ## Vendor all shared Terraform assets (modules + vscode-extensions.tf) into each template dir
+sync-shared: sync-claude-module sync-vscode-extensions sync-docker-daemon-module sync-bashrc-guard sync-ssh-agent-setup ## Vendor all shared Terraform assets (modules + vscode-extensions.tf) into each template dir
 
 .PHONY: validate
 validate: sync-shared ## Validate all Terraform templates (requires terraform in PATH)
diff --git a/VERSION b/VERSION
index 83b4ac5..74d5120 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-v0.5
+v0.6
diff --git a/docs/user/using-workspaces.md b/docs/user/using-workspaces.md
index 4f346a6..f9a0b6a 100644
--- a/docs/user/using-workspaces.md
+++ b/docs/user/using-workspaces.md
@@ -541,6 +541,28 @@ ssh -T git@gitlab.com
 
 **How it works:** Coder's GitSSH wrapper uses your Coder-managed SSH key automatically. No need to manage keys inside the workspace.
 
+### SSH Keys in DDEV Containers
+
+DDEV's containers can use the same keys, for example for `composer install` with private repositories, `drush` aliases, or `git` in a post-start hook. There's nothing to set up, and `ddev auth ssh` isn't needed:
+
+```bash
+ddev auth ssh                     # lists the keys the containers can use
+ddev exec ssh -T git@github.com   # tests them
+```
+
+The workspace runs an SSH agent relay at `~/.ssh-agent-relay/agent.sock`, and DDEV's `ssh_agent_upstream` points at it. Each time something uses the relay, it connects to the first of these that is available:
+
+1. **Your own agent, if it's forwarded.** VS Code Desktop forwards your local agent (for example 1Password), and so does `coder ssh -A`. Each new terminal or `coder ssh -A` session makes its agent the one the relay uses.
+2. **Your Coder-managed key**, loaded into an agent when the workspace starts.
+
+The relay picks again on every use, so after VS Code reconnects, DDEV containers that are already running keep working, and they fall back to the Coder key when you disconnect. Terminals use the relay too, so plain `ssh` in the workspace works the same way.
+
+Notes:
+
+- The most recent terminal or session with a forwarded agent wins for the whole workspace. If you [share a workspace](#sharing-your-workspace) and a collaborator connects with `coder ssh -A`, your DDEV containers use their keys until you open a new terminal.
+- While an agent is forwarded, any container on the DDEV network can ask it to sign. Agents that confirm each use, like 1Password, limit that exposure.
+- To use only key files instead, run `ddev config global --ssh-agent-upstream=""` and `ddev auth ssh`. The workspace sets the relay again on its next start.
+
 ### Common Workflows
 
 **Clone and start working:**
diff --git a/drupal-contrib/ssh-agent-setup.sh b/drupal-contrib/ssh-agent-setup.sh
new file mode 100644
index 0000000..9b4b209
--- /dev/null
+++ b/drupal-contrib/ssh-agent-setup.sh
@@ -0,0 +1,49 @@
+# SSH agent for the workspace and DDEV's containers (#210, #220). Runs after
+# Docker is up, because `ddev config global` needs it.
+#
+# - ~/.coder-ssh-agent/agent.sock: an ssh-agent holding the Coder workspace
+#   key, so plain ssh and DDEV's containers have a key even with nothing
+#   forwarded (git alone already gets it from GIT_SSH_COMMAND).
+# - ~/.ssh-agent-relay/agent.sock: one stable socket that relays each
+#   connection to the best live agent (see /home/coder-files/ssh-agent-relay/
+#   connect): the user's forwarded agent from VS Code or `coder ssh -A` when
+#   there is one, otherwise the Coder-key agent. DDEV's ssh_agent_upstream
+#   points here, never at the `current` symlink, since DDEV resolves symlinks
+#   once when the project starts.
+#
+# Each socket gets its own directory because DDEV bind-mounts the socket's
+# whole directory into ddev-ssh-agent.
+SSH_AGENT_DIR="$HOME/.coder-ssh-agent"
+SSH_RELAY_DIR="$HOME/.ssh-agent-relay"
+SSH_RELAY_FILES=/home/coder-files/ssh-agent-relay
+mkdir -p "$SSH_AGENT_DIR" "$SSH_RELAY_DIR"
+chmod 700 "$SSH_AGENT_DIR" "$SSH_RELAY_DIR"
+
+# $HOME persists across restarts and ssh-agent -a refuses an existing socket.
+pkill -u "$(id -u)" -f "ssh-agent -a $SSH_AGENT_DIR/agent.sock" 2> /dev/null || true
+rm -f "$SSH_AGENT_DIR/agent.sock"
+if setsid ssh-agent -a "$SSH_AGENT_DIR/agent.sock" > /dev/null 2>&1 < /dev/null; then
+  # The key goes straight from the API into the agent, never to disk.
+  if curl -fsS --max-time 10 -H "Coder-Session-Token: ${CODER_AGENT_TOKEN:-}" \
+    "${CODER_AGENT_URL%/}/api/v2/workspaceagents/me/gitsshkey" \
+    | jq -r .private_key | SSH_AUTH_SOCK="$SSH_AGENT_DIR/agent.sock" ssh-add -q - 2> /dev/null; then
+    echo "✓ Coder SSH key loaded into $SSH_AGENT_DIR/agent.sock"
+  else
+    echo "⚠ Could not load the Coder SSH key into $SSH_AGENT_DIR/agent.sock"
+  fi
+else
+  echo "⚠ Could not start ssh-agent at $SSH_AGENT_DIR/agent.sock"
+fi
+
+if command -v socat > /dev/null 2>&1 && [ -x "$SSH_RELAY_FILES/connect" ]; then
+  pkill -u "$(id -u)" -f "UNIX-LISTEN:$SSH_RELAY_DIR/agent.sock" 2> /dev/null || true
+  nohup setsid socat UNIX-LISTEN:"$SSH_RELAY_DIR/agent.sock",fork,unlink-early,mode=600 \
+    EXEC:"$SSH_RELAY_FILES/connect" > /dev/null 2>&1 < /dev/null &
+  ddev config global --ssh-agent-upstream="$SSH_RELAY_DIR/agent.sock" > /dev/null 2>&1 || true
+  if ! grep -qF "$SSH_RELAY_FILES/bashrc.sh" ~/.bashrc 2> /dev/null; then
+    echo "[ -r $SSH_RELAY_FILES/bashrc.sh ] && . $SSH_RELAY_FILES/bashrc.sh" >> ~/.bashrc
+  fi
+  echo "✓ SSH agent relay at $SSH_RELAY_DIR/agent.sock (ddev ssh_agent_upstream)"
+else
+  echo "⚠ socat or $SSH_RELAY_FILES/connect missing; SSH agent relay not started"
+fi
diff --git a/drupal-contrib/template.tf b/drupal-contrib/template.tf
index 31c1656..0b7948e 100644
--- a/drupal-contrib/template.tf
+++ b/drupal-contrib/template.tf
@@ -367,6 +367,8 @@ resource "coder_agent" "main" {
     mkdir -p ~/.ddev
     echo "Configuring DDEV to omit ddev-router..."
     ddev config global --omit-containers=ddev-router --instrumentation-opt-in=false > /dev/null 2>&1 || true
+
+    ${file("${path.module}/ssh-agent-setup.sh")}
     mkcert -install 2>/dev/null || true
 
     # Pre-pull DDEV images (uses registry mirror if configured). Redirect --
diff --git a/drupal-contrib/tests/validate.tftest.hcl b/drupal-contrib/tests/validate.tftest.hcl
index c16b80d..5aae18a 100644
--- a/drupal-contrib/tests/validate.tftest.hcl
+++ b/drupal-contrib/tests/validate.tftest.hcl
@@ -174,3 +174,15 @@ run "user_startup_hook" {
     error_message = "startup script must run the optional ~/.coder-startup.sh user hook, detached"
   }
 }
+
+run "ssh_agent_relay" {
+  command = plan
+  assert {
+    condition     = strcontains(coder_agent.main.startup_script, "api/v2/workspaceagents/me/gitsshkey")
+    error_message = "startup script must load the Coder SSH key into an ssh-agent"
+  }
+  assert {
+    condition     = strcontains(coder_agent.main.startup_script, "--ssh-agent-upstream=\"$SSH_RELAY_DIR/agent.sock\"")
+    error_message = "startup script must point DDEV's ssh_agent_upstream at the relay socket"
+  }
+}
diff --git a/drupal-core/ssh-agent-setup.sh b/drupal-core/ssh-agent-setup.sh
new file mode 100644
index 0000000..9b4b209
--- /dev/null
+++ b/drupal-core/ssh-agent-setup.sh
@@ -0,0 +1,49 @@
+# SSH agent for the workspace and DDEV's containers (#210, #220). Runs after
+# Docker is up, because `ddev config global` needs it.
+#
+# - ~/.coder-ssh-agent/agent.sock: an ssh-agent holding the Coder workspace
+#   key, so plain ssh and DDEV's containers have a key even with nothing
+#   forwarded (git alone already gets it from GIT_SSH_COMMAND).
+# - ~/.ssh-agent-relay/agent.sock: one stable socket that relays each
+#   connection to the best live agent (see /home/coder-files/ssh-agent-relay/
+#   connect): the user's forwarded agent from VS Code or `coder ssh -A` when
+#   there is one, otherwise the Coder-key agent. DDEV's ssh_agent_upstream
+#   points here, never at the `current` symlink, since DDEV resolves symlinks
+#   once when the project starts.
+#
+# Each socket gets its own directory because DDEV bind-mounts the socket's
+# whole directory into ddev-ssh-agent.
+SSH_AGENT_DIR="$HOME/.coder-ssh-agent"
+SSH_RELAY_DIR="$HOME/.ssh-agent-relay"
+SSH_RELAY_FILES=/home/coder-files/ssh-agent-relay
+mkdir -p "$SSH_AGENT_DIR" "$SSH_RELAY_DIR"
+chmod 700 "$SSH_AGENT_DIR" "$SSH_RELAY_DIR"
+
+# $HOME persists across restarts and ssh-agent -a refuses an existing socket.
+pkill -u "$(id -u)" -f "ssh-agent -a $SSH_AGENT_DIR/agent.sock" 2> /dev/null || true
+rm -f "$SSH_AGENT_DIR/agent.sock"
+if setsid ssh-agent -a "$SSH_AGENT_DIR/agent.sock" > /dev/null 2>&1 < /dev/null; then
+  # The key goes straight from the API into the agent, never to disk.
+  if curl -fsS --max-time 10 -H "Coder-Session-Token: ${CODER_AGENT_TOKEN:-}" \
+    "${CODER_AGENT_URL%/}/api/v2/workspaceagents/me/gitsshkey" \
+    | jq -r .private_key | SSH_AUTH_SOCK="$SSH_AGENT_DIR/agent.sock" ssh-add -q - 2> /dev/null; then
+    echo "✓ Coder SSH key loaded into $SSH_AGENT_DIR/agent.sock"
+  else
+    echo "⚠ Could not load the Coder SSH key into $SSH_AGENT_DIR/agent.sock"
+  fi
+else
+  echo "⚠ Could not start ssh-agent at $SSH_AGENT_DIR/agent.sock"
+fi
+
+if command -v socat > /dev/null 2>&1 && [ -x "$SSH_RELAY_FILES/connect" ]; then
+  pkill -u "$(id -u)" -f "UNIX-LISTEN:$SSH_RELAY_DIR/agent.sock" 2> /dev/null || true
+  nohup setsid socat UNIX-LISTEN:"$SSH_RELAY_DIR/agent.sock",fork,unlink-early,mode=600 \
+    EXEC:"$SSH_RELAY_FILES/connect" > /dev/null 2>&1 < /dev/null &
+  ddev config global --ssh-agent-upstream="$SSH_RELAY_DIR/agent.sock" > /dev/null 2>&1 || true
+  if ! grep -qF "$SSH_RELAY_FILES/bashrc.sh" ~/.bashrc 2> /dev/null; then
+    echo "[ -r $SSH_RELAY_FILES/bashrc.sh ] && . $SSH_RELAY_FILES/bashrc.sh" >> ~/.bashrc
+  fi
+  echo "✓ SSH agent relay at $SSH_RELAY_DIR/agent.sock (ddev ssh_agent_upstream)"
+else
+  echo "⚠ socat or $SSH_RELAY_FILES/connect missing; SSH agent relay not started"
+fi
diff --git a/drupal-core/template.tf b/drupal-core/template.tf
index 87cbe25..1a9ae78 100644
--- a/drupal-core/template.tf
+++ b/drupal-core/template.tf
@@ -449,6 +449,8 @@ resource "coder_agent" "main" {
     echo "Configuring DDEV to omit ddev-router..."
     ddev config global --omit-containers=ddev-router --instrumentation-opt-in=false > /dev/null 2>&1 || true
 
+    ${file("${path.module}/ssh-agent-setup.sh")}
+
     # Install mkcert CA to suppress DDEV's "mkcert may not be properly installed" warning
     # DDEV ships its own mkcert binary; this sets up the local CA trust
     mkcert -install 2>/dev/null || true
diff --git a/drupal-core/tests/validate.tftest.hcl b/drupal-core/tests/validate.tftest.hcl
index df30d94..111c43e 100644
--- a/drupal-core/tests/validate.tftest.hcl
+++ b/drupal-core/tests/validate.tftest.hcl
@@ -199,3 +199,18 @@ run "user_startup_hook" {
     error_message = "startup script must run the optional ~/.coder-startup.sh user hook, detached"
   }
 }
+
+run "ssh_agent_relay" {
+  command = plan
+  variables {
+    cache_path = "/tmp/mock-cache"
+  }
+  assert {
+    condition     = strcontains(coder_agent.main.startup_script, "api/v2/workspaceagents/me/gitsshkey")
+    error_message = "startup script must load the Coder SSH key into an ssh-agent"
+  }
+  assert {
+    condition     = strcontains(coder_agent.main.startup_script, "--ssh-agent-upstream=\"$SSH_RELAY_DIR/agent.sock\"")
+    error_message = "startup script must point DDEV's ssh_agent_upstream at the relay socket"
+  }
+}
diff --git a/freeform/ssh-agent-setup.sh b/freeform/ssh-agent-setup.sh
new file mode 100644
index 0000000..9b4b209
--- /dev/null
+++ b/freeform/ssh-agent-setup.sh
@@ -0,0 +1,49 @@
+# SSH agent for the workspace and DDEV's containers (#210, #220). Runs after
+# Docker is up, because `ddev config global` needs it.
+#
+# - ~/.coder-ssh-agent/agent.sock: an ssh-agent holding the Coder workspace
+#   key, so plain ssh and DDEV's containers have a key even with nothing
+#   forwarded (git alone already gets it from GIT_SSH_COMMAND).
+# - ~/.ssh-agent-relay/agent.sock: one stable socket that relays each
+#   connection to the best live agent (see /home/coder-files/ssh-agent-relay/
+#   connect): the user's forwarded agent from VS Code or `coder ssh -A` when
+#   there is one, otherwise the Coder-key agent. DDEV's ssh_agent_upstream
+#   points here, never at the `current` symlink, since DDEV resolves symlinks
+#   once when the project starts.
+#
+# Each socket gets its own directory because DDEV bind-mounts the socket's
+# whole directory into ddev-ssh-agent.
+SSH_AGENT_DIR="$HOME/.coder-ssh-agent"
+SSH_RELAY_DIR="$HOME/.ssh-agent-relay"
+SSH_RELAY_FILES=/home/coder-files/ssh-agent-relay
+mkdir -p "$SSH_AGENT_DIR" "$SSH_RELAY_DIR"
+chmod 700 "$SSH_AGENT_DIR" "$SSH_RELAY_DIR"
+
+# $HOME persists across restarts and ssh-agent -a refuses an existing socket.
+pkill -u "$(id -u)" -f "ssh-agent -a $SSH_AGENT_DIR/agent.sock" 2> /dev/null || true
+rm -f "$SSH_AGENT_DIR/agent.sock"
+if setsid ssh-agent -a "$SSH_AGENT_DIR/agent.sock" > /dev/null 2>&1 < /dev/null; then
+  # The key goes straight from the API into the agent, never to disk.
+  if curl -fsS --max-time 10 -H "Coder-Session-Token: ${CODER_AGENT_TOKEN:-}" \
+    "${CODER_AGENT_URL%/}/api/v2/workspaceagents/me/gitsshkey" \
+    | jq -r .private_key | SSH_AUTH_SOCK="$SSH_AGENT_DIR/agent.sock" ssh-add -q - 2> /dev/null; then
+    echo "✓ Coder SSH key loaded into $SSH_AGENT_DIR/agent.sock"
+  else
+    echo "⚠ Could not load the Coder SSH key into $SSH_AGENT_DIR/agent.sock"
+  fi
+else
+  echo "⚠ Could not start ssh-agent at $SSH_AGENT_DIR/agent.sock"
+fi
+
+if command -v socat > /dev/null 2>&1 && [ -x "$SSH_RELAY_FILES/connect" ]; then
+  pkill -u "$(id -u)" -f "UNIX-LISTEN:$SSH_RELAY_DIR/agent.sock" 2> /dev/null || true
+  nohup setsid socat UNIX-LISTEN:"$SSH_RELAY_DIR/agent.sock",fork,unlink-early,mode=600 \
+    EXEC:"$SSH_RELAY_FILES/connect" > /dev/null 2>&1 < /dev/null &
+  ddev config global --ssh-agent-upstream="$SSH_RELAY_DIR/agent.sock" > /dev/null 2>&1 || true
+  if ! grep -qF "$SSH_RELAY_FILES/bashrc.sh" ~/.bashrc 2> /dev/null; then
+    echo "[ -r $SSH_RELAY_FILES/bashrc.sh ] && . $SSH_RELAY_FILES/bashrc.sh" >> ~/.bashrc
+  fi
+  echo "✓ SSH agent relay at $SSH_RELAY_DIR/agent.sock (ddev ssh_agent_upstream)"
+else
+  echo "⚠ socat or $SSH_RELAY_FILES/connect missing; SSH agent relay not started"
+fi
diff --git a/freeform/template.tf b/freeform/template.tf
index 6efcd8b..1dd4905 100644
--- a/freeform/template.tf
+++ b/freeform/template.tf
@@ -282,6 +282,8 @@ resource "coder_agent" "main" {
     ddev config global --instrumentation-opt-in=true > /dev/null 2>&1 || true
     ddev config global --router-http-port=8080 > /dev/null 2>&1 || true
 
+    ${file("${path.module}/ssh-agent-setup.sh")}
+
     # Create .ddev commands directory
     mkdir -p ~/.ddev/commands/host
     if [ -d /home/coder-files/.ddev/commands/host ]; then
diff --git a/freeform/tests/validate.tftest.hcl b/freeform/tests/validate.tftest.hcl
index b39c378..4c7d8c6 100644
--- a/freeform/tests/validate.tftest.hcl
+++ b/freeform/tests/validate.tftest.hcl
@@ -238,3 +238,15 @@ run "user_startup_hook" {
     error_message = "startup script must run the optional ~/.coder-startup.sh user hook, detached"
   }
 }
+
+run "ssh_agent_relay" {
+  command = plan
+  assert {
+    condition     = strcontains(coder_agent.main.startup_script, "api/v2/workspaceagents/me/gitsshkey")
+    error_message = "startup script must load the Coder SSH key into an ssh-agent"
+  }
+  assert {
+    condition     = strcontains(coder_agent.main.startup_script, "--ssh-agent-upstream=\"$SSH_RELAY_DIR/agent.sock\"")
+    error_message = "startup script must point DDEV's ssh_agent_upstream at the relay socket"
+  }
+}
diff --git a/image/Dockerfile b/image/Dockerfile
index d33ef83..04c09d5 100644
--- a/image/Dockerfile
+++ b/image/Dockerfile
@@ -15,6 +15,7 @@ RUN apt-get update && \
   direnv \
   dnsutils \
   file \
+  fzf \
   git \
   gnupg \
   htop \
@@ -32,6 +33,7 @@ RUN apt-get update && \
   passwd \
   postgresql-client \
   rsync \
+  socat \
   software-properties-common \
   sudo \
   telnet \
@@ -40,7 +42,8 @@ RUN apt-get update && \
   unzip \
   vim \
   wget \
-  zip && \
+  zip \
+  zstd && \
   # Generate locale
   locale-gen en_US.UTF-8 && \
   rm -rf /var/lib/apt/lists/* && \
@@ -201,7 +204,9 @@ RUN chmod 644 /home/coder-files/WELCOME.txt && \
   chmod 644 /home/coder-files/.gitconfig && \
   chmod 644 /home/coder-files/.gitignore_global && \
   chmod 755 /home/coder-files/.ddev/commands/host/launch && \
-  chmod 755 /home/coder-files/.ddev/commands/host/coder-routes
+  chmod 755 /home/coder-files/.ddev/commands/host/coder-routes && \
+  chmod 755 /home/coder-files/ssh-agent-relay/connect && \
+  chmod 644 /home/coder-files/ssh-agent-relay/bashrc.sh
 
 USER coder
 RUN ddev --version && \
diff --git a/image/scripts/ssh-agent-relay/bashrc.sh b/image/scripts/ssh-agent-relay/bashrc.sh
new file mode 100644
index 0000000..c77d4eb
--- /dev/null
+++ b/image/scripts/ssh-agent-relay/bashrc.sh
@@ -0,0 +1,28 @@
+# Sourced from ~/.bashrc in interactive shells. If this shell has a working
+# forwarded SSH agent (VS Code Remote, `coder ssh -A`), point the workspace
+# relay at it, so DDEV's containers get the same keys. Then use the relay for
+# this shell's own SSH_AUTH_SOCK, so it keeps working after a reconnect and
+# falls back to the Coder key when no agent is forwarded.
+# The last shell to start wins: `current` is shared by the whole workspace.
+
+_relay_dir="$HOME/.ssh-agent-relay"
+
+# ssh-add -l exits 0 or 1 when it reaches an agent, 2 when it can't, and
+# timeout exits 124 so a hung forwarded socket can't stall the shell.
+_ssh_agent_alive() {
+  SSH_AUTH_SOCK="$1" timeout 2 ssh-add -l > /dev/null 2>&1
+  [ $? -le 1 ]
+}
+
+if [ -d "$_relay_dir" ]; then
+  if [ -n "${SSH_AUTH_SOCK:-}" ] && [ "$SSH_AUTH_SOCK" != "$_relay_dir/agent.sock" ] \
+    && _ssh_agent_alive "$SSH_AUTH_SOCK"; then
+    ln -sfn "$(readlink -f "$SSH_AUTH_SOCK")" "$_relay_dir/current"
+  fi
+  if [ -S "$_relay_dir/agent.sock" ] && _ssh_agent_alive "$_relay_dir/agent.sock"; then
+    export SSH_AUTH_SOCK="$_relay_dir/agent.sock"
+  fi
+fi
+
+unset _relay_dir
+unset -f _ssh_agent_alive
diff --git a/image/scripts/ssh-agent-relay/connect b/image/scripts/ssh-agent-relay/connect
new file mode 100644
index 0000000..5cfc19f
--- /dev/null
+++ b/image/scripts/ssh-agent-relay/connect
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Connects one client of the workspace SSH agent relay
+# (~/.ssh-agent-relay/agent.sock) to the best agent that is alive right now.
+# socat runs this once per connection (EXEC:), so the relay follows a VS Code
+# or `coder ssh -A` reconnect without being restarted, and falls back to the
+# Coder-key agent when no forwarded agent is left. Candidates, in order:
+#   1. ~/.ssh-agent-relay/current: the forwarded agent of the most recent
+#      interactive shell that had one (set by bashrc.sh)
+#   2. the newest live forwarded agent, /tmp/auth-agent*/listener.sock
+#   3. ~/.coder-ssh-agent/agent.sock: the Coder workspace key, loaded at startup
+
+relay_dir="${HOME:-/home/coder}/.ssh-agent-relay"
+coder_agent="${HOME:-/home/coder}/.coder-ssh-agent/agent.sock"
+
+# ssh-add -l exits 0 (keys) or 1 (no keys) when it reaches an agent, 2 when it
+# can't, and timeout exits 124 if the agent hangs.
+alive() {
+  [ -S "$1" ] || return 1
+  SSH_AUTH_SOCK="$1" timeout 2 ssh-add -l > /dev/null 2>&1
+  [ $? -le 1 ]
+}
+
+candidates=()
+if [ -L "$relay_dir/current" ]; then
+  candidates+=("$(readlink -f "$relay_dir/current")")
+fi
+while IFS= read -r sock; do
+  candidates+=("$sock")
+done < <(ls -t /tmp/auth-agent*/listener.sock 2> /dev/null)
+candidates+=("$coder_agent")
+
+for sock in "${candidates[@]}"; do
+  if alive "$sock"; then
+    exec socat STDIO UNIX-CONNECT:"$sock"
+  fi
+done
+exit 1
diff --git a/openspec/changes/add-ssh-agent-relay/proposal.md b/openspec/changes/add-ssh-agent-relay/proposal.md
new file mode 100644
index 0000000..a774774
--- /dev/null
+++ b/openspec/changes/add-ssh-agent-relay/proposal.md
@@ -0,0 +1,23 @@
+# Change: SSH Agent for the Workspace and DDEV Containers
+
+## Why
+Only `git` in a workspace can use the Coder-managed SSH key, through `GIT_SSH_COMMAND`. Plain `ssh` has no agent, and DDEV's containers have neither the key nor the user's own keys, so `composer install` with private repositories, `drush` aliases, and `git` in post-start hooks fail inside `web` (#210).
+
+A user's own agent forwarded by VS Code Remote or `coder ssh -A` doesn't reach the containers reliably either: every reconnect creates a new socket and leaves the old one dead, so containers and terminals started before a reconnect lose the agent (#220).
+
+DDEV v1.25.5 adds `ssh_agent_upstream` (ddev/ddev#8861) and resolves symlinked agent sockets (ddev/ddev#8963), which this change builds on. #210 and #220 both set `ssh_agent_upstream` and `SSH_AUTH_SOCK`, so they are done together.
+
+## What Changes
+- The image installs `socat`, `fzf` and `zstd`, and ships `/home/coder-files/ssh-agent-relay/connect` and `bashrc.sh`. `VERSION` goes to `v0.6`, which also brings DDEV v1.25.5.
+- New shared startup snippet `shared/ssh-agent-setup.sh`, vendored into each template by `make sync-ssh-agent-setup` and included in each template's `startup_script` after Docker is up:
+  - Starts `ssh-agent` on `~/.coder-ssh-agent/agent.sock` and loads the Coder key from `/api/v2/workspaceagents/me/gitsshkey`, piped straight into `ssh-add -`.
+  - Starts a `socat` relay on `~/.ssh-agent-relay/agent.sock` that runs `connect` for each connection. `connect` uses the first live agent of: the `current` symlink (the forwarded agent of the most recent interactive shell), the newest live `/tmp/auth-agent*/listener.sock`, and the Coder-key agent.
+  - Runs `ddev config global --ssh-agent-upstream=~/.ssh-agent-relay/agent.sock`. It never points at `current`, because DDEV resolves symlinks once at project start.
+  - Adds one line to `~/.bashrc` that sources `bashrc.sh`. In interactive shells with a live forwarded agent, `bashrc.sh` retargets `current`, and it then sets the shell's `SSH_AUTH_SOCK` to the relay. Both liveness checks use `timeout 2 ssh-add -l`, and only exit codes 0 and 1 count as live.
+- Each socket has its own directory, because DDEV bind-mounts the socket's directory into `ddev-ssh-agent`.
+- `docs/user/using-workspaces.md` documents the behavior, including that the most recent forwarding session wins for the whole workspace, which matters with workspace sharing.
+
+## Impact
+- Affected specs: `workspace-ssh-agent` (new capability)
+- Affected code: `image/Dockerfile`, `image/scripts/ssh-agent-relay/`, `shared/ssh-agent-setup.sh` (and vendored copies), `drupal-core/template.tf`, `drupal-contrib/template.tf`, `freeform/template.tf`, their `tests/validate.tftest.hcl`, `Makefile`, `VERSION`, `docs/user/using-workspaces.md`
+- Security: any container on a project's DDEV network can ask the relayed agent to sign. That's the same exposure as `ddev auth ssh` with an upstream agent; the Coder key is one the workspace user can already fetch, and agents like 1Password confirm each use.
diff --git a/openspec/changes/add-ssh-agent-relay/specs/workspace-ssh-agent/spec.md b/openspec/changes/add-ssh-agent-relay/specs/workspace-ssh-agent/spec.md
new file mode 100644
index 0000000..fa2fd22
--- /dev/null
+++ b/openspec/changes/add-ssh-agent-relay/specs/workspace-ssh-agent/spec.md
@@ -0,0 +1,31 @@
+## ADDED Requirements
+
+### Requirement: Coder Key Agent
+The workspace startup script SHALL load the Coder-managed SSH key into an `ssh-agent` on `~/.coder-ssh-agent/agent.sock` on every workspace start, without writing the key to disk and without failing workspace startup.
+
+#### Scenario: Key loads
+- **WHEN** a workspace starts
+- **THEN** `SSH_AUTH_SOCK=~/.coder-ssh-agent/agent.sock ssh-add -l` SHALL list the Coder key
+
+#### Scenario: Key fetch fails
+- **WHEN** the agent can't start or the key can't be fetched
+- **THEN** the startup script SHALL print a warning and continue
+
+### Requirement: SSH Agent Relay for DDEV
+The workspace SHALL provide a stable agent socket at `~/.ssh-agent-relay/agent.sock` that connects each client to the first live agent of: the forwarded agent recorded by the most recent interactive shell, the newest live forwarded agent in `/tmp/auth-agent*/listener.sock`, and the Coder key agent. DDEV's global `ssh_agent_upstream` SHALL point at this socket.
+
+#### Scenario: Nothing forwarded
+- **WHEN** no client forwards an SSH agent
+- **THEN** `ddev exec ssh-add -l` SHALL list the Coder key
+
+#### Scenario: Forwarded agent
+- **WHEN** a user opens a terminal through VS Code Remote or `coder ssh -A` with a forwarded agent
+- **THEN** DDEV's containers and that terminal SHALL use the forwarded agent's keys
+
+#### Scenario: Reconnect
+- **WHEN** the forwarded agent that was in use goes away
+- **THEN** the relay SHALL use the next live forwarded agent, or the Coder key agent if none is left, without restarting DDEV projects
+
+#### Scenario: Hung forwarded agent
+- **WHEN** a forwarded agent socket doesn't respond
+- **THEN** a new interactive shell SHALL start within about 2 seconds per liveness check, and SHALL NOT set `SSH_AUTH_SOCK` to that socket
diff --git a/openspec/changes/add-ssh-agent-relay/tasks.md b/openspec/changes/add-ssh-agent-relay/tasks.md
new file mode 100644
index 0000000..efa84b5
--- /dev/null
+++ b/openspec/changes/add-ssh-agent-relay/tasks.md
@@ -0,0 +1,12 @@
+## 1. Implementation
+- [x] 1.1 Install `socat`, `fzf`, `zstd` and ship `ssh-agent-relay/connect` and `bashrc.sh` in the image; bump `VERSION` to `v0.6` (DDEV v1.25.5) <!-- id: 1.1 -->
+- [x] 1.2 Add `shared/ssh-agent-setup.sh`, the `sync-ssh-agent-setup` make target, and include it in the `startup_script` of `drupal-core`, `drupal-contrib` and `freeform` <!-- id: 1.2 -->
+- [x] 1.3 Add an `ssh_agent_relay` run to each template's `tests/validate.tftest.hcl` <!-- id: 1.3 -->
+- [x] 1.4 Document in `docs/user/using-workspaces.md` <!-- id: 1.4 -->
+- [x] 1.5 Revert the PHP2Shell workaround (#222), now that DDEV v1.25.5 has fixed PHP <!-- id: 1.5 -->
+
+## 2. Validation
+- [x] 2.1 `terraform fmt -check -recursive`, `make validate` and `make test-templates` pass <!-- id: 2.1 -->
+- [x] 2.2 Relay fallback order checked in a plain `ubuntu:24.04` container: Coder key only, forwarded agent, shell retargeting, agent gone, all gone, dead `SSH_AUTH_SOCK` <!-- id: 2.2 -->
+- [ ] 2.3 With the v0.6 image on staging: `ddev-ssh-agent` in the nested Docker connects to the `mode=600` relay socket under Sysbox <!-- id: 2.3 -->
+- [ ] 2.4 On staging, from a fresh workspace: `ddev auth ssh` and `ddev exec ssh -T git@github.com` with no forwarded agent (Coder key), with `coder ssh -A`, and with VS Code Desktop, including after a VS Code reconnect <!-- id: 2.4 -->
diff --git a/shared/ssh-agent-setup.sh b/shared/ssh-agent-setup.sh
new file mode 100644
index 0000000..9b4b209
--- /dev/null
+++ b/shared/ssh-agent-setup.sh
@@ -0,0 +1,49 @@
+# SSH agent for the workspace and DDEV's containers (#210, #220). Runs after
+# Docker is up, because `ddev config global` needs it.
+#
+# - ~/.coder-ssh-agent/agent.sock: an ssh-agent holding the Coder workspace
+#   key, so plain ssh and DDEV's containers have a key even with nothing
+#   forwarded (git alone already gets it from GIT_SSH_COMMAND).
+# - ~/.ssh-agent-relay/agent.sock: one stable socket that relays each
+#   connection to the best live agent (see /home/coder-files/ssh-agent-relay/
+#   connect): the user's forwarded agent from VS Code or `coder ssh -A` when
+#   there is one, otherwise the Coder-key agent. DDEV's ssh_agent_upstream
+#   points here, never at the `current` symlink, since DDEV resolves symlinks
+#   once when the project starts.
+#
+# Each socket gets its own directory because DDEV bind-mounts the socket's
+# whole directory into ddev-ssh-agent.
+SSH_AGENT_DIR="$HOME/.coder-ssh-agent"
+SSH_RELAY_DIR="$HOME/.ssh-agent-relay"
+SSH_RELAY_FILES=/home/coder-files/ssh-agent-relay
+mkdir -p "$SSH_AGENT_DIR" "$SSH_RELAY_DIR"
+chmod 700 "$SSH_AGENT_DIR" "$SSH_RELAY_DIR"
+
+# $HOME persists across restarts and ssh-agent -a refuses an existing socket.
+pkill -u "$(id -u)" -f "ssh-agent -a $SSH_AGENT_DIR/agent.sock" 2> /dev/null || true
+rm -f "$SSH_AGENT_DIR/agent.sock"
+if setsid ssh-agent -a "$SSH_AGENT_DIR/agent.sock" > /dev/null 2>&1 < /dev/null; then
+  # The key goes straight from the API into the agent, never to disk.
+  if curl -fsS --max-time 10 -H "Coder-Session-Token: ${CODER_AGENT_TOKEN:-}" \
+    "${CODER_AGENT_URL%/}/api/v2/workspaceagents/me/gitsshkey" \
+    | jq -r .private_key | SSH_AUTH_SOCK="$SSH_AGENT_DIR/agent.sock" ssh-add -q - 2> /dev/null; then
+    echo "✓ Coder SSH key loaded into $SSH_AGENT_DIR/agent.sock"
+  else
+    echo "⚠ Could not load the Coder SSH key into $SSH_AGENT_DIR/agent.sock"
+  fi
+else
+  echo "⚠ Could not start ssh-agent at $SSH_AGENT_DIR/agent.sock"
+fi
+
+if command -v socat > /dev/null 2>&1 && [ -x "$SSH_RELAY_FILES/connect" ]; then
+  pkill -u "$(id -u)" -f "UNIX-LISTEN:$SSH_RELAY_DIR/agent.sock" 2> /dev/null || true
+  nohup setsid socat UNIX-LISTEN:"$SSH_RELAY_DIR/agent.sock",fork,unlink-early,mode=600 \
+    EXEC:"$SSH_RELAY_FILES/connect" > /dev/null 2>&1 < /dev/null &
+  ddev config global --ssh-agent-upstream="$SSH_RELAY_DIR/agent.sock" > /dev/null 2>&1 || true
+  if ! grep -qF "$SSH_RELAY_FILES/bashrc.sh" ~/.bashrc 2> /dev/null; then
+    echo "[ -r $SSH_RELAY_FILES/bashrc.sh ] && . $SSH_RELAY_FILES/bashrc.sh" >> ~/.bashrc
+  fi
+  echo "✓ SSH agent relay at $SSH_RELAY_DIR/agent.sock (ddev ssh_agent_upstream)"
+else
+  echo "⚠ socat or $SSH_RELAY_FILES/connect missing; SSH agent relay not started"
+fi