Marmelab Dev Container Features

A collection of custom dev container Features, published to GitHub Container Registry following the dev container Feature distribution specification.

Features

claude-code

Installs the Claude Code CLI and, in VS Code, the Claude Code extension. See src/claude-code.

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/marmelab/devcontainers/claude-code:1": {},
  },
}

$ claude --version

Repository structure

Each published Feature lives in its own sub-folder under src, containing a devcontainer-feature.json, an entrypoint install.sh, and a README.md. Tests live under test/<feature>.

├── src
│   └── claude-code
│       ├── devcontainer-feature.json
│       ├── install.sh
│       └── README.md
├── test
│   └── claude-code
│       ├── test.sh
│       ├── non_root_user.sh
│       └── scenarios.json
└── .devcontainer
    └── claude-code            # local dogfood copy (see below)

Developing this repository

This repo's own Dev Container installs Claude Code via a local copy of the feature at .devcontainer/claude-code. It is a separate copy because the Dev Container CLI only resolves local features inside the .devcontainer/ folder, so the published src/claude-code cannot be referenced directly. Keep the two in sync. Credential mounts for the container are declared in .devcontainer/devcontainer.json.

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 claude-code feature exposes a version option. If no option is provided in a user's devcontainer.json, the value falls back to its default (latest).

{
  // ...
  "options": {
    "version": {
      "type": "string",
      "proposals": ["latest", "stable"],
      "default": "latest",
      "description": "Version passed to the official installer.",
    },
  },
}

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

#!/bin/bash

echo "Activating feature 'claude-code' (version: ${VERSION})"

...

Distributing Features

Versioning

Features are individually versioned by the version attribute in a Feature's devcontainer-feature.json. Features are versioned according to the semver specification. More details can be found in the dev container Feature specification.

Publishing

NOTE: The Distribution spec can be found here.

While any registry implementing the OCI Distribution spec can be used, this template will leverage GHCR (GitHub Container Registry) as the backing registry.

Features are meant to be easily sharable units of dev container configuration and installation code.

This repo contains a GitHub Action workflow that will publish each Feature to GHCR.

Allow GitHub Actions to create and approve pull requests should be enabled in the repository's Settings > Actions > General > Workflow permissions for auto generation of src/<feature>/README.md per Feature (which merges any existing src/<feature>/NOTES.md).

By default, each Feature will be prefixed with the <owner>/<repo> namespace. For example, the Features in this repository can be referenced in a devcontainer.json with:

ghcr.io/marmelab/devcontainers/claude-code:1

The provided GitHub Action will also publish a "metadata" package with just the namespace, eg: ghcr.io/marmelab/devcontainers. This contains information useful for tools aiding in Feature discovery.

'marmelab/devcontainers' is known as the feature collection namespace.

Marking Feature Public

Note that by default, GHCR packages are marked as private. To stay within the free tier, Features need to be marked as public.

This can be done by navigating to the Feature's "package settings" page in GHCR, and setting the visibility to 'public`. The URL may look something like:

https://github.com/users/<owner>/packages/container/<repo>%2F<featureName>/settings

Adding Features to the Index

If you'd like your Features to appear in our public index so that other community members can find them, you can do the following:

• Go to github.com/devcontainers/devcontainers.github.io
  • This is the GitHub repo backing the containers.dev spec site
• Open a PR to modify the collection-index.yml file

This index is from where supporting tools like VS Code Dev Containers and GitHub Codespaces surface Features for their dev container creation UI.

Using private Features in Codespaces

For any Features hosted in GHCR that are kept private, the GITHUB_TOKEN access token in your environment will need to have package:read and contents:read for the associated repository.

Many implementing tools use a broadly scoped access token and will work automatically. GitHub Codespaces uses repo-scoped tokens, and therefore you'll need to add the permissions in devcontainer.json

An example devcontainer.json can be found below.

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/my-org/private-features/hello:1": {
      "greeting": "Hello",
    },
  },
  "customizations": {
    "codespaces": {
      "repositories": {
        "my-org/private-features": {
          "permissions": {
            "packages": "read",
            "contents": "read",
          },
        },
      },
    },
  },
}