Use cases

Static site with health check

worker_count = 2
[runtime]
type = "auto"

[[http.servers]]
listen = "0.0.0.0:8080"

[[http.servers.locations]]
matcher = { type = "exact", path = "/health" }
action = { type = "response", status = 200, body = "OK" }

[[http.servers.locations]]
matcher = { type = "prefix", path = "/" }
action = { type = "static", directory = "./public" }

Use this for documentation, a landing page, or frontend assets. Exact matching ensures the health response wins over the root prefix.

Static frontend with balanced API

worker_count = 4
[runtime]
type = "auto"

[upstreams.api]
policy = "weighted_round_robin"
servers = [
  { url = "http://127.0.0.1:9001", weight = 2 },
  { url = "http://127.0.0.1:9002", weight = 1 },
]

[[http.servers]]
listen = "0.0.0.0:8080"
server_name = "example.test"

[[http.servers.locations]]
matcher = { type = "prefix", path = "/api" }
action = { type = "proxy", upstream_group = "api" }

[[http.servers.locations]]
matcher = { type = "prefix", path = "/" }
action = { type = "static", directory = "./public" }

Use this when one process serves frontend files and forwards API traffic to multiple application instances.

Two virtual hosts on one port

[[http.servers]]
listen = "0.0.0.0:8080"
server_name = "www.example.test"
[[http.servers.locations]]
matcher = { type = "prefix", path = "/" }
action = { type = "static", directory = "./public" }

[[http.servers]]
listen = "0.0.0.0:8080"
server_name = "api.example.test"
[[http.servers.locations]]
matcher = { type = "prefix", path = "/" }
action = { type = "proxy", upstream = "http://127.0.0.1:9000" }

Use this for host-based separation without opening another listening port. The first entry is also the unmatched-host fallback.

Explicit Linux io_uring

worker_count = 4
[runtime]
type = "io_uring"
sq_entries = 4096
cq_entries = 8192
buf_ring_size = 16384
buf_size = 8192

Use explicit mode only after verifying the Linux kernel and environment support the required operations. Use auto when fallback is desirable.

Repository examples

The source tree also contains validated files under examples/config/: minimal response, static site, direct proxy, round robin, load balancing, virtual hosts, mixed routes, and each runtime.