Runtime Configuration

Structure

The configuration is structured as follows:

• auths (object, optional): Authentication configurations for HTTPS requests, keyed by URL.
• dynamic_loading (bool, optional, default: false): Enable dynamic plugin loading and unloading at runtime. When enabled, two built-in tools are exposed: hyper_mcp-load_plugin and hyper_mcp-unload_plugin. Can also be set via the --dynamic-loading CLI flag or the HYPER_MCP_DYNAMIC_LOADING environment variable (CLI/env takes precedence over the config file).
• plugins: A map of plugin names to plugin configuration objects.
  • path (string): OCI path or HTTP URL or local path for the plugin.
  • description (string, optional): A human-readable description of the plugin. This is for documentation purposes only and has no effect on plugin behavior.
  • runtime_config (object, optional): Plugin-specific runtime configuration. The available fields are:
    • skip_tools (array[string], optional): List of regex patterns for tool names to skip loading at runtime. Each pattern is automatically anchored to match the entire tool name (equivalent to wrapping with ^ and $). Supports full regex syntax for powerful pattern matching.
    • allowed_hosts (array[string], optional): List of allowed hosts for the plugin (e.g., ["1.1.1.1"] or ["*"]).
    • allowed_paths (array[string], optional): List of allowed file system paths. Supports both simple paths and host-to-plugin path mapping. See Allowed Paths Configuration for detailed documentation.
    • allowed_secrets (array[object], optional): List of allowed keyring entries that the plugin can access. Each entry specifies a service and user name. See Allowed Secrets Configuration for detailed documentation.
    • env_vars (object, optional): Key-value pairs of environment variables for the plugin.
    • memory_limit (string, optional): Memory limit for the plugin (e.g., "512Mi").

Environment Variable Expansion

Config files support environment variable expansion using the ${VAR} syntax. Expansion happens before the file is parsed, so it works identically across JSON, YAML, and TOML configs.

Syntax

Pattern	Behaviour
${VAR}	Replaced with the value of the environment variable VAR. An error is raised if the variable is unset or empty.
${VAR:-default}	Replaced with the value of VAR, or default if the variable is unset or empty.
$${VAR}	Escape hatch — produces the literal text ${VAR} (no expansion).
$VAR	Not expanded. Left as-is. This is intentional so that regex patterns in skip_tools (which use $ for end-of-string anchors) are not affected.

Variable names must match [A-Za-z_][A-Za-z0-9_]*.

Examples

YAML:

plugins:
  my_plugin:
    url: "file://${HOME}/plugins/my-plugin.wasm"
    runtime_config:
      env_vars:
        API_KEY: "${API_KEY}"
        REGION: "${AWS_REGION:-us-east-1}"

JSON:

{
  "plugins": {
    "my_plugin": {
      "url": "file://${HOME}/plugins/my-plugin.wasm",
      "runtime_config": {
        "env_vars": {
          "API_KEY": "${API_KEY}",
          "REGION": "${AWS_REGION:-us-east-1}"
        }
      }
    }
  }
}

TOML:

[plugins.my_plugin]
url = "file://${HOME}/plugins/my-plugin.wasm"

[plugins.my_plugin.runtime_config.env_vars]
API_KEY = "${API_KEY}"
REGION = "${AWS_REGION:-us-east-1}"

Producing a literal ${...}

If you need the literal text ${VAR} in a config value (for example, a template string that should not be expanded), double the leading $:

env_vars:
  TEMPLATE: "$${NOT_EXPANDED}"   # Value will be: ${NOT_EXPANDED}

Error behaviour

If a ${VAR} reference (without a default) points to an undefined or empty environment variable, hyper-mcp will refuse to start and print an error listing all missing variables. This prevents silent misconfiguration.

To make a variable optional, always provide a default:

url: "${PLUGIN_PATH:-file:///usr/local/share/hyper-mcp/default-plugin.wasm}"

Plugin Names

Plugin names must follow strict naming conventions to ensure consistency and avoid conflicts:

Allowed Characters

• Letters: A-Z, a-z (case-sensitive)
• Numbers: 0-9
• Underscores: _ (as separators only)

Naming Rules

• Must start with a letter or number (not underscore)
• Must end with a letter or number (not underscore)
• Cannot contain consecutive underscores
• Cannot contain hyphens or other special characters
• Cannot contain spaces or whitespace

Valid Examples

✅ plugin
✅ myPlugin
✅ plugin_name
✅ plugin123
✅ my_awesome_plugin_v2
✅ Plugin_Name_123

Invalid Examples

❌ plugin-name        (hyphens not allowed)
❌ plugin_            (cannot end with underscore)
❌ _plugin            (cannot start with underscore)
❌ plugin__name       (consecutive underscores)
❌ plugin name        (spaces not allowed)
❌ plugin@name        (special characters not allowed)

Best Practices

• Use descriptive, meaningful names
• Follow consistent naming conventions within your organization
• Consider using prefixes for related plugins (e.g., company_auth, company_logging)
• Use underscores to separate logical components (e.g., api_client, data_processor)

Authentication Configuration

