Plugins in Production

Most of what a real Codumentor deployment does — workspace isolation, web search, the Office editors, scheduled goals, external coding agents, per-user secrets — comes from plugins. A production config typically enables a dozen or more.

This page is the operator's view: which plugins need something installed on the host or configured outside codumentor.yaml, and how to provide it. It is not the full catalog.

For the list of every built-in plugin and the YAML to enable one, see Setup → Plugins.
For per-plugin configuration and behaviour, see the Plugin Catalog.
For the trust model (plugins run unsandboxed, with full process access), see Security → Plugin Security.

Enabling a plugin is always the same: add a {module, class, args} entry to the plugins: list. The work below is the extra setup some plugins need to actually function.

Prerequisites at a glance

Plugin(s)	What the admin must provide	How
`workspace_isolation`, `branch_switching`, `scm_push`, `external_agent` (sandbox tier ≥ 1), isolated subagents	Linux + bubblewrap with overlay support + overlayfs + (Ubuntu 24.04+) an AppArmor profile	Workspace isolation prerequisites below
`mermaid_render`, `webretrieve` (JS rendering)	Playwright + a Chromium browser binary	`pip install playwright && playwright install chromium`
`ripgrep`	The `rg` binary on `PATH`	`apt install ripgrep` (or your distro's package)
`svn`	A Subversion client	`apt install subversion`
`database`	DB access. Native pure-Python drivers ship bundled (`pg8000`, `PyMySQL`, `oracledb`, `python-tds`). Only `mode: cli` (or `mode: auto` with no driver) needs an external client	`psql` / `mysql` / `go-sqlcmd` per engine
`read_aloud` (and Telegram voice)	An OpenAI-compatible STT/TTS endpoint + API key via the top-level `speech:` block	Speech (read-aloud / voice) below
`websearch`	A search-provider API key (Tavily, Brave, Serper, Google CSE, …)	`provider_config.api_key: "${TAVILY_API_KEY}"`
`external_agent`	The external CLI binaries installed and logged in (`claude`, `codex`, …)	Install each CLI, then run its login as the service user so the auth store lands in `$HOME` (e.g. `claude /login`, `codex login`)
`redmine`, `bug_report`	A reachable Redmine instance + API key	`redmine`: each user stores a `redmine_api_key` secret; `bug_report`: instance `api_key` in config
`user_secrets`, `model_profiles`, `oauth`	`auth.jwt_secret` set, or these stores are written unencrypted	Authentication → jwt_secret
`goals`, `scheduler_tools`	The scheduler + job queue (enabled by default)	`scheduler.enabled: true` (default); see Configuration → scheduler
`doc_editor`, `xlsx_editor`, `pptx_editor`, `filesync` (SMB/UNC)	Nothing extra — `python-docx`, `openpyxl`, `python-pptx`, `smbprotocol` ship in `requirements.txt`	—

Portable/frozen builds: the bundled Python dependencies above are included in the executable. Host binaries (bubblewrap, ripgrep, svn, Chromium, DB CLIs) and the external coding-agent CLIs are not bundled — install them on the host regardless of how you run Codumentor.

Workspace isolation prerequisites

The workspace_isolation plugin sandboxes each conversation in a per-session bubblewrap overlay filesystem. The scm_push and external_agent (tier ≥ 1) plugins, and subagents under subagent_isolation: isolated, all run inside this same sandbox — so these requirements apply to all of them.

Requirement	Minimum	Notes
OS	Linux	Ubuntu 22.04+ / Debian 12+ recommended. (No Windows/macOS host sandbox.)
Kernel	5.11+	For unprivileged overlayfs
bubblewrap	0.8.0+	Must be compiled with overlay support
AppArmor	—	Needs a profile if `apparmor_restrict_unprivileged_userns=1` (Ubuntu 24.04+)

1. Check what you have

# Overlay support is the part most distro packages are missing:
bwrap --help | grep overlay      # no output → your bwrap lacks overlay support

# Convenience checker shipped with the plugin:
./src/codumentor/plugins/workspace_isolation/setup/check.sh

2. Install / build if needed

Most distributions ship bubblewrap without overlay support, so you usually have to build 0.8.0+ from source (the helper script automates it):

./src/codumentor/plugins/workspace_isolation/setup/setup.sh

On Ubuntu 24.04+, unprivileged user namespaces are restricted by AppArmor. bubblewrap relies on them, so the setup script installs an AppArmor profile at /etc/apparmor.d/bwrap that allows userns for the bwrap binary. (If you build bwrap to a different path, update the profile to match.)

3. Enable it

plugins:
  - module: codumentor.plugins.workspace_isolation
    class: WorkspaceIsolationPlugin
    priority: 5
    args:
      enabled: true
      persistent_home: true        # shared $HOME across agents (default)
      subagent_isolation: shared   # "shared" (default) or "isolated"
      snapshots:
        upper_dir_ttl: 2592000     # 30 d — writable overlay layer lifetime
        cleanup_interval: 3600     # sweep cadence (0 = startup only)
        min_free_gb: 5             # disk-pressure backstop
      sandbox:
        unshare_net: true         # block networking inside the sandbox (default)

See Configuration → Workspace Isolation Plugin for the full option table.

Speech (read-aloud / voice)

read_aloud (the "🔊 read aloud" message action) and Telegram voice replies share one top-level speech: block pointing at an OpenAI-compatible speech service:

speech:
  enabled: true
  base_url: "https://api.openai.com/v1"
  api_key: "${OPENAI_API_KEY}"
  tts_model: "tts-1"
  tts_voice: "alloy"

The read-aloud action lights up only when enabled: true and api_key resolves to a real value through an environment variable. A per-user ${secret:...} key will not work here, because the web read-aloud call runs outside an agent turn (where per-user secrets are resolved). Without a resolvable key the action renders disabled with an explanatory note.

External coding agents (`external_agent`)

Each configured backend (claude-code, codex, …) is a separate CLI that the main agent can delegate to. Two things must be true for a backend to work:

The CLI binary is installed and on PATH for the service user (binary: defaults to claude, codex, opencode, gemini).
A credential resolves at spawn time — otherwise the call is rejected, not spawned. How the credential is sourced depends on mode:

technical_user — one deployer credential shared by all callers. Either set api_key (supports ${env:VAR} / ${secret:NAME}), or omit it and let the CLI use its own auth store under $HOME. For the omit case you must log in once as the service user so that store exists:

``bash # as the user the Codumentor process runs as: claude /login # populates ~/.claude codex login # populates ~/.codex``

byo_subscription — each end user authenticates their own CLI subscription (OAuth) into a per-user $HOME; no shared deployer credential.

Sandbox tier. default_sandbox_tier (and per-backend overrides) sets isolation: tier 0 runs the CLI as a plain subprocess; tier 1 wraps it in a bubblewrap overlay (repo read-only, copy-on-write) and can enforce memory/wall-clock limits via user-level systemd-run plus a network egress allow-list. Tier 1 needs bubblewrap — see Workspace isolation prerequisites. When workspace_isolation runs with persistent_home: true, that shared $HOME is what external agents see, so a one-time login persists across sessions.