Claude Code

Catalog name claude. Anthropic’s Claude Code CLI (claude), an interactive coding assistant.

What it’s for

An AI coding agent that lives in the container and works against your real stack - reading and editing the repos, running commands, driving the tools you installed. Its login (OAuth/subscription, or API key) and session state persist across container rebuilds, so you authenticate once.

Add it

monoceros init acme --with-features=claude
monoceros add-feature acme claude

Note

acme is just a sample workbench name - it’s whatever you passed to monoceros init. Substitute your own throughout.

Remove it

monoceros remove-feature acme claude

Or delete the feature’s entry from acme.yml by hand and re-run monoceros apply acme - the yml is the source of truth.

Options

Option	Default	Description
version	latest	npm-style version spec (latest, ^0.4, 0.4.2).
apiKey	(empty)	sk-ant-... for API auth; empty means OAuth login on first run.
permissionMode	auto	Default permission mode Claude starts in (see below).

acme.yml

features:
  - ref: ghcr.io/getmonoceros/monoceros-features/claude-code:1
    options:
      permissionMode: auto
      apiKey: ${CLAUDE_CODE_API_KEY}

acme.env

# The yml only references the variable; its value lives here, never in the yml.
CLAUDE_CODE_API_KEY=sk-ant-...

Tip

Leave apiKey empty to use your Claude subscription via OAuth (log in once; it persists). Set it to run in API-key mode. The value lives in acme.env, not the yml - see Workbench configuration.

Permission mode

permissionMode sets how Claude asks for approval before acting. Monoceros writes it into the container’s ~/.claude/settings.json on each apply, so the yml stays the source of truth.

Value	Behaviour
auto (default)	Auto Mode: no approval prompt before each action, and no recurring warning - a background classifier vets actions. The low-friction default, reasonable because the container is the isolation boundary.
ask	Claude prompts before edits and commands, as it does by default outside Monoceros.
edits	Auto-accepts file edits, still prompts for other commands (e.g. shell).
bypass	Skips all approval prompts. Its one-time “accept responsibility” warning is pre-accepted so it never interrupts.

Note

You can still switch modes inside a session with Shift+Tab, or override per invocation with a flag. permissionMode only sets the default the container starts with.

Plugins

Claude Code plugins package skills, slash commands and MCP servers. Name the ones you want in the yml and every container comes up with them installed, instead of you running the two /plugin commands after each rebuild.

features:
  - ref: ghcr.io/getmonoceros/monoceros-features/claude-code:1
    options:
      permissionMode: auto
    plugins:
      - url: https://github.com/acme/claude-plugins.git
        enable:
          - acme-conventions

Every workbench with the feature already carries this block commented out, so you uncomment it and put your own marketplace in.

Field	Meaning
url	Full HTTPS address of the marketplace repository, the same form repos: uses.
path	Instead of url, for a marketplace in your workspace: projects/<folder>.
provider	Only for hosts other than github.com, gitlab.com and bitbucket.org, so Monoceros knows which token applies: gitlab, github, bitbucket.
enable	The plugins to install. Required, because a marketplace often holds several.

On monoceros apply Monoceros registers the marketplace and installs those plugins inside the container, using Claude Code’s own plugin commands. If the marketplace is already there from an earlier apply, it pulls it again and updates the plugins, so a fix someone pushes reaches you without any extra step.

A private marketplace needs the same access token as a private repository, and apply says so before it builds anything. See Git and repos.

Note

Plugins are not pinned to a version, like the tools a feature installs. Every apply takes what the marketplace’s default branch has at that moment. See Reproducibility and upgrades.

What you get

The claude command on PATH in the container, ready to run via monoceros run or inside a monoceros shell. On apply Monoceros also writes a CLAUDE.md stack briefing at the workspace root, so the agent knows the real stack (languages, services, tools) without per-session setup.