# How to Set Up Model Registry URL Override in FluidAudio for Offline Mirrors

> Set up model registry URL override in FluidAudio for offline mirrors by exporting REGISTRY_URL or setting ModelRegistry.baseURL programmatically. Redirect model downloads to your internal mirror.

- Repository: [Fluid Inference/fluidaudio](https://github.com/fluidinference/fluidaudio)
- Tags: how-to-guide
- Published: 2026-03-02

---

**Override the model registry URL in FluidAudio by setting `ModelRegistry.baseURL` programmatically before manager initialization, or by exporting the `REGISTRY_URL` (or `MODEL_REGISTRY_URL`) environment variable to redirect all model downloads to your internal mirror.**

When deploying `fluidinference/fluidaudio` in air‑gapped environments, you must redirect model downloads away from the default HuggingFace servers to an internal host. The `ModelRegistry` component provides a centralized mechanism to configure a **model registry URL override** without modifying download logic throughout the codebase.

## How the Model Registry URL System Works

The registry logic lives in [`Sources/FluidAudio/ModelRegistry.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudio/ModelRegistry.swift). Lines 30‑38 define the `baseURL` property, which defaults to `https://huggingface.co` when no override is present. Once you change this value, every URL‑building helper in lines 46‑85—including `apiModels()`, `resolveModel()`, `apiDatasets()`, `resolveDataset()`, and `resolveDatasetBase()`—automatically prepends your custom host to all endpoint paths.

## Three Methods to Override the Model Registry URL

FluidAudio evaluates these options in strict priority order:

### 1. Programmatic Override via ModelRegistry.baseURL

Set the static property in Swift before any manager creates or downloads a model. This approach is recommended for macOS or iOS applications where you control the app lifecycle.

```swift
import FluidAudio

// Point to your internal mirror before instantiating managers
ModelRegistry.baseURL = "https://my-internal-mirror.example.com"

// Subsequent managers will download from the mirror
let diarizer = DiarizerManager()

```

### 2. REGISTRY_URL Environment Variable

If no programmatic value exists, FluidAudio checks the `REGISTRY_URL` variable at runtime. This method is ideal for CI/CD pipelines and command‑line usage.

```bash
export REGISTRY_URL=https://my-internal-mirror.example.com
swift run fluidaudio transcribe meeting.wav

```

### 3. MODEL_REGISTRY_URL Environment Variable (Fallback)

When `REGISTRY_URL` is absent, FluidAudio falls back to `MODEL_REGISTRY_URL`. This secondary option ensures compatibility with legacy deployment scripts.

```bash
export MODEL_REGISTRY_URL=https://backup-mirror.example.com
swift run fluidaudio diarization-benchmark --auto-download

```

## Configuring Proxy Settings for Offline Mirrors

If your internal mirror sits behind a corporate proxy, the `ModelRegistry` respects standard `https_proxy` and `http_proxy` environment variables. The methods `configureProxySettings()` and `parseProxyURL()` (both in [`Sources/FluidAudio/ModelRegistry.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudio/ModelRegistry.swift)) read these variables and apply them to the `URLSession` returned by `configuredSession()`.

```bash
export https_proxy=http://proxy.corp.com:8080
export http_proxy=http://proxy.corp.com:8080
export REGISTRY_URL=https://my-internal-mirror.example.com

swift run fluidaudio transcribe audio.wav

```

## Implementation Examples

### Xcode Scheme Configuration

For local development in Xcode:

1. Open **Product → Scheme → Edit Scheme → Run → Arguments**.
2. Switch to the **Environment Variables** tab.
3. Add `REGISTRY_URL` with the value `https://my-internal-mirror.example.com`.
4. Close the dialog and run your target.

### Swift Application Bootstrap

```swift
import FluidAudio

func applicationDidFinishLaunching(_ notification: Notification) {
    // Set mirror before any audio processing begins
    ModelRegistry.baseURL = "https://artifactory.internal.com/hf-mirror"
    
    // Initialize managers after registry is configured
    let transcriptionManager = TranscriptionManager()
}

```

### Complete Offline Deployment Script

```bash
#!/bin/bash

# setup-offline.sh

export REGISTRY_URL="https://airgap-models.corp.internal"
export https_proxy="http://proxy.corp.internal:3128"

# Validate FluidAudio can reach the mirror

swift run fluidaudio list-models --verify-registry

```

## Summary

- **Programmatic control** is achieved by setting `ModelRegistry.baseURL` in Swift before any manager instantiation (lines 30‑38 of [`ModelRegistry.swift`](https://github.com/fluidinference/fluidaudio/blob/main/ModelRegistry.swift)).
- **Environment variables** provide flexible deployment options: `REGISTRY_URL` takes precedence over `MODEL_REGISTRY_URL` if both are present.
- **Automatic propagation** occurs across all URL builders (`resolveModel`, `apiDatasets`, etc.) once the base URL is changed.
- **Proxy support** is handled automatically via `https_proxy`/`http_proxy` variables, parsed by `configureProxySettings()` and applied to the shared `URLSession`.

## Frequently Asked Questions

### What is the default model registry URL in FluidAudio?

If you do not provide a model registry URL override, FluidAudio defaults to **`https://huggingface.co`**. This hard‑coded value is defined in the `baseURL` property of [`Sources/FluidAudio/ModelRegistry.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudio/ModelRegistry.swift) (lines 30‑38).

### Which environment variable takes precedence for registry overrides?

`REGISTRY_URL` has higher priority than `MODEL_REGISTRY_URL`. FluidAudio checks for `REGISTRY_URL` first; only if it is absent does the system fall back to `MODEL_REGISTRY_URL`. If neither variable is set, the default HuggingFace URL is used.

### How does FluidAudio handle corporate proxy settings for model downloads?

The `ModelRegistry` class automatically detects `https_proxy` and `http_proxy` environment variables through its `parseProxyURL()` helper (called within `configureProxySettings()`). These settings configure the `URLSession` used by all download methods, routing traffic through your corporate proxy before reaching the mirrored registry.

### Can I switch registry URLs at runtime after models have started downloading?

You can change `ModelRegistry.baseURL` at any time, but the change only affects **subsequent** download requests. Any model downloads already in progress will continue using the endpoint that was active when the `URLSession` task began. For consistent behavior, set the override once during application startup or before running CLI commands.