Dev Container Features

This repository provides a collection of dev container Features for use in dev containers and GitHub Codespaces. Each Feature is independently versioned and published to GitHub Container Registry (GHCR) following the dev container Feature distribution specification.

Feature: agency-agents

Adds the msitarzewski/agency-agents agent set to your dev container. During the container build it:

1. Downloads the upstream repository as a ZIP archive.
2. Runs scripts/convert.sh to prepare the agents.
3. Runs scripts/install.sh --no-interactive --parallel when tool=auto (default), or scripts/install.sh --tool <tool> --no-interactive for explicit tool mode.

The feature only installs the upstream agent files for the selected tool(s). It does not create or modify workspace AGENTS.md files.

Official website: agencyagents.dev

Usage

{
    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
    "features": {
        "ghcr.io/YOUR_GITHUB_USER/agency-agents/agency-agents:0": {}
    }
}

To install for a specific tool, pass the tool option:

{
    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
    "features": {
        "ghcr.io/YOUR_GITHUB_USER/agency-agents/agency-agents:0": {
            "tool": "cursor"
        }
    }
}

Options

Option	Type	Default	Description
tool	string	auto	auto runs install.sh --no-interactive --parallel; otherwise uses --tool <tool> (e.g. copilot, cursor).

Credits

The agents installed by this feature come from the msitarzewski/agency-agents repository. All credit for the agent definitions, convert.sh, and install.sh scripts belongs to the upstream project and its contributors.

Project website: agencyagents.dev

This repository only wraps that upstream work as a dev container Feature for easier, reproducible installation inside dev containers.

Feature: opencode

Installs the opencode AI coding agent CLI and ensures volume-mounted data directories are owned by the correct user. During the container build it:

1. Downloads and runs the opencode installer via curl -fsSL https://opencode.ai/install | bash -s -- --no-modify-path.
2. Creates a symlink at /usr/local/bin/opencode so the CLI is available on PATH.
3. Installs a /usr/local/bin/opencode-fix-permissions script that fixes ownership of volume-mounted data directories.

The feature runs opencode-fix-permissions as a postStartCommand to ensure the config, data, and state directories under ~/.opencode are owned by the dev container user.

Official documentation: opencode.ai

Usage

{
    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
    "features": {
        "ghcr.io/YOUR_GITHUB_USER/devcontainer-features/opencode:0": {}
    }
}

To specify the username for volume ownership fixes, pass the username option:

{
    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
    "features": {
        "ghcr.io/YOUR_GITHUB_USER/devcontainer-features/opencode:0": {
            "username": "vscode"
        }
    }
}

Options

Option	Type	Default	Description
username	string	""	Username to own the ~/.opencode volume-mounted directories.
version	string	""	Specific version to install (e.g. 1.3.17). Empty = latest.

Volume Mounts

Opencode stores its configuration, data, and state under ~/.opencode in three subdirectories:

• config – configuration files
• data – project data and caches
• state – runtime state

When these directories are volume-mounted into the container, they may be owned by root depending on how the volumes are created. The opencode-fix-permissions script runs on container start to chown these directories to the specified user, ensuring opencode can read and write them without permission errors.

Shared Volumes Between Projects

If you share the same ~/.opencode volume mounts across multiple projects, be aware that opencode's state and data will be shared as well. This can be useful for preserving context between projects, but may also cause unexpected behaviour if projects have conflicting configurations. Consider using separate volume mounts per project if isolation is needed.

Repo and Feature Structure

Similar to the devcontainers/features repo, this repository has a src folder. Each Feature has its own sub-folder, containing at least a devcontainer-feature.json and an entrypoint script install.sh.

├── src
│   ├── agency-agents
│   │   ├── devcontainer-feature.json
│   │   └── install.sh
...

An implementing tool will composite the documented dev container properties from the feature's devcontainer-feature.json file, and execute in the install.sh entrypoint script in the container during build time. Implementing tools are also free to process attributes under the customizations property as desired.

Options

All available options for a Feature should be declared in the devcontainer-feature.json. The syntax for the options property can be found in the devcontainer Feature json properties reference.

For example, the agency-agents feature exposes a tool string option. If no option is provided in a user's devcontainer.json, the value defaults to auto.

{
    // ...
    "options": {
        "tool": {
            "type": "string",
            "default": "auto",
            "description": "Tool name passed to ./scripts/install.sh --tool <tool>. Use 'auto' for --parallel auto-detection."
        }
    }
}

Options are exported as Feature-scoped environment variables. The option name is capitalised and sanitised according to option resolution.

#!/bin/sh

tool="${TOOL:-auto}"

...