# How to Configure CORS Origins for the Voicebox API: A Complete FastAPI Guide

> Configure CORS origins for the Voicebox API with this complete FastAPI guide. Learn to set environment variables and leverage built-in defaults for seamless integration.

- Repository: [Jamie Pine/voicebox](https://github.com/jamiepine/voicebox)
- Tags: how-to-guide
- Published: 2026-04-14

---

**Set the `VOICEBOX_CORS_ORIGINS` environment variable to a comma-separated list of additional origins, or rely on the built-in local development defaults defined in [`backend/app.py`](https://github.com/jamiepine/voicebox/blob/main/backend/app.py).**

Voicebox is an open-source voice processing platform built by `jamiepine` that exposes a FastAPI-based HTTP API. When configuring CORS origins for the Voicebox API, you work with a private helper function that combines hard-coded local development endpoints with runtime environment variables to construct the final allowlist.

## Understanding the Voicebox CORS Architecture

Inside [`backend/app.py`](https://github.com/jamiepine/voicebox/blob/main/backend/app.py), the application factory calls `_configure_cors()` during startup. This function assembles the cross-origin policy by merging static defaults with user-supplied origins from the environment.

The implementation uses FastAPI's `CORSMiddleware` to handle preflight requests and inject `Access-Control-Allow-Origin` headers.

```python

# backend/app.py (lines 85-100)

def _configure_cors(application: FastAPI) -> None:
    """Set up CORS middleware with local-first defaults."""
    default_origins = [
        "http://localhost:5173",          # Vite dev server

        "http://127.0.0.1:5173",
        "http://localhost:17493",         # Tauri dev bridge

        "http://127.0.0.1:17493",
        "tauri://localhost",              # Tauri webview (macOS)

        "https://tauri.localhost",        # Tauri webview (Windows/Linux)

        "http://tauri.localhost",         # Tauri webview (Windows, some builds)

    ]
    env_origins = os.environ.get("VOICEBOX_CORS_ORIGINS", "")
    all_origins = default_origins + [o.strip() for o in env_origins.split(",") if o.strip()]

    application.add_middleware(
        CORSMiddleware,
        allow_origins=all_origins,
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )

```

## Default CORS Origins for Local Development

Voicebox ships with a **zero-config local development setup**. The `_configure_cors` function hard-codes seven default origins covering common local development scenarios:

- **Vite development server**: `http://localhost:5173` and `http://127.0.0.1:5173`
- **Tauri dev bridge**: `http://localhost:17493` and `http://127.0.0.1:17493`
- **Tauri webview platforms**: `tauri://localhost` (macOS), `https://tauri.localhost`, and `http://tauri.localhost` (Windows/Linux)

These defaults ensure the API accepts requests from the bundled desktop application and standard frontend development servers without additional configuration.

## Adding Custom Origins via Environment Variables

For production deployments or custom frontends, use the **`VOICEBOX_CORS_ORIGINS`** environment variable. The parsing logic in `_configure_cors` splits the string on commas, trims whitespace, and appends valid entries to the default list.

```bash

# Add specific production origins

export VOICEBOX_CORS_ORIGINS="https://app.example.com, https://admin.example.com"
uvicorn backend.app:app --host 0.0.0.0 --port 8000

```

Empty entries and surrounding whitespace are automatically filtered. The following inputs all produce valid results:

- `"https://a.com,https://b.com"` → Adds both origins
- `"https://a.com, https://b.com, "` → Trims spaces and ignores trailing comma
- `""` → Uses defaults only

## Docker and Container Deployment Configuration

When deploying Voicebox in containers, pass the environment variable in your Dockerfile or orchestration manifest:

```dockerfile

# Dockerfile

FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
ENV VOICEBOX_CORS_ORIGINS="https://frontend.example.com"
CMD ["uvicorn", "backend.app:app", "--host", "0.0.0.0", "--port", "8000"]

```

Or via `docker run`:

```bash
docker run -e VOICEBOX_CORS_ORIGINS="https://app.example.com" -p 8000:8000 voicebox:latest

```

## Verifying CORS Behavior with the Test Suite

The repository includes comprehensive CORS validation in [`backend/tests/test_cors.py`](https://github.com/jamiepine/voicebox/blob/main/backend/tests/test_cors.py). This suite confirms that:

- Default origins receive `Access-Control-Allow-Origin` headers
- Unknown origins are silently blocked
- Environment variable parsing handles edge cases (trailing commas, extra whitespace)
- The combined allowlist includes both defaults and custom origins

You can run these tests to verify your configuration before production deployment:

```bash
cd backend
pytest tests/test_cors.py -v

```

## Summary

- **Default security**: Voicebox uses a restrictive allowlist in [`backend/app.py`](https://github.com/jamiepine/voicebox/blob/main/backend/app.py) covering only local development tools (Vite, Tauri).
- **Runtime extension**: Set `VOICEBOX_CORS_ORIGINS` to append production domains without modifying source code.
- **Implementation details**: The `_configure_cors` helper in [`backend/app.py`](https://github.com/jamiepine/voicebox/blob/main/backend/app.py) handles merging, deduplication, and middleware registration using FastAPI's `CORSMiddleware`.
- **Credentials support**: The configuration sets `allow_credentials=True`, enabling cookie and authorization header transmission for allowed origins.
- **Validation**: Refer to [`backend/tests/test_cors.py`](https://github.com/jamiepine/voicebox/blob/main/backend/tests/test_cors.py) for the canonical behavior specification and regression testing.

## Frequently Asked Questions

### How do I add multiple allowed origins to Voicebox?

Set the `VOICEBOX_CORS_ORIGINS` environment variable to a comma-separated string of URLs. For example: `export VOICEBOX_CORS_ORIGINS="https://site1.com, https://site2.com"`. The `_configure_cors` function in [`backend/app.py`](https://github.com/jamiepine/voicebox/blob/main/backend/app.py) automatically splits, trims, and appends these to the default local development origins.

### What are the default CORS origins allowed by Voicebox?

Voicebox allows seven local development origins by default: Vite dev server (`localhost:5173`), Tauri dev bridge (`localhost:17493`), and Tauri webview protocols (`tauri://localhost`, `https://tauri.localhost`, `http://tauri.localhost`). These are hard-coded in the `_configure_cors` function and work out-of-the-box for local development.

### Does Voicebox support credentials (cookies/auth headers) with CORS?

Yes. The CORS configuration in [`backend/app.py`](https://github.com/jamiepine/voicebox/blob/main/backend/app.py) explicitly sets `allow_credentials=True`, which permits browsers to send cookies, authorization headers, and TLS client certificates when the request origin matches the allowlist. Ensure your production origins are explicitly added via `VOICEBOX_CORS_ORIGINS` to utilize this feature securely.

### Can I replace the default origins instead of appending to them?

The current implementation in `_configure_cors` always concatenates environment variable origins with the hard-coded defaults. To completely replace the allowlist, you would need to modify [`backend/app.py`](https://github.com/jamiepine/voicebox/blob/main/backend/app.py) directly or fork the repository. The test suite in [`backend/tests/test_cors.py`](https://github.com/jamiepine/voicebox/blob/main/backend/tests/test_cors.py) validates the default behavior, so any modifications should include corresponding test updates.