The auths field allows you to configure authentication for HTTPS requests made by plugins. Authentication is matched by URL prefix, with longer prefixes taking precedence.

Supported Authentication Types

Basic Authentication

auths:
  "https://api.example.com":
    type: basic
    username: "your-username"
    password: "your-password"

Bearer Token Authentication

auths:
  "https://api.example.com":
    type: token
    token: "your-bearer-token"

Keyring Authentication

auths:
  "https://private.registry.io":
    type: keyring
    service: "my-app"
    user: "registry-user"

Keyring Setup Examples

For keyring authentication, you need to store the actual auth configuration JSON in your system keyring. This provides secure credential storage without exposing sensitive data in config files.

macOS (using Keychain Access or security command)

Using the security command:

# Store basic auth credentials
security add-generic-password -a "registry-user" -s "my-app" -w '{"type":"basic","username":"actual-user","password":"actual-pass"}'

# Store token auth credentials
security add-generic-password -a "api-user" -s "my-service" -w '{"type":"token","token":"actual-bearer-token"}'

# Verify the entry was created
security find-generic-password -a "registry-user" -s "my-app"

Using Keychain Access GUI:

1. Open Keychain Access (Applications → Utilities → Keychain Access)
2. Click "File" → "New Password Item"
3. Set "Keychain Item Name" to your service name (e.g., "my-app")
4. Set "Account Name" to your user name (e.g., "registry-user")
5. Set "Password" to the JSON auth config: {"type":"basic","username":"actual-user","password":"actual-pass"}
6. Click "Add"

Linux (using libsecret/gnome-keyring)

Install required tools:

# Ubuntu/Debian
sudo apt-get install libsecret-tools

# RHEL/CentOS/Fedora
sudo yum install libsecret-devel

Using secret-tool:

# Store basic auth credentials
echo '{"type":"basic","username":"actual-user","password":"actual-pass"}' | secret-tool store --label="my-app credentials" service "my-app" username "registry-user"

# Store token auth credentials
echo '{"type":"token","token":"actual-bearer-token"}' | secret-tool store --label="my-service token" service "my-service" username "api-user"

# Verify the entry was created
secret-tool lookup service "my-app" username "registry-user"

Windows (using Windows Credential Manager)

Using cmdkey (Command Prompt as Administrator):

REM Store basic auth credentials (escape quotes for JSON)
cmdkey /generic:"my-app" /user:"registry-user" /pass:"{\"type\":\"basic\",\"username\":\"actual-user\",\"password\":\"actual-pass\"}"

REM Store token auth credentials
cmdkey /generic:"my-service" /user:"api-user" /pass:"{\"type\":\"token\",\"token\":\"actual-bearer-token\"}"

REM Verify the entry was created
cmdkey /list:"my-app"

Using Credential Manager GUI:

1. Open "Credential Manager" from Control Panel → User Accounts → Credential Manager
2. Click "Add a generic credential"
3. Set "Internet or network address" to your service name (e.g., "my-app")
4. Set "User name" to your user name (e.g., "registry-user")
5. Set "Password" to the JSON auth config: {"type":"basic","username":"actual-user","password":"actual-pass"}
6. Click "OK"

Using PowerShell:

# Store basic auth credentials
$cred = New-Object System.Management.Automation.PSCredential("registry-user", (ConvertTo-SecureString '{"type":"basic","username":"actual-user","password":"actual-pass"}' -AsPlainText -Force))
New-StoredCredential -Target "my-app" -Credential $cred -Type Generic

URL Matching Behavior

Authentication is applied based on URL prefix matching:

• Longer prefixes take precedence over shorter ones
• Exact matches take highest precedence
• URLs are matched case-sensitively

Example:

auths:
  "https://example.com":
    type: basic
    username: "broad-user"
    password: "broad-pass"
  "https://example.com/api":
    type: token
    token: "api-token"
  "https://example.com/api/v1":
    type: basic
    username: "v1-user"
    password: "v1-pass"

• Request to https://example.com/api/v1/users → uses v1 basic auth (longest match)
• Request to https://example.com/api/data → uses api token auth
• Request to https://example.com/public → uses broad basic auth

Keyring Authentication Example

Configuration file:

auths:
  "https://private.registry.io":
    type: keyring
    service: "private-registry"
    user: "registry-user"
  "https://internal.company.com":
    type: keyring
    service: "company-api"
    user: "api-user"

plugins:
  secure-plugin:
    url: "https://private.registry.io/secure-plugin"
    runtime_config:
      allowed_hosts:
        - "private.registry.io"

Corresponding keyring entries (stored separately):

• Service: private-registry, User: registry-user, Password: {"type":"basic","username":"real-user","password":"real-pass"}
• Service: company-api, User: api-user, Password: {"type":"token","token":"company-jwt-token"}

Real-World Keyring Scenarios

Scenario 1: Corporate Environment

auths:
  "https://artifactory.company.com":
    type: keyring
    service: "company-artifactory"
    user: "build-service"
  "https://nexus.company.com":
    type: keyring
    service: "company-nexus"
    user: "deployment-bot"

