# "HTTP Server" _Path: en/http/server_ > "The HTTP server (http.service) listens on a port and hosts routers, endpoints, and static file handlers." ## Table of Contents - HTTP Server ## Content # HTTP Server An `http.service` owns a listener and hosts routers, endpoints, and static file handlers. **Classification: server configuration reference.** Blocks are partial registry fragments unless they define every referenced network, environment, filesystem, router, certificate, actor, and policy entry. ## Configuration ```yaml - name: gateway kind: http.service addr: ":8080" timeouts: read: "5s" write: "30s" idle: "60s" host: buffer_size: 1024 worker_count: 4 lifecycle: auto_start: true security: actor: id: "http-gateway" policies: - app:http_policy ``` | Field | Type | Default | Description | |-------|------|---------|-------------| | `addr` | string | required | Listen address (`:8080`, `0.0.0.0:443`) | | `timeouts.read` | duration | - | Request read timeout | | `timeouts.write` | duration | - | Response write timeout | | `timeouts.idle` | duration | - | Keep-alive connection timeout | | `host.buffer_size` | int | 1024 | Message relay buffer size | | `host.worker_count` | int | NumCPU | Message relay workers | | `network` | Registry ID | - | Bind listener through a [network overlay](system/network.md) (e.g. Tailscale, I2P) | | `tls` | object | - | TLS termination (see [TLS](#tls)) | ## Timeouts Configure timeouts to prevent resource exhaustion: ```yaml timeouts: read: "10s" # Max time to read the entire request (headers + body) write: "60s" # Max time to write response idle: "120s" # Keep-alive timeout ``` - `read` — Short (5–10 seconds) for APIs, longer for uploads - `write` — Match the expected response generation time - `idle` — Balance connection reuse against resource usage Duration format: 30s, 1m, 2h15m. Use 0 to disable. ## Host Configuration The `host` section configures the server's internal message relay used by components like WebSocket relay: ```yaml host: buffer_size: 2048 worker_count: 8 ``` | Field | Default | Description | |-------|---------|-------------| | `buffer_size` | 1024 | Message queue capacity per worker | | `worker_count` | NumCPU | Parallel message processing goroutines | Increase these values for high-throughput WebSocket applications. The message relay handles async delivery between HTTP components and processes. ## Security HTTP servers can have a default security context applied through the lifecycle configuration: ```yaml lifecycle: auto_start: true security: actor: id: "gateway-service" policies: - app:http_access_policy ``` This sets a baseline actor and policies for all requests. For authenticated requests, the [token_auth middleware](http/middleware.md) overrides the actor based on the validated token, allowing per-user security policies. ## Lifecycle Servers are managed by the supervisor: ```yaml lifecycle: auto_start: true start_timeout: 30s stop_timeout: 60s requires: - app:database ``` | Field | Description | |-------|-------------| | `auto_start` | Start when application starts | | `start_timeout` | Max time to wait for server to start | | `stop_timeout` | Max time for graceful shutdown | | `requires` | Start after these entries are ready (`depends_on` is the legacy spelling) | The server waits for its initial routes before accepting requests. During graceful shutdown, ordinary requests may finish within the stop deadline. SSE relays and Lua streaming responses end when shutdown begins; see [Server-Sent Events](http/sse.md) and [HTTP response streaming](lua/http/http.md#streams-and-server-shutdown). Connections still open after the deadline are closed. ## Connecting Components Routers and static handlers reference the server via metadata: ```yaml entries: - name: gateway kind: http.service addr: ":8080" - name: api kind: http.router meta: server: gateway prefix: /api - name: static kind: http.static meta: server: gateway path: / fs: app:public ``` ## Multiple Servers Run separate servers for different purposes: ```yaml entries: # Public API - name: public kind: http.service addr: ":8080" lifecycle: auto_start: true # Admin (localhost only) - name: admin kind: http.service addr: "127.0.0.1:9090" lifecycle: auto_start: true ``` ## TLS The server can terminate TLS directly. Set `tls.mode` to `manual` (supply your own certificate) or `auto` (certificate provided by an overlay network driver, e.g. `network.tailscale`). Plain clearnet listeners do not support `auto`. Omit `tls` or leave the mode empty to run plain HTTP. In `auto` mode the server must not specify `cert`/`key` — the network driver provides them. ### Manual certificate Under `mode: manual`, `cert` and `key` carry PEM content. Supply that content in one of three ways (pick one per field, never mix): 1. **Inline PEM** — the literal PEM string. 2. **`file://` reference** — manifest-relative path, resolved and inlined at load time (traversal-safe). 3. **Environment registry reference** — pull the PEM from a registered [env variable](system/env.md) at decode time, using a `${env:NAME}` placeholder. ```yaml - name: api kind: http.service addr: ":443" tls: mode: manual cert: file://./certs/server.pem key: file://./certs/server.key ``` ```yaml - name: api kind: http.service addr: ":443" tls: mode: manual cert: ${env:app.env:tls_cert} key: ${env:app.env:tls_key} ``` The `${env:NAME}` placeholder resolves `NAME` through the [environment registry](system/env.md) — a registered variable's public name or its entry ID (e.g. `app.env:tls_cert`). It is not a raw OS environment variable; an OS value is only reachable when an `env.storage.os`-backed variable is registered under that name. A default can be supplied with `${env:NAME|default}`. The legacy cert_env / key_env companion fields still resolve through the environment registry the same way, but are deprecated — prefer the ${env:NAME} placeholder shown above. | Field | Description | |-------|-------------| | `mode` | `""` (off), `auto`, or `manual` | | `cert` / `key` | PEM content — inline, `file://` reference, or `${env:NAME}` placeholder | ### Mutual TLS (mTLS) Under `mode: manual` the server can additionally verify client certificates: ```yaml tls: mode: manual cert: ${env:app.env:tls_cert} key: ${env:app.env:tls_key} client_ca: file://./certs/clients-ca.pem client_auth: require_and_verify ``` `client_ca` accepts the same three forms as `cert`/`key` (inline PEM, `file://`, or `${env:NAME}`). The legacy `client_ca_env` companion field is likewise deprecated in favor of `client_ca: ${env:NAME}`. | Field | Description | |-------|-------------| | `client_auth` | `request`, `require_any`, `verify_if_given`, `require_and_verify` | | `client_ca` | PEM bundle of trusted client CAs (inline, `file://`, or `${env:NAME}`) | `verify_if_given` and `require_and_verify` require a CA. `request` and `require_any` accept any client cert without CA verification. ## See Also - [Routing](http/router.md) - Routers and endpoints - [Static Files](http/static.md) - Static file serving - [Middleware](http/middleware.md) - Available middleware - [Security](system/security.md) - Security policies - [WebSocket Relay](http/websocket-relay.md) - WebSocket messaging ## Navigation Previous: "Executor" (system/exec) Next: "Routing" (http/router)