Model Profiles Plugin

The Model Profiles plugin lets authenticated users define their own named LLM profiles (model id, base URL, API key, thinking options) and assign them to specific agent roles — overriding which model each role uses for that user's turns. Deployers control whether users may bring their own API keys and which endpoints are allowed.

Configuration

plugins:
  - module: codumentor.plugins.model_profiles
    class: ModelProfilesPlugin
    priority: 5
    args:
      enabled: true
      allow_custom_api_keys: true
      max_profiles_per_user: 20
      # allowed_base_urls: ["https://openrouter.ai/api/v1"]

Parameters

• enabled (optional): Whether the plugin is active (default: true)
• allow_custom_api_keys (optional): Allow users to store their own API keys in profiles; when false, users can only use deployer-defined profiles (default: true)
• allowed_base_urls (optional): Allow-list of permitted endpoint base URLs; null/empty allows any (default: null)
• max_profiles_per_user (optional): Maximum profiles per user (default: 20)
• data_dir (optional): Where profile data is stored; defaults to the agent storage dir, else ./data
• previous_jwt_secrets (optional): Older JWT secrets, so profiles encrypted under a rotated key can still be decrypted

How It Works

The plugin exposes no agent tools. Instead it:

• adds per-user model selection through a web settings panel (and a matching TUI pane) plus a REST API for CRUD on profiles and role assignments;
• registers an onContextReady hook that applies the user's profile overrides at the start of each turn, and an onResponsePersist hook that clears them afterwards.

Profiles can be assigned to known roles such as subagent, explore, agentic_developer, web_retrieve, web_search, context_summarization, and goal. Deployers can also define read-only admin profiles in models.profiles, which users may "adopt" by supplying their own key.

Notes

• Encryption at rest: API keys are encrypted with a key derived from auth.jwt_secret (see User Secrets for the shared encryption story). Without a configured secret, keys fall back to plaintext.
• Access to the management API is gated by the model_profiles:manage permission, and overrides apply only to authenticated users.
• A built-in test endpoint sends a tiny completion to verify a profile's endpoint, model, and key before you rely on it.
• This is the per-user counterpart to the deployer-level models.profiles block in the main configuration.