Setup corporate credentials once:

# macOS
security add-generic-password -a "build-service" -s "company-artifactory" -w '{"type":"basic","username":"corp_user","password":"corp_secret"}'

# Linux
echo '{"type":"basic","username":"corp_user","password":"corp_secret"}' | secret-tool store --label="Company Artifactory" service "company-artifactory" username "build-service"

# Windows
cmdkey /generic:"company-artifactory" /user:"build-service" /pass:"{\"type\":\"basic\",\"username\":\"corp_user\",\"password\":\"corp_secret\"}"

Scenario 2: Multi-Environment Setup

auths:
  "https://staging-api.example.com":
    type: keyring
    service: "example-staging"
    user: "staging-user"
  "https://prod-api.example.com":
    type: keyring
    service: "example-prod"
    user: "prod-user"

Store different credentials for each environment:

# Staging credentials
security add-generic-password -a "staging-user" -s "example-staging" -w '{"type":"token","token":"staging-jwt-token"}'

# Production credentials
security add-generic-password -a "prod-user" -s "example-prod" -w '{"type":"token","token":"prod-jwt-token"}'

Scenario 3: Team Shared Configuration

# Team members can share this config file safely
auths:
  "https://shared-registry.team.com":
    type: keyring
    service: "team-registry"
    user: "developer"

Each team member stores their own credentials:

# Developer A
security add-generic-password -a "developer" -s "team-registry" -w '{"type":"basic","username":"alice","password":"alice_key"}'

# Developer B
security add-generic-password -a "developer" -s "team-registry" -w '{"type":"basic","username":"bob","password":"bob_key"}'

Keyring Best Practices

1. Service Naming Convention: Use descriptive, consistent service names (e.g., company-artifactory, project-registry)
2. User Identification: Use role-based usernames (e.g., build-service, deployment-bot) rather than personal names
3. Credential Rotation: Update keyring entries when rotating credentials - no config file changes needed
4. Environment Separation: Use different service names for different environments
5. Team Coordination: Document your service/user naming conventions for team members
6. Backup Strategy: Consider backing up keyring entries for critical services
7. Testing: Use non-production credentials in keyring for testing

Dynamic Loading

When dynamic_loading is set to true, hyper-mcp exposes two additional built-in tools that allow MCP clients to manage plugins at runtime:

• hyper_mcp-load_plugin: Dynamically loads a new plugin into the current session. Accepts a plugin name and a full config object (with url and optional runtime_config).
• hyper_mcp-unload_plugin: Dynamically unloads an existing plugin from the current session by name. The plugin is removed from both the active plugin set and the running configuration.

After a plugin is loaded or unloaded, hyper-mcp automatically notifies the MCP client that the tool, resource, and prompt lists have changed.

Enabling Dynamic Loading

Dynamic loading can be enabled (or disabled) in three ways (in order of precedence):

1. CLI flag: --dynamic-loading true
2. Environment variable: HYPER_MCP_DYNAMIC_LOADING=true
3. Config file:

dynamic_loading: true

plugins:
  time:
    url: oci://ghcr.io/hyper-mcp-rs/time-plugin:latest

{
  "dynamic_loading": true,
  "plugins": {
    "time": {
      "url": "oci://ghcr.io/hyper-mcp-rs/time-plugin:latest"
    }
  }
}

Security Considerations

• Dynamic loading is disabled by default to follow the principle of least privilege.
• When enabled, any MCP client connected to the session can load arbitrary plugins or unload existing ones.
• Only enable dynamic loading in trusted environments or when the MCP client is expected to manage plugins.

Example (YAML)

auths:
  "https://private.registry.io":
    type: basic
    username: "registry-user"
    password: "registry-pass"
  "https://api.github.com":
    type: token
    token: "ghp_1234567890abcdef"
  "https://enterprise.api.com":
    type: basic
    username: "enterprise-user"
    password: "enterprise-pass"

dynamic_loading: true

plugins:
  time:
    url: oci://ghcr.io/hyper-mcp-rs/time-plugin:latest
    description: "Get current time and do time calculations"
  myip:
    url: oci://ghcr.io/hyper-mcp-rs/myip-plugin:latest
    description: "Get your current public IP address"
    runtime_config:
      allowed_hosts:
        - "1.1.1.1"
      allowed_paths:
        - "/tmp"                      # Single path (same for host and plugin)
        - "/var/log:/plugin/logs"     # Mapped path (host:plugin)
        - "/home/user/data"           # Another single path
      allowed_secrets:
        - service: "my-app"
          user: "admin"
        - service: "database"
          user: "db_user"
      skip_tools:
        - "debug_tool"           # Skip exact tool name
        - "temp_.*"              # Skip tools starting with "temp_"
        - ".*_backup"            # Skip tools ending with "_backup"
        - "test_[0-9]+"          # Skip tools like "test_1", "test_42"
      env_vars:
        FOO: "bar"
      memory_limit: "512Mi"
  private_plugin:
    url: "https://private.registry.io/my-plugin"
    description: "A plugin loaded from a private registry"
    runtime_config:
      allowed_hosts:
        - "private.registry.io"
      allowed_secrets:
        - service: "private-registry"
          user: "auth-token"

