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

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.

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, 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.

# 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.

# 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

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:

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. 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:

cd backend
pytest tests/test_cors.py -v

Summary

• Default security: Voicebox uses a restrictive allowlist in 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 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 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 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 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 directly or fork the repository. The test suite in backend/tests/test_cors.py validates the default behavior, so any modifications should include corresponding test updates.

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