How to Configure Retrieval Models with Security Gates and Remote Code Trust in MTPLX

To configure retrieval models with security gates in MTPLX, enable the --retrieval-trust-remote-code CLI flag, set retrieval_trust_remote_code = true in your ~/.mtplx/config.toml file, or pass trust_remote_code=True to the RetrievalRegistry constructor.

MTPLX supports optional retrieval models—including embedding and reranking models—that execute alongside the chat runtime. Because certain checkpoint formats (such as Jina-style models) bundle their own Python code (model.py, rerank.py), loading these models can execute arbitrary code on your system. To mitigate this risk, the MTPLX source code implements a strict security gate that blocks remote code execution unless you explicitly opt in.

Understanding the Security Gate and RetrievalTrustError

The core protection mechanism is the RetrievalTrustError exception defined in mtplx/retrieval.py (lines 71-78). This error is raised whenever a user requests a model containing bundled Python without granting explicit permission.

The RetrievalRegistry class stores the consent state in the boolean attribute trust_remote_code, initialized in RetrievalRegistry.__init__ (lines 89-107). By default, this value is False, placing the registry in safe mode.

When the registry acquires a model via _acquire (lines 84-92), it invokes _require_remote_code_trust for any Jina-style checkpoint. If trust_remote_code is False, the gate triggers and raises RetrievalTrustError, preventing code execution and pointing the user to the --retrieval-trust-remote-code flag.

Configuration Methods for Remote Code Trust

You can configure retrieval models with security gates using three distinct methods.

Command-Line Interface Flag

The --retrieval-trust-remote-code global flag, defined in mtplx/commands/public.py, enables remote code execution for the current process. This maps internally to the retrieval_trust_remote_code attribute used during registry construction via registry_from_args.

TOML Configuration File

For persistent configuration across sessions, set retrieval_trust_remote_code = true in your ~/.mtplx/config.toml (or the path specified by $MTPLX_CONFIG). The configuration loader in mtplx/config.py reads this value as part of the UserConfig schema, applying it automatically whenever the registry initializes.

Programmatic Python API

When constructing the registry programmatically, pass trust_remote_code=True directly to RetrievalRegistry, or use registry_from_args (lines 992-1014 in mtplx/retrieval.py) with parsed arguments containing retrieval_trust_remote_code=True.

How the Registry Enforces Security Gates

When a request for an embedding or rerank model arrives, the registry executes the following validation flow:

1. Path Resolution: The registry resolves the model reference to a local filesystem path using logic in _backend_key (lines 147-165).
2. Checkpoint Detection: It checks whether the checkpoint is a Jina embedding via _is_jina_embedding_checkpoint (lines 63-66) or a Jina reranker via _is_jina_reranker_checkpoint (lines 68-71).
3. Trust Verification: If either check returns true, _require_remote_code_trust validates that trust_remote_code is enabled.
4. Load or Abort: Only if the opt-in is confirmed does the registry proceed with loading; otherwise, it raises RetrievalTrustError.

This ensures that only models you consciously trust can execute bundled code, while pure MLX weight files load without restrictions.

Practical Configuration Examples

Enabling Trust via CLI

mtplx serve \
    --embedding-model org/embedding-repo=embed1 \
    --reranker-model org/rerank-repo=rank1 \
    --retrieval-trust-remote-code

Persistent TOML Configuration

Create or edit ~/.mtplx/config.toml:

retrieval_trust_remote_code = true
embedding_model = ["org/embedding-repo=embed1"]
reranker_model = ["org/rerank-repo=rank1"]
retrieval_max_resident = 3
retrieval_idle_timeout = 300

Programmatic Registry Setup

from mtplx.retrieval import RetrievalRegistry, RetrievalSpec

# Configure registry with remote code trust enabled

registry = RetrievalRegistry(
    max_resident=3,
    cache_dir="~/.mtplx/cache",
    idle_timeout_s=300,
    trust_remote_code=True,  # Security gate opt-in

)

# Register and use a Jina-style model

spec = RetrievalSpec(
    served_id="embed1",
    model_ref="org/embedding-repo",
    role="embedding",
)
registry.register(spec)

vectors, used_spec, token_count = registry.embed(
    ["What is MTPLX?"], model="embed1"
)

Handling Security Gate Violations

from mtplx.retrieval import RetrievalRegistry, RetrievalTrustError

# Safe mode (default)

registry = RetrievalRegistry(trust_remote_code=False)

try:
    vectors, _, _ = registry.embed(
        ["sample text"], model="jina-embeddings-v5"
    )
except RetrievalTrustError as e:
    print("Security gate blocked loading:", e)
    # Enable trust or notify user before retrying

Summary

• Security Gate: MTPLX uses RetrievalTrustError in mtplx/retrieval.py to block models with bundled Python unless explicitly trusted via trust_remote_code.
• Opt-in Methods: Enable remote code trust via the --retrieval-trust-remote-code CLI flag, the retrieval_trust_remote_code TOML setting in UserConfig, or the trust_remote_code constructor parameter.
• Detection Logic: The registry detects Jina-style checkpoints using _is_jina_embedding_checkpoint and _is_jina_reranker_checkpoint before enforcing the gate in _acquire.
• Safe Defaults: By default, trust_remote_code is False, ensuring arbitrary code cannot execute without user consent.

Frequently Asked Questions

What triggers the RetrievalTrustError in MTPLX?

The RetrievalTrustError is raised when you attempt to load a retrieval model that contains bundled Python code—such as Jina-style checkpoints with model.py or rerank.py—without setting trust_remote_code=True. The check occurs in RetrievalRegistry._acquire (lines 84-92) before the model is instantiated, protecting against arbitrary code execution.

How do I permanently enable remote code trust for all MTPLX sessions?

Add retrieval_trust_remote_code = true to your ~/.mtplx/config.toml file. The configuration loader in mtplx/config.py reads this value into the UserConfig object, which registry_from_args uses to initialize the RetrievalRegistry with trust_remote_code=True automatically for every subsequent run.

Can I enable remote code trust for only specific models?

Currently, the trust_remote_code flag is a global registry setting applied during RetrievalRegistry.__init__ (lines 89-107). While you cannot toggle it per individual model within a single registry instance, you can create separate registry instances with different trust settings, or dynamically handle RetrievalTrustError exceptions to prompt users for specific models.

Which checkpoint formats require the remote code trust flag?

Jina-style embedding and reranking checkpoints require the flag. The registry identifies these using _is_jina_embedding_checkpoint (lines 63-66) and _is_jina_reranker_checkpoint (lines 68-71) in mtplx/retrieval.py. Pure MLX weight files without bundled Python do not trigger the security gate.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}