---
title: Gateway
description: The gateway section — listen address, worker threads, request and shutdown timeouts, body size limits, internal route prefix, SNI enforcement, health probes, and response compression.
---

# Gateway

The `gateway` section configures the listener and connection-level behavior. It is the only
required top-level section, and `listen` is the only required field within it.

```yaml
gateway:
  listen: "0.0.0.0:8080"
  workers: 0
  request_timeout: 30s
  shutdown_timeout: 30s
  pre_stop_delay: 5s
  max_body_size: 10485760
  internal_route_prefix: "__"
  enforce_sni_check: true
```

## `gateway`

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `listen` | socket address | — | Address and port to bind, e.g. `0.0.0.0:8080`. **Required.** |
| `workers` | integer | `0` | Worker threads. `0` means auto (derive from CPUs). |
| `request_timeout` | duration | `30s` | Per-request timeout. Must be greater than zero. |
| `shutdown_timeout` | duration | `30s` | Graceful shutdown window to drain in-flight requests. |
| `pre_stop_delay` | duration | `5s` | Delay after SIGTERM before the listener stops accepting new connections. Gives Kubernetes time to mark the pod NotReady. Set to `0s` to disable (e.g. when a `preStop` hook owns the delay). |
| `max_body_size` | integer (bytes) | `10485760` (10 MiB) | Maximum request body size. Must be greater than zero. |
| `tls` | object | none | TLS listener configuration. See [TLS](/docs/octopus/configuration/tls). |
| `compression` | object | enabled | Response compression. See [below](#compression). |
| `internal_route_prefix` | string | `"__"` | Prefix for built-in internal endpoints (admin, metrics, FARP), e.g. `/__admin`, `/__metrics`. |
| `probes` | object | enabled | Kubernetes-style health probe endpoints. See [below](#probes). |
| `enforce_sni_check` | boolean | `true` | Reject requests whose `Host` / `:authority` disagrees with the negotiated TLS SNI (anti host-spoofing). Disable when TLS is terminated upstream or `Host` legitimately differs from the SNI. |
| `security_headers` | object | disabled | Security response headers (HSTS, CSP, `X-Frame-Options`, …). See [below](#security-headers). |

<Callout type="info">
  `pre_stop_delay` and `enforce_sni_check` are most relevant in Kubernetes and TLS deployments
  respectively. See [Kubernetes](/docs/octopus/kubernetes) and [Security](/docs/octopus/security) for the
  operational background.
</Callout>

## Probes

The `gateway.probes` object controls the health endpoints served on the gateway's listen port,
intended for Kubernetes liveness/readiness/startup probes and external load-balancer checks.

```yaml
gateway:
  listen: "0.0.0.0:8080"
  probes:
    enabled: true
    liveness_path: /livez
    readiness_path: /readyz
    startup_path: /startupz
    require_discovery_sync: true
```

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | `true` | Whether the probe endpoints are served. |
| `liveness_path` | string | `/livez` | Returns 200 while the process is alive. |
| `readiness_path` | string | `/readyz` | Returns 200 only when ready to serve new traffic. |
| `startup_path` | string | `/startupz` | Returns 200 once the listener has bound. |
| `require_discovery_sync` | boolean | `true` | When true, readiness waits for the first service-discovery sync (only applies when discovery is configured). |

## Compression

The `gateway.compression` object configures response compression. It is enabled by default and is
the global compression middleware in the request pipeline (see [Middleware](/docs/octopus/configuration/middleware)).

```yaml
gateway:
  listen: "0.0.0.0:8080"
  compression:
    enabled: true
    level: 6
    min_size: 1024
    algorithms: ["br", "zstd", "gzip"]
```

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | `true` | Enable response compression. |
| `level` | integer | `6` | Compression level (1–9 for gzip/zstd, 1–11 for brotli). |
| `min_size` | integer (bytes) | `1024` | Minimum response size before compression is applied. |
| `algorithms` | array of string | `["br", "zstd", "gzip"]` | Preferred algorithms in order of preference. Valid values: `br` (brotli), `zstd`, `gzip`. |

## Security headers

The `gateway.security_headers` object adds common security headers to every response via the
security-headers middleware. It is **disabled by default**; set `enabled: true` to turn it on. Each
header is emitted only when its value is set (set a field to `null` to omit it); the defaults below
apply when enabled without overrides.

```yaml
gateway:
  listen: "0.0.0.0:8080"
  security_headers:
    enabled: true
    frame_options: DENY
    content_type_options: nosniff
    referrer_policy: strict-origin-when-cross-origin
    # hsts, csp, xss_protection, permissions_policy are also supported
```

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `enabled` | boolean | `false` | Add the configured security headers to every response. |
| `hsts` | string | `max-age=31536000; includeSubDomains` | `Strict-Transport-Security` value. |
| `csp` | string | `default-src 'self'` | `Content-Security-Policy` value. |
| `frame_options` | string | `DENY` | `X-Frame-Options` value. |
| `content_type_options` | string | `nosniff` | `X-Content-Type-Options` value. |
| `xss_protection` | string | `1; mode=block` | `X-XSS-Protection` value. |
| `referrer_policy` | string | `strict-origin-when-cross-origin` | `Referrer-Policy` value. |
| `permissions_policy` | string | none | `Permissions-Policy` value. |