Example (JSON)

{
  "dynamic_loading": true,
  "auths": {
    "https://private.registry.io": {
      "type": "basic",
      "username": "registry-user",
      "password": "registry-pass"
    },
    "https://api.github.com": {
      "type": "token",
      "token": "ghp_1234567890abcdef"
    },
    "https://enterprise.api.com": {
      "type": "basic",
      "username": "enterprise-user",
      "password": "enterprise-pass"
    }
  },
  "plugins": {
    "time": {
      "url": "oci://ghcr.io/hyper-mcp-rs/time-plugin:latest",
      "description": "Get current time and do time calculations"
    },
    "myip": {
      "url": "oci://ghcr.io/hyper-mcp-rs/myip-plugin:latest",
      "description": "Get your current public IP address",
      "runtime_config": {
        "allowed_hosts": ["1.1.1.1"],
        "allowed_paths": [
          "/tmp",
          "/var/log:/plugin/logs",
          "/home/user/data"
        ],
        "allowed_secrets": [
          {
            "service": "my-app",
            "user": "admin"
          }
        ],
        "skip_tools": [
          "debug_tool",
          "temp_.*",
          ".*_backup",
          "test_[0-9]+"
        ],
        "env_vars": {"FOO": "bar"},
        "memory_limit": "512Mi"
      }
    },
    "private_plugin": {
      "url": "https://private.registry.io/my-plugin",
      "description": "A plugin loaded from a private registry",
      "runtime_config": {
        "allowed_hosts": ["private.registry.io"]
      }
    }
  }
}

Loading Configuration

Configuration is loaded at runtime from a file with .json, .yaml, .yml, or .toml extension. The loader will parse the file according to its extension. If the file does not exist or the format is unsupported, an error will be raised.

Security Considerations

Credential Storage

• Basic/Token auth: Credentials are stored directly in the config file. Ensure proper file permissions (e.g., chmod 600).
• Keyring auth: Credentials are stored securely in the system keyring. The config file only contains service/user identifiers.

Best Practices

• Use keyring authentication for production environments
• Rotate credentials regularly
• Use environment-specific config files
• Never commit credentials to version control
• Consider using short-lived tokens when possible

Troubleshooting Keyring Authentication

Common Issues

"No matching entry found in secure storage"

This error occurs when the keyring entry doesn't exist or can't be accessed.

Solutions:

1. Verify the service and user names match exactly between config and keyring
2. Check that the keyring entry exists:

   # macOS
   security find-generic-password -a "your-user" -s "your-service"
   
   # Linux
   secret-tool lookup service "your-service" username "your-user"
   
   # Windows
   cmdkey /list:"your-service"
   

3. Ensure the current user has permission to access the keyring entry

"Failed to parse JSON from keyring"

This error occurs when the stored password isn't valid JSON or doesn't match the expected AuthConfig format.

Solutions:

1. Verify the stored password is valid JSON:

   # macOS - retrieve and validate
   security find-generic-password -a "your-user" -s "your-service" -w | jq .
   

2. Ensure the JSON matches one of these formats:
   • {"type":"basic","username":"real-user","password":"real-pass"}
   • {"type":"token","token":"real-token"}

Platform-Specific Issues

macOS:

• Keychain may be locked - unlock it manually or use security unlock-keychain
• Application may not have keychain access permissions

Linux:

• GNOME Keyring service may not be running: systemctl --user status gnome-keyring
• D-Bus session may not be available in non-graphical environments

Windows:

• Credential Manager may require administrator privileges for certain operations
• Windows Credential Manager has size limits for stored passwords

Debugging Tips

1. Test keyring access independently:

   # Create a test entry
   security add-generic-password -a "test-user" -s "test-service" -w '{"type":"token","token":"test"}'
   
   # Retrieve it
   security find-generic-password -a "test-user" -s "test-service" -w
   
   # Clean up
   security delete-generic-password -a "test-user" -s "test-service"
   

2. Validate JSON format:

   echo '{"type":"basic","username":"user","password":"pass"}' | jq .
   

3. Check permissions:

   # Ensure config file is readable
   ls -la config.yaml
   
   # Set appropriate permissions
   chmod 600 config.yaml
   

Skip Tools Pattern Matching

The skip_tools field supports powerful regex pattern matching for filtering out unwanted tools at runtime.

📖 For comprehensive examples, advanced patterns, and detailed use cases, see SKIP_TOOLS_GUIDE.md

Pattern Behavior

• Automatic Anchoring: Patterns are automatically anchored to match the entire tool name (wrapped with ^ and $)
• Regex Support: Full regex syntax is supported, including wildcards, character classes, and quantifiers
• Case Sensitive: Pattern matching is case-sensitive
• Compilation: All patterns are compiled into a single optimized regex set for efficient matching

Pattern Examples

Exact Matches

skip_tools:
  - "debug_tool"      # Matches only "debug_tool"
  - "test_runner"     # Matches only "test_runner"

