Skip to content

Configuration

Jump to bottom
github-actions edited this page May 15, 2026 · 8 revisions

UNCORS supports two configuration methods: command-line arguments and configuration files. When both are used, CLI arguments take precedence and override settings defined in the configuration file.

The configuration system is built around the concept of host mappings, which translate local domains (defined in your hosts file) to external domains. Settings are organized into two levels:

  • Global Configuration - settings that apply to all mappings and control core server behavior
  • Mapping Configuration - settings specific to individual host mappings that determine how requests are handled

Table of Contents

Quick Reference

Minimal configuration:

mappings:
  - from: http://api.local:3000
    to: https://api.example.com

Common configuration patterns:

# Basic proxy with caching
mappings:
  - from: http://api.local:3000
    to: https://api.example.com
    cache:
      - /api/**

# Proxy with static files (SPA)
mappings:
  - from: http://app.local:3000
    to: https://api.example.com
    statics:
      - path: /
        dir: ./dist
        index: index.html

# Proxy with mocked endpoints
mappings:
  - from: http://api.local:3000
    to: https://api.example.com
    mocks:
      - path: /api/test
        response:
          code: 200
          raw: '{"status": "ok"}'

Tip

For complete working examples, see Real-World Examples

Command-Line Options

Configure the UNCORS proxy server using the following command-line parameters:

Mapping Configuration

Parameter Short Description
--from -f Source host with protocol and port (e.g., http://localhost:8080). Port defaults to 80 for HTTP and 443 for HTTPS if not specified
--to -t Target host with protocol to proxy requests to (e.g., https://api.example.com)

Multiple --from/--to pairs can be specified to define additional mappings. Each mapping can use a different port by specifying it in the URL.

Global Configuration

Parameter Short Description
--proxy HTTP/HTTPS proxy URL for upstream requests
--config Path to YAML configuration file
--debug Enable debug logging output

Note

CLI parameters override configuration file settings.

Configuration File

UNCORS uses YAML format for configuration files. Below is a comprehensive example demonstrating all available options:

# Global configuration
debug: false
proxy: localhost:8080

# Mappings configuration
mappings:
  - http://localhost:8080: https://github.com
  - from: http://other.domain.com:3000
    to: https://example.com
    statics:
      /path: ./public
      /another-path: ~/another-static-dir
    mocks:
      - path: /hello
        response:
          code: 200
          delay: 1m 30s
          raw: "Hello world"
      - path: /world
        method: POST
        response:
          code: 203
          delay: 5s
          file: ./path/to/file.data
    scripts:
      - path: /api/custom
        method: POST
        script: |
          local json = require("json")
          local data = json.decode(request.body)
          response.headers["Content-Type"] = "application/json"
          response:WriteHeader(200)
          response:WriteString(json.encode({status = "ok", received = data}))

Global Configuration Properties

Property Type Default Description
proxy string - HTTP/HTTPS proxy URL for upstream requests
debug boolean false Enable debug logging output
mappings array [] List of host mapping configurations (see below)
cache-config object - Global cache behavior settings (see Response Caching)

Mapping Configuration

The mappings section defines how UNCORS routes and handles requests. Each entry specifies a source and destination host pair along with optional processing rules:

mappings:
  - from: http://localhost:8080
    to: https://github.com
    mocks: [...]
    statics: [...]
    scripts: [...]

This configuration forwards all requests from http://localhost:8080 to https://github.com. The port is specified in the from URL and defaults to 80 for HTTP and 443 for HTTPS if omitted. Additional features like mocking, static file serving, and scripting can be configured per mapping. See Response Mocking, Static File Serving, and Script Handler for details.

OPTIONS Request Handling

By default, UNCORS intercepts and handles OPTIONS requests locally to facilitate CORS preflight checks. The default response includes:

  • Access-Control-Allow-Origin: *
  • Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS

Disabling OPTIONS handling:

mappings:
  - from: http://localhost:8080
    to: https://github.com
    options-handling:
      disabled: true

Customizing OPTIONS response headers:

mappings:
  - from: http://localhost:8080
    to: https://github.com
    options-handling:
      headers:
        Access-Control-Allow-Origin: http://localhost
        Access-Control-Allow-Methods: GET, POST

Note

UNCORS adds standard CORS headers to all responses. Custom headers specified here will override the defaults.

Protocol Scheme Mapping

UNCORS supports flexible protocol scheme mapping, allowing requests to be redirected between HTTP and HTTPS or to preserve the original scheme.

HTTP to HTTPS mapping:

mappings:
  - from: http://localhost:8080
    to: https://site.com

HTTPS to HTTP mapping:

mappings:
  - from: https://localhost:8443
    to: http://site.com

Scheme-agnostic mapping:

Using // as the scheme creates a mapping that matches both HTTP and HTTPS requests.

Redirect all requests to HTTPS:

mappings:
  - from: //localhost:8080
    to: https://site.com

Preserve the original request scheme:

mappings:
  - from: //localhost:8080
    to: //site.com

Note

HTTPS mappings require valid SSL/TLS certificates. See HTTPS Configuration for setup instructions.

Named Placeholder Mapping

UNCORS supports named placeholders in host mappings for flexible domain matching. A placeholder is written as {name} and matches any sequence of characters in that hostname segment (excluding . and /). Using explicit names makes multi-placeholder mappings self-documenting and allows each placeholder to be referenced by name in the target URL.

Example 1: Static target with placeholder source

mappings:
  - from: http://{repo}.local.com:8080
    to: https://github.com

All requests matching the {repo}.local.com pattern on port 8080 are forwarded to the same target:

Local request Target request
http://raw.local.com:8080 https://github.com
http://raw.local.com:8080/api/info https://github.com/api/info
http://docs.local.com:8080 https://github.com
http://docs.local.com:8080/index.html https://github.com/index.html

Example 2: Dynamic subdomain mapping

mappings:
  - from: http://{repo}.local.com:8080
    to: https://{repo}.github.com

The value captured by {repo} from the source URL is substituted into the target URL:

Local request Target request
http://raw.local.com:8080 https://raw.github.com
http://raw.local.com:8080/api/info https://raw.github.com/api/info
http://docs.local.com:8080 https://docs.github.com
http://docs.local.com:8080/index.html https://docs.github.com/index.html

Example 3: Multiple named placeholders

mappings:
  - from: http://{env}.{service}.local.com
    to: https://{service}.{env}.api.com

Each placeholder is matched and substituted by name, so the order in source and target can differ:

Local request Target request
http://prod.auth.local.com https://auth.prod.api.com
http://prod.auth.local.com/login https://auth.prod.api.com/login
http://staging.users.local.com https://users.staging.api.com

Note

Every placeholder name in a from URL must be unique. Using the same name twice (e.g., {client}.{client}.com) is a configuration error.

Simplified Syntax

For basic mappings without mocking or static file serving, use the shorthand syntax:

mappings:
  - http://localhost:8080: https://github.com

Both syntax styles can be mixed within the same configuration file:

mappings:
  - http://localhost:8080: https://github.com
  - http://host1:3000: https://gitlab.com
  - http://{repo}.com:8080: https://{repo}.io
  - from: http://host2:9090
    to: https://gitea.com
    mocks: [...]
    statics: [...]

Warning

Domain mappings only work for hosts defined in your system's hosts file. A placeholder mapping like http://{name}.local.com will not intercept all internet traffic - only requests to domains explicitly configured in your hosts file.

HAR Recording

UNCORS can record all proxied traffic to an HTTP Archive (HAR 1.2) file per mapping. The file can be opened in browser DevTools, Postman, or any HAR viewer.

Shorthand - pass the output file path as a string:

mappings:
  - from: http://api.local:3000
    to: https://api.example.com
    har: ./recordings/api.har

Full form - use an object for additional control:

mappings:
  - from: http://api.local:3000
    to: https://api.example.com
    har:
      file: ./recordings/api.har
      capture-secure-headers: false   # default: false
Property Type Default Description
file string - Output .har file path. Collector is disabled when empty.
capture-secure-headers boolean false Include auth/cookie headers in the recording (see HAR Collector).

Warning

Enabling capture-secure-headers writes tokens and cookies to disk in plain text. Never commit such files to version control.

See HAR Collector for the full reference.

HTTPS Configuration

UNCORS supports HTTPS for both incoming requests and upstream connections using auto-generated certificates.

Auto-Generated Certificates

UNCORS automatically generates and signs TLS certificates on-the-fly using a local Certificate Authority (CA).

Setup:

# Generate CA certificate (one-time setup)
uncors generate-certs

# Optional: specify validity period
uncors generate-certs --validity-days 730

# Force regenerate existing CA
uncors generate-certs --force

This creates a CA certificate in ~/.config/uncors/:

  • ca.crt - CA certificate (add to system trust store)
  • ca.key - CA private key

Trust the CA certificate:

After generating, add ca.crt to your system's trusted certificates:

  • macOS: Double-click ca.crt and add to Keychain Access
  • Linux: Copy to /usr/local/share/ca-certificates/ and run sudo update-ca-certificates
  • Windows: Import via Certificate Manager (certmgr.msc)

HTTPS mapping:

mappings:
  - from: https://localhost:8443
    to: https://github.com
  # Certificates are generated automatically for each host

Tip

Auto-generated certificates are cached in memory and regenerated only when needed.

Note

HTTPS server functionality is only activated when at least one mapping uses the https:// scheme. Each mapping specifies its own port in the from URL.

Proxy Configuration

UNCORS supports routing upstream requests through an HTTP/HTTPS proxy server.

Automatic Proxy Detection

UNCORS automatically detects and uses system proxy settings from environment variables:

  • HTTP_PROXY / http_proxy
  • HTTPS_PROXY / https_proxy
  • NO_PROXY / no_proxy

Environment variable values can be specified as:

  • Full URL: http://proxy.example.com:8080
  • Host and port: proxy.example.com:8080 (assumes HTTP)

Explicit Proxy Configuration

Override system settings using CLI or configuration file:

uncors --proxy http://proxy.example.com:8080 --from http://localhost --to https://api.example.com
proxy: http://proxy.example.com:8080

Clone this wiki locally