ddev-ai-ssh

A DDEV add-on that enables SSH access to the web container for AI agents. Installs sshd in the web container and generates per-project SSH keys, so AI containers (OpenCode, Claude Code, Ralph) can execute commands (drush, composer, phpunit, phpstan) without needing the Docker socket.

Part of DDEV AI Workspace — a modular ecosystem of DDEV add-ons for AI-powered Drupal development. Install the full stack with one command: ddev add-on get trebormc/ddev-ai-workspace

Created by Robert Menetray · Sponsored by DruScan

Note: This add-on is typically installed automatically as a dependency of ddev-opencode or ddev-claude-code. You rarely need to install it directly.

Why SSH?

SSH provides per-project isolation with minimal attack surface. Each DDEV project has a unique ed25519 key pair, so AI containers can only connect to the web container of their own project. Different projects have different keys, preventing cross-project access.

What it does

Installs openssh-server in the web container (via web-build/Dockerfile.ai-ssh)
Generates a per-project ed25519 key pair in .ddev/.agent-ssh-keys/ (gitignored)
Configures the ddev user’s authorized_keys on every ddev start
Hardens sshd: no root login, no password auth, no TCP/X11 forwarding

AI containers use ssh web <command> to run commands in the web container (drush, composer, phpunit, etc.).

Quick Start

The recommended way to install this add-on is through the DDEV AI Workspace:

ddev add-on get trebormc/ddev-ai-workspace
ddev restart

This add-on is also automatically installed as a dependency when you install ddev-opencode or ddev-claude-code.

Standalone installation

ddev add-on get trebormc/ddev-ai-ssh
ddev restart

Commands

Command	Description
`ddev ai-ssh-status`	Check if sshd is running and keys are configured

Configuration

No configuration needed. Keys are generated automatically on install and reused across restarts.

SSH keys are stored in .ddev/.agent-ssh-keys/ and automatically added to .gitignore. Each developer generates their own keys on the first install.

Security

Per-project isolation: each project has a unique key pair. Containers from project A cannot connect to project B.
Key-only authentication: no passwords, no root login.
Hardened sshd: TCP forwarding and X11 forwarding disabled.
ForceCommand: SSH sessions always start in /var/www/html with DDEV environment variables.

Uninstallation

ddev add-on remove ddev-ai-ssh
ddev restart

SSH keys in .ddev/.agent-ssh-keys/ are NOT deleted automatically.

Part of DDEV AI Workspace

Repository	Description	Relationship
ddev-ai-workspace	Meta add-on that installs the full AI development stack.	Workspace
ddev-opencode	OpenCode AI CLI container.	Auto-installs this add-on
ddev-claude-code	Claude Code CLI container.	Auto-installs this add-on
ddev-ralph	Autonomous AI task orchestrator.	Uses SSH indirectly
ddev-beads	Git-backed task tracker.	Sibling dependency
ddev-playwright-mcp	Headless Playwright browser.	Sibling dependency
drupal-ai-agents	10 agents, 12 rules, 24 skills for Drupal development.	Agent configuration

Disclaimer

This project is an independent initiative by Robert Menetray, sponsored by DruScan. It is not affiliated with Anthropic, OpenCode, Beads, Playwright, Microsoft, or DDEV. AI-generated code may contain errors. Always review changes before deploying to production.

License

Apache-2.0. See LICENSE.