Wildcard Patterns

skip_tools:
  - "temp_.*"         # Matches "temp_file", "temp_data", etc.
  - ".*_backup"       # Matches "data_backup", "file_backup", etc.
  - "debug.*"         # Matches "debug", "debugger", "debug_info", etc.

Advanced Regex Patterns

skip_tools:
  - "tool_[0-9]+"                    # Matches "tool_1", "tool_42", etc.
  - "test_(unit|integration)"        # Matches "test_unit" and "test_integration"
  - "[a-z]+_helper"                  # Matches lowercase word + "_helper"
  - "system_(admin|user)_.*"         # Matches tools starting with "system_admin_" or "system_user_"

Explicit Anchoring

skip_tools:
  - "^prefix_.*"      # Explicit start anchor (same as "prefix_.*" due to auto-anchoring)
  - ".*_suffix$"      # Explicit end anchor (same as ".*_suffix" due to auto-anchoring)
  - "^exact_only$"    # Fully explicit anchoring (same as "exact_only")

Special Characters

skip_tools:
  - "file\\.exe"      # Matches "file.exe" literally (escaped dot)
  - "script\\?"       # Matches "script?" literally (escaped question mark)
  - "temp\\*data"     # Matches "temp*data" literally (escaped asterisk)

Common Use Cases

skip_tools:
  - ".*_test"         # Skip all test tools
  - "dev_.*"          # Skip all development tools
  - "mock_.*"         # Skip all mock tools
  - ".*_deprecated"   # Skip all deprecated tools
  - "admin_.*"        # Skip all admin tools
  - "debug.*"         # Skip all debug-related tools

Error Handling

• Invalid regex patterns will cause configuration loading to fail with a descriptive error
• Empty pattern arrays are allowed and will skip no tools
• The skip_tools field can be omitted entirely to skip no tools

Performance Notes

• All patterns are compiled into a single optimized RegexSet for O(1) tool name checking
• Pattern compilation happens once at startup, not per tool evaluation
• Large numbers of patterns have minimal runtime performance impact

Allowed Paths Configuration

The allowed_paths field provides fine-grained control over filesystem access for plugins. It supports both simple paths and sophisticated host-to-plugin path mapping, enabling secure isolation while maintaining flexibility.

Host Path Existence and Auto-Creation

When hyper-mcp parses an allowed_paths entry, it inspects the host side of the mapping (the part before the : on Unix or ; on Windows):

• If the host path already exists, it is accepted as-is. Existing files are left untouched; existing directories are not modified.
• If the host path does not exist, hyper-mcp will create it as a directory (recursively, equivalent to mkdir -p) before continuing.
• If the host path cannot be created (for example, because a parent component is an existing regular file, or the process lacks permission to create it), the configuration fails to load with an error of the form host path <path> does not exist and could not be created: <reason>.

This means it is safe to point allowed_paths at directories that do not yet exist on a fresh checkout (e.g. project-local cache or scratch directories) — they will be materialized on startup.

Note that only the host side is created. The plugin side of a mapped entry is an opaque label inside the WASM sandbox and is never created on the host filesystem.

Path Format

Paths can be specified in two formats:

1. Simple Path Format

When the same path should be accessible to both the host and plugin:

allowed_paths:
  - "/tmp"
  - "/home/user/data"
  - "./relative/path"

2. Mapped Path Format

When you want to map a host filesystem path to a different path as seen by the plugin:

Unix/Linux/macOS (using : as separator):

allowed_paths:
  - "/host/path:/plugin/path"
  - "/var/log:/plugin/logs"
  - "/home/user/data:/plugin/user/data"

Windows (using ; as separator):

allowed_paths:
  - "C:\\host\\path;C:\\plugin\\path"
  - "C:\\logs;C:\\plugin\\logs"

Platform-Specific Separators

The separator used for path mapping is platform-dependent:

• Unix/Linux/macOS: Colon (:) - e.g., "/host/path:/plugin/path"
• Windows: Semicolon (;) - e.g., "C:\\host\\path;C:\\plugin\\path"

This ensures compatibility with Windows drive letters (which contain colons) and Unix absolute paths.

Path Mapping Examples

Basic Mapping

allowed_paths:
  - "/tmp"                           # Plugin sees /tmp at /tmp
  - "/var/log:/plugin/logs"          # Host /var/log appears as /plugin/logs to plugin
  - "/home/user/data"                # Plugin sees /home/user/data at /home/user/data

Relative Paths

allowed_paths:
  - "./local/data"                   # Relative to current directory
  - "../shared/files"                # Parent directory reference
  - "./host/config:./plugin/config"  # Mapped relative paths

Windows Paths

allowed_paths:
  - "C:\\Users\\Public"              # Simple Windows path
  - "C:\\app\\data;C:\\plugin\\data" # Mapped Windows path
  - "\\\\server\\share"              # UNC network path
  - "C:\\logs;D:\\plugin\\logs"      # Map between different drives

Home Directory Expansion

allowed_paths:
  - "~/Documents"                    # User home directory
  - "~/host/config:~/plugin/config"  # Mapped home directories

