Configuration

Via reads a strict YAML configuration. Unknown fields and invalid values cause startup to fail with a configuration error.

Single upstream

The smallest configuration sends every request to one upstream:

listen: ":8080"
proxy_pass: http://localhost:3000

listen accepts:

• :PORT to listen on all IPv4 interfaces;
• HOST:PORT;
• [IPv6]:PORT.

proxy_pass must be an HTTP or HTTPS URL without a path, query, fragment, or credentials.

Routes

Use routes to select different upstreams by host and path:

listen: ":8080"

routes:
  - host: api.example.com
    path: /api
    proxy_pass: http://localhost:8000

  - path: /
    proxy_pass: http://localhost:3000

Top-level proxy_pass and routes are mutually exclusive. Every route must have exactly one target: proxy_pass or static. host is optional and path defaults to /.

See Routing for host matching, path matching, and precedence.

Configuration directories

-c accepts either one YAML file or a directory containing .yaml and .yml fragments. Files are merged in lexical filename order:

/etc/via/config/
├── 00-server.yaml
├── 10-api.yaml
└── 20-app.yaml

00-server.yaml:

listen: ":8080"

10-api.yaml:

routes:
  - host: api.example.com
    path: /
    proxy_pass: http://localhost:8000

20-app.yaml:

routes:
  - path: /
    proxy_pass: http://localhost:3000

Across a directory, listen must be declared exactly once and top-level proxy_pass at most once. Route arrays from all fragments are concatenated. The normal validation rules are applied after merging.

See Debug mode and hot reload for reload behavior.

TLS

Add a certificate and private key to terminate TLS:

listen: ":443"

tls:
  cert: /etc/via/cert.pem
  key: /etc/via/key.pem

proxy_pass: http://localhost:8000

Both files must exist and be readable. See TLS for runtime and reload behavior.

Static routes

A route may serve a directory instead of proxying:

routes:
  - path: /api
    proxy_pass: http://localhost:8000

  - path: /
    static: ./dist

For SPA fallback behavior, use the object form:

routes:
  - path: /
    static:
      root: ./dist
      fallback: index.html

Each route must contain exactly one of proxy_pass or static. See Static files for path mapping, caching, range requests, and security behavior.