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

> Learn to configure retrieval models with security gates and remote code trust in MTPLX. Enhance your model security by following this simple guide for the youssofal/MTPLX repository.

- Repository: [Youssof Altoukhi/MTPLX](https://github.com/youssofal/MTPLX)
- Tags: how-to-guide
- Published: 2026-09-13

---

**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`](https://github.com/youssofal/MTPLX/blob/main/model.py), [`rerank.py`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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

```bash
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`:

```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

```python
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

```python
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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/model.py) or [`rerank.py`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/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`](https://github.com/youssofal/MTPLX/blob/main/mtplx/retrieval.py). Pure MLX weight files without bundled Python do not trigger the security gate.