ddev-opencode

A DDEV add-on that runs OpenCode in a dedicated container for AI-powered Drupal development.

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

Agents, rules, and skills for Drupal development are automatically synced from drupal-ai-agents via ddev-agents-sync. No manual git clone needed.

Quick Start

The recommended way to install this add-on is through the DDEV AI Workspace, which installs all tools and dependencies with a single command:

ddev add-on get trebormc/ddev-ai-workspace
ddev restart
ddev opencode  # or: ddev oc

Standalone installation

If you only need OpenCode without the rest of the workspace, you can install it individually. This requires familiarity with the DDEV add-on ecosystem and its dependencies:

ddev add-on get trebormc/ddev-opencode
ddev restart
ddev opencode  # or: ddev oc

This automatically installs the required dependencies:

• ddev-agents-sync: auto-syncs AI agents from git
• ddev-ai-ssh: SSH access to web container
• ddev-beads: task tracking
• ddev-playwright-mcp: browser automation

Prerequisites

• DDEV >= v1.24.10
• An API key (Anthropic, OpenAI, or a LiteLLM proxy)

Authentication

Run ddev opencode and follow the prompts. OpenCode handles authentication natively. No custom commands or manual file editing needed.

Credentials are stored in a shared file on the host (~/.ddev/opencode/auth.json by default), so you only need to authenticate once. All your DDEV projects share the same credentials automatically.

Configuration

After installation, environment variables are in .ddev/.env.opencode:

# Shared OpenCode directory for credentials and config.
# Shared across ALL DDEV projects. Change only if you need a custom location.
# Files: auth.json (credentials), config/ (opencode.json, custom overrides)
HOST_OPENCODE_DIR=${HOME}/.ddev/opencode

# Timezone
TZ=UTC

Agent Configuration

Agents, rules, and skills are automatically synced from drupal-ai-agents via ddev-agents-sync. No manual setup is needed.

The sync process resolves model tokens (like ${MODEL_CHEAP}) to OpenCode model names (like opencode/gpt-5-nano) using the .env.agents file from the agent repository. See drupal-ai-agents for details on model tokens and customization.

To customize which repos are synced, edit .ddev/.env.agents-sync:

# Sync from multiple repos (later repos override earlier ones)
AGENTS_REPOS=https://github.com/trebormc/drupal-ai-agents.git,https://github.com/your-org/private-agents.git

To manually trigger an update: ddev agents-update

Changing agent models

To change which AI models your agents use, override the .env.agents file. Create a private git repo with just an .env.agents and add it as a second entry:

AGENTS_REPOS=https://github.com/trebormc/drupal-ai-agents.git,https://github.com/your-org/my-config.git

See Model Token System for the full list of tokens and how to customize them.

Local config override

To use a custom opencode.json (e.g., to add a LiteLLM proxy or change global permissions), place it in ~/.ddev/opencode/config/opencode.json. It takes precedence over the default from the agent repository. Agents, rules, and skills are always loaded from the synced volume regardless.

Architecture

┌─────────────────────────────────────────────────┐
│              DDEV Docker Network                 │
│                                                  │
│  ┌──────────────┐     SSH       ┌────────────┐  │
│  │   OpenCode   │──────────────>│    Web     │  │
│  │  Container   │               │  (Drupal)  │  │
│  └──────┬───────┘               └────────────┘  │
│         │ MCP HTTP                               │
│         v                                        │
│  ┌──────────────┐  ┌──────────────┐              │
│  │  Playwright  │  │    Beads     │              │
│  │     MCP      │  │  (bd tasks)  │              │
│  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────┘

OpenCode communicates with the web container via SSH (ssh web), giving it full CLI access to drush, composer, phpunit, phpstan, and any other tool in the web container. SSH keys are auto-generated per project in .ddev/.agent-ssh-keys/. Playwright MCP is accessed over HTTP for browser automation and visual testing.

Commands

Tab title for multi-project workflows

When working on multiple DDEV projects at the same time, it can be hard to tell which terminal belongs to which project. The tui subcommand sets the terminal tab title to project-name - custom text, so you can identify each terminal at a glance.

The project name (DDEV_SITENAME) is always included automatically. If you add extra text after tui, it appears as a label. Useful for describing the task you are working on in that terminal.

# Tab title: "mysite - OpenCode"
ddev opencode

# Tab title: "mysite - OpenCode"  (explicit tui, same result)
ddev opencode tui

# Tab title: "mysite - Fix login redirect bug"
ddev opencode tui Fix login redirect bug

# Tab title: "mysite - TASK-42 migrate users"
ddev opencode tui TASK-42 migrate users

This way, if you have three terminals open (two projects, two tasks), each tab shows exactly where you are and what you are doing.

Shell Helpers

Inside the container (via ddev opencode shell), these helper functions are available:

Desktop Notifications (optional)

OpenCode can send desktop notifications when tasks complete or need attention. Notifications are pre-configured via opencode-notifier.json (ships with drupal-ai-agents). No setup needed inside the container.

To receive notifications, install the ai-notify-bridge on your host (one-time setup):

curl -fsSL https://raw.githubusercontent.com/trebormc/ai-notify-bridge/main/install.sh | bash

If the bridge is not installed or not running, OpenCode works normally. Notification calls fail silently with no impact.

Multica integration (optional)

Multica is a managed-agents platform that lets you assign tasks to AI coding agents from a central web UI. This add-on can run the Multica daemon inside the OpenCode container so a self-hosted Multica server can delegate work to OpenCode in any of your DDEV projects.

The Multica binary is always installed in the container, but the daemon only runs when you opt in by setting a token in ~/.ddev/multica/.env.multica. With no file or an empty token, the integration stays completely dormant and the container behaves exactly as it does without Multica.

Enable (once, shared with other AI add-ons)

The Multica configuration lives in ~/.ddev/multica/.env.multica, a directory shared by every Multica-aware DDEV add-on (this one, ddev-claude-code, …). One configuration enables the daemon in all of them — and across every DDEV project on the same host.

# One-time setup on your host
cp ~/.ddev/multica/.env.multica.example ~/.ddev/multica/.env.multica
$EDITOR ~/.ddev/multica/.env.multica
# Fill in MULTICA_SERVER_URL, MULTICA_APP_URL, MULTICA_TOKEN

Then in any DDEV project using a Multica-aware add-on:

ddev restart

The container’s entrypoint detects the token, logs in, and starts the daemon in the background. Each container registers as a separate Multica runtime — OpenCode containers show up as OpenCode DDEV (<project>) with device name ddev-<project>-opencode. Watched workspaces are managed from the Multica UI (the daemon auto-subscribes to all your UI workspaces on login).

Verify

ddev opencode shell
multica daemon status
multica agent list

You should also see the runtime appear in the Multica UI under “Agent runtimes”.

Disable

Empty the file (or delete it) and ddev restart. The entrypoint will skip the Multica section entirely.

: > ~/.ddev/multica/.env.multica

Token rotation

The Personal Access Token from Multica defaults to a 90-day expiry. When it expires, regenerate it in the Multica UI, update ~/.ddev/multica/.env.multica, and ddev restart each project where you need it.

Autonomous Execution

For autonomous task execution (overnight runs), see ddev-ralph.

Uninstallation

ddev add-on remove ddev-opencode
ddev restart

Part of DDEV AI Workspace

This add-on is part of DDEV AI Workspace, a modular ecosystem of DDEV add-ons for AI-powered Drupal development.

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.