Complex Scenarios

allowed_paths:
  # Root and system paths
  - "/"                              # Root directory (use with caution!)
  - "/usr/local/share:/plugin/share"
  
  # Application-specific paths
  - "/opt/myapp/data:/plugin/data"
  - "/etc/myapp/config:/plugin/config"
  
  # Paths with special characters
  - "/path/with spaces"
  - "/path-with-dashes"
  - "/path_with_underscores"
  - "/path.with.dots"
  
  # Deeply nested structures
  - "/very/deeply/nested/path/structure"

Whitespace Handling

Whitespace around paths is automatically trimmed:

allowed_paths:
  - "  /tmp  "                       # Treated as "/tmp"
  - "  /var/log  :  /plugin/logs  "  # Treated as "/var/log:/plugin/logs"

Empty Plugin Path Behavior

If the plugin path is empty or contains only whitespace after the separator, the host path is used for both:

allowed_paths:
  - "/tmp:"          # Equivalent to "/tmp" (plugin path defaults to host path)
  - "/var/log:  "    # Equivalent to "/var/log" (whitespace-only plugin path)

Multiple Colons/Semicolons

Only the first separator is used to split the mapping. This allows paths to contain additional colons or semicolons:

Unix:

allowed_paths:
  - "/host/path:/plugin/path:with:colons"  # Host: "/host/path", Plugin: "/plugin/path:with:colons"

Windows:

allowed_paths:
  - "C:\\host;C:\\plugin;data"  # Host: "C:\host", Plugin: "C:\plugin;data"

Use Cases

1. Read-Only Configuration Access

runtime_config:
  allowed_paths:
    - "/etc/myapp/config:/plugin/config"

Host configuration at /etc/myapp/config appears to the plugin at /plugin/config.

2. Isolated Data Directories

runtime_config:
  allowed_paths:
    - "/var/lib/myapp/plugin1:/plugin/data"

Each plugin gets its own isolated data directory mapped to a standard location.

3. Multi-Environment Setup

runtime_config:
  allowed_paths:
    - "/opt/production/data:/plugin/data"    # Production
    # - "/opt/staging/data:/plugin/data"     # Staging (commented out)
    # - "/opt/dev/data:/plugin/data"         # Development (commented out)

4. Shared Resources

runtime_config:
  allowed_paths:
    - "/tmp"                                  # Shared temp directory
    - "/usr/local/share:/plugin/shared"       # Shared libraries/resources
    - "/var/cache/myapp:/plugin/cache"        # Shared cache

5. Cross-Platform Compatibility

# Unix/Linux/macOS
allowed_paths:
  - "~/config:/plugin/config"
  - "/var/log:/plugin/logs"

# Windows equivalent
allowed_paths:
  - "C:\\Users\\username\\config;C:\\plugin\\config"
  - "C:\\logs;C:\\plugin\\logs"

Complete Example

plugins:
  file_processor:
    url: "oci://ghcr.io/myorg/file-processor:latest"
    runtime_config:
      allowed_hosts:
        - "api.example.com"
      allowed_paths:
        # Temporary workspace
        - "/tmp"
        
        # Configuration (read-only in practice)
        - "/etc/myapp/config:/plugin/config"
        
        # Input data (host path) -> Plugin working directory
        - "/var/lib/myapp/input:/plugin/input"
        
        # Output directory
        - "/var/lib/myapp/output:/plugin/output"
        
        # Logs (isolated per plugin)
        - "/var/log/myapp/file-processor:/plugin/logs"
        
        # Shared cache directory
        - "/var/cache/myapp:/plugin/cache"
      env_vars:
        PLUGIN_ENV: "production"
        LOG_LEVEL: "info"
      memory_limit: "1GB"

Security Considerations

1. Principle of Least Privilege: Only grant access to paths that the plugin absolutely needs.
2. Path Isolation: Use path mapping to isolate plugins from each other's data.
3. Avoid Root Access: Avoid granting access to / unless absolutely necessary.
4. Validate Paths: Ensure paths exist and have appropriate permissions before configuring them.
5. Use Mapping for Isolation: Map host paths to plugin-specific locations to prevent plugins from knowing the actual host filesystem structure.

Error Handling

• Invalid Format: Paths are parsed at configuration load time; invalid formats will cause startup errors.
• Missing Separators: If no separator is found, the entire string is treated as a simple path.
• Empty Paths: Empty path strings are not allowed and will cause configuration errors.

Performance Notes

• Path configuration is parsed once at startup, not during runtime operations.
• Path mapping has minimal overhead during filesystem operations.
• Large numbers of allowed paths have negligible performance impact.

Best Practices

1. Use Descriptive Mappings: Map host paths to clear, consistent plugin paths (e.g., /plugin/config, /plugin/data).
2. Document Path Purpose: Comment your path configurations to explain their purpose.
3. Group Related Paths: Organize paths by function (config, data, logs, cache).
4. Version-Aware Paths: Consider including version information in paths for easier upgrades.
5. Environment-Specific Paths: Use different path configurations for different environments (dev, staging, prod).
6. Test Path Access: Verify that plugins can actually access configured paths before deploying to production.

