[rfay]

The Issue

• Install socat, fzf, zstd, and relay the forwarded SSH agent (VS Code, coder ssh -A) to DDEV by default #220: VS Code and coder ssh -A forward the user's agent, for example 1Password, but DDEV's containers can't use it. The forwarded socket also changes on every reconnect, and the old ones stop working.
• Load the Coder SSH key into an ssh-agent so DDEV containers can use it #210: Only git can use the Coder key, through GIT_SSH_COMMAND. Plain ssh and DDEV's containers have no key at all.

DDEV v1.25.5 adds ssh_agent_upstream (ddev/ddev#8861) and resolves symlinked agent sockets (ddev/ddev#8963). v1.25.5 also fixes PHP2Shell, so the #222 workaround can go.

How This PR Solves The Issue

• Revert of fix: PHP2Shell workaround, upgrade PHP in DDEV web images on workspace start #222: the PHP2Shell workaround is removed, because DDEV v1.25.5 web images have fixed PHP.
• Image v0.6 (already pushed): DDEV v1.25.5, plus socat, fzf and zstd. It also ships /home/coder-files/ssh-agent-relay/connect and bashrc.sh.
• shared/ssh-agent-setup.sh: copied into each template by make sync-ssh-agent-setup. It runs in every template's startup script after Docker is up:

  • It loads the Coder key into ssh-agent at ~/.coder-ssh-agent/agent.sock. The key is piped from the API into ssh-add - and never written to disk.

  • It runs a socat relay at ~/.ssh-agent-relay/agent.sock. On each connection, connect uses the first live agent of:

    1. current, the forwarded agent of the most recent interactive shell;
    2. the newest live /tmp/auth-agent*/listener.sock;
    3. the Coder-key agent.

    This means it follows a VS Code reconnect without a new terminal, and falls back to the Coder key when nothing is forwarded.

  • It sets ddev config global --ssh-agent-upstream to the relay socket. This is never current, because DDEV resolves symlinks once, when the project starts.

  • It adds one line to ~/.bashrc that sources bashrc.sh. In an interactive shell with a live forwarded agent, that script retargets current, then points the shell's SSH_AUTH_SOCK at the relay.

• Liveness checks: an agent counts as live only if timeout 2 ssh-add -l exits 0 or 1. A dead relay never replaces a working socket, and a hung forwarded agent can't stall a shell.
• Socket directories: each socket has its own directory, because DDEV mounts the socket's whole directory into ddev-ssh-agent.
• Spec, tests and docs:
  • OpenSpec change add-ssh-agent-relay;
  • an ssh_agent_relay run in each template's tests;
  • a new docs section, "SSH Keys in DDEV Containers", in docs/user/using-workspaces.md.

Known limitation, documented: the last session to forward an agent wins for the whole workspace. With workspace sharing, a collaborator's coder ssh -A switches the containers to their keys until the owner opens a new terminal.

Manual Testing Instructions

These need the v0.6 image, on staging. Use a fresh workspace from each template:

1. Run SSH_AUTH_SOCK=~/.coder-ssh-agent/agent.sock ssh-add -l. It should list the Coder key.
2. With no agent forwarded (web terminal), run ddev auth ssh and ddev exec ssh -T git@github.com. They should list and use the Coder key, and plain ssh -T git@github.com should work too.
3. Run coder ssh -A <ws> from a machine with your own agent, then repeat step 2. The containers should get your keys.
4. Do the same from VS Code Desktop. Then reconnect VS Code without opening a new terminal and run ddev exec ssh-add -l again. It should still work.
5. Disconnect every forwarding session. ddev exec ssh-add -l should fall back to the Coder key.
6. Check that the PHP2Shell workaround isn't needed: ddev exec php -v should show a fixed PHP.

Automated Testing Overview

• terraform fmt, make validate and make test-templates pass, and openspec validate add-ssh-agent-relay --strict passes.
• The connect/bashrc.sh fallback order was tested in a plain ubuntu:24.04 container with fake agents in six scenarios: Coder key only, a forwarded agent, a shell retargeting current, the forwarded agent gone, all forwarded agents gone, and a shell started with a dead SSH_AUTH_SOCK.
• Not yet verified: whether ddev-ssh-agent in the nested Docker under Sysbox can connect to the mode=600 relay socket. That's step 2 above.

Related Issue Link(s)

• Fixes Install socat, fzf, zstd, and relay the forwarded SSH agent (VS Code, coder ssh -A) to DDEV by default #220
• Fixes Load the Coder SSH key into an ssh-agent so DDEV containers can use it #210
• Reverts fix: PHP2Shell workaround, upgrade PHP in DDEV web images on workspace start #222

🤖 Generated with Claude Code

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-26 19:05 UTC