Allowed Secrets Configuration

The allowed_secrets field provides fine-grained control over which system keyring entries a plugin can access. This enables secure secret management by explicitly whitelisting keyring credentials that plugins are permitted to retrieve.

Purpose

Rather than allowing plugins unrestricted access to the system keyring, allowed_secrets implements a principle of least privilege by specifying exactly which keyring entries a plugin may access. This prevents plugins from accessing sensitive credentials they don't need.

Entry Format

Each entry in allowed_secrets is an object with two required fields:

allowed_secrets:
  - service: "service-name"
    user: "user-name"

• service (string, required): The service name of the keyring entry
• user (string, required): The user/account name of the keyring entry

Basic Examples

Single Secret

runtime_config:
  allowed_secrets:
    - service: "my-app"
      user: "admin"

Multiple Secrets

runtime_config:
  allowed_secrets:
    - service: "database"
      user: "db_user"
    - service: "api-service"
      user: "api_key_user"
    - service: "s3-bucket"
      user: "backup-bot"

JSON Format

{
  "runtime_config": {
    "allowed_secrets": [
      {
        "service": "my-app",
        "user": "admin"
      },
      {
        "service": "database",
        "user": "db_user"
      }
    ]
  }
}

Use Cases

1. Database Credentials

plugins:
  db_backup:
    url: "oci://ghcr.io/myorg/db-backup:latest"
    runtime_config:
      allowed_secrets:
        - service: "postgres-prod"
          user: "backup-user"
        - service: "mysql-prod"
          user: "backup-user"

The plugin can only access these specific database credentials, not other secrets in the keyring.

2. API Access

plugins:
  api_client:
    url: "oci://ghcr.io/myorg/api-client:latest"
    runtime_config:
      allowed_secrets:
        - service: "github-api"
          user: "bot-token"
        - service: "slack-api"
          user: "webhook-url"

3. Multi-Environment Credentials

plugins:
  deployment_tool:
    url: "oci://ghcr.io/myorg/deployer:latest"
    runtime_config:
      allowed_secrets:
        - service: "aws-staging"
          user: "deploy-bot"
        - service: "aws-production"
          user: "deploy-bot"
        - service: "docker-registry"
          user: "ci-system"

4. Service-Specific Access

plugins:
  monitoring:
    url: "oci://ghcr.io/myorg/monitor:latest"
    runtime_config:
      allowed_secrets:
        - service: "datadog"
          user: "api-key"
        - service: "pagerduty"
          user: "integration-key"
      
  backup:
    url: "oci://ghcr.io/myorg/backup:latest"
    runtime_config:
      allowed_secrets:
        - service: "s3-backups"
          user: "backup-bot"
        # Note: This plugin cannot access monitoring secrets

Setting Up Keyring Entries

Before a plugin can access a secret, the entry must exist in the system keyring. Here's how to create keyring entries that plugins can access:

macOS

# Add a secret that a plugin can access
security add-generic-password \
  -a "db_user" \
  -s "database" \
  -w "my-secret-password" \
  -T ""

# Verify it exists
security find-generic-password -a "db_user" -s "database"

# Delete if needed
security delete-generic-password -a "db_user" -s "database"

Linux

# Add a secret using secret-tool
echo "my-secret-password" | secret-tool store \
  --label="Database credentials" \
  service "database" \
  username "db_user"

# Verify it exists
secret-tool lookup service "database" username "db_user"

# Delete if needed
secret-tool clear service "database" username "db_user"

Windows (Command Prompt)

REM Add a secret
cmdkey /generic:"database" /user:"db_user" /pass:"my-secret-password"

REM List credentials
cmdkey /list:"database"

REM Delete if needed
cmdkey /delete:"database"

Windows (PowerShell)

# Add a secret
$password = ConvertTo-SecureString "my-secret-password" -AsPlainText -Force
$cred = New-Object System.Management.Automation.PSCredential("db_user", $password)
# Note: Requires CredentialManager module or similar

# For generic credentials, use cmdkey or Windows Credential Manager GUI

Special Characters in Service and User Names

The allowed_secrets field supports service and user names with special characters:

allowed_secrets:
  # Dots and hyphens
  - service: "my-app.production"
    user: "admin@example.com"
  
  # Underscores
  - service: "service_with_underscore"
    user: "user-with-dash"
  
  # Slashes (useful for namespacing)
  - service: "company/project/service"
    user: "deploy-key"
  
  # Dots in user names
  - service: "api-gateway"
    user: "user.name@domain.com"

Note: When creating keyring entries with special characters, ensure they are properly escaped or quoted according to your shell's requirements.

Complete Example

plugins:
  enterprise_integration:
    url: "oci://ghcr.io/myorg/enterprise-integration:v2.1"
    runtime_config:
      # Network access
      allowed_hosts:
        - "api.enterprise.com"
        - "*.internal.company.com"
      
      # Filesystem access
      allowed_paths:
        - "/var/lib/myapp/cache:/plugin/cache"
        - "/etc/myapp/config:/plugin/config"
      
      # Keyring access (whitelist specific secrets)
      allowed_secrets:
        - service: "enterprise-api"
          user: "integration-key"
        - service: "database-prod"
          user: "app-user"
        - service: "s3-artifacts"
          user: "upload-bot"
      
      # Environment configuration
      env_vars:
        ENVIRONMENT: "production"
        LOG_LEVEL: "info"
      
      # Resource limits
      memory_limit: "2GB"

Security Considerations

1. Principle of Least Privilege: Only grant access to secrets that the plugin absolutely needs. Each plugin should have its own minimal set of allowed secrets.

2. Avoid Wildcards: Unlike allowed_hosts, there is no wildcard support in allowed_secrets. Each entry must be explicitly specified, ensuring maximum security.

3. Service Naming Convention: Use consistent, descriptive service names:

   • Good: "github-api", "postgres-production", "aws-s3-backups"
   • Avoid: "api", "db", "secret1"

4. User Naming Convention: Use role-based or purpose-based user names:

   • Good: "deploy-bot", "backup-service", "ci-system"
   • Avoid: Personal names like "john", "alice"

5. Audit Secret Access: Regularly review which plugins have access to which secrets. Remove entries that are no longer needed.

6. Environment Separation: Use different service names for different environments:

   # Development
   - service: "api-dev"
     user: "test-key"
   
   # Production
   - service: "api-prod"
     user: "production-key"
   

7. Secret Rotation: When rotating secrets, only the keyring entries need to be updated—the configuration remains unchanged:

   # Update the secret in the keyring
   security add-generic-password -a "api-user" -s "my-service" -w "new-secret" -U
   
   # No config file changes needed!
   

Validation and Error Handling

Configuration Validation

• Both service and user fields are required for each entry
• Empty strings are not allowed for service or user
• Duplicate entries are allowed (though redundant)
• The allowed_secrets array itself can be empty [] (no secrets allowed)
• The allowed_secrets field can be omitted entirely (no restrictions on secret access)

Runtime Behavior

• If a plugin attempts to access a keyring entry not in allowed_secrets, the access is denied
• If an allowed keyring entry doesn't exist, the plugin receives an appropriate error
• Keyring access failures are logged for security auditing

Common Errors

"Secret not in allowed list"

• The plugin is trying to access a keyring entry that isn't whitelisted
• Solution: Add the entry to allowed_secrets if it's legitimate

"Keyring entry not found"

• The specified service/user combination doesn't exist in the system keyring
• Solution: Create the keyring entry using the appropriate platform tool

"Failed to access keyring"

• The system keyring is locked or inaccessible
• Solution: Unlock the keyring or check permissions

Performance Notes

• Secret validation is performed using hash-based lookups (O(1) complexity)
• Configuration is parsed once at startup, not during runtime
• Large numbers of allowed secrets have negligible performance impact
• Keyring access itself may have platform-specific performance characteristics

Best Practices

1. Document Secret Purpose: Add comments explaining why each secret is needed:

   allowed_secrets:
     # API authentication for external service
     - service: "external-api"
       user: "integration-token"
     
     # Database connection credentials
     - service: "postgres-prod"
       user: "app-reader"
   

2. Group by Function: Organize secrets by their purpose or system:

   allowed_secrets:
     # Database credentials
     - service: "postgres-prod"
       user: "app-user"
     - service: "redis-cache"
       user: "cache-client"
     
     # External APIs
     - service: "github-api"
       user: "bot-token"
     - service: "slack-webhook"
       user: "notifications"
   

3. Test Secret Access: Before deploying, verify that:

   • All listed secrets exist in the keyring
   • The plugin can successfully access them
   • No additional secrets are needed

4. Version Control Safety: The config file only contains service/user identifiers, never actual secrets, making it safe to commit to version control.

5. Environment-Specific Configs: Use different configurations for different environments:

   # config.dev.yaml
   allowed_secrets:
     - service: "api-dev"
       user: "test-token"
   
   # config.prod.yaml
   allowed_secrets:
     - service: "api-prod"
       user: "production-token"
   

6. Regular Audits: Periodically review and remove unnecessary secret permissions.

Notes

• Fields marked as optional can be omitted.
• Plugin authors may extend runtime_config with additional fields, but only the above are officially recognized.
• Authentication applies to all HTTPS requests made by plugins, including plugin downloads and runtime API calls.
• URL matching is case-sensitive and based on string prefix matching.
• Keyring authentication requires platform-specific keyring services to be available and accessible.
• Skip tools patterns use full regex syntax with automatic anchoring for precise tool filtering.
• Allowed secrets provide fine-grained control over keyring access, implementing principle of least privilege for secret management.
• When allowed_secrets is omitted, plugins may have unrestricted keyring access (depending on plugin implementation). When specified, only the listed keyring entries can be accessed.
• Dynamic loading is disabled by default. When enabled via config, CLI flag, or environment variable, the hyper_mcp-load_plugin and hyper_mcp-unload_plugin tools become available to MCP clients.