What's the default poll interval?

15 seconds, with jitter added so routers in a fleet do not all hit the CDN at the same moment. Both values are configurable.

What does watch_config.startup_delay do?

Optional startup delay spreads reload checks across router instances in a cluster so many pods do not reload at once (thundering herd).

What happens to WebSocket subscriptions during a reload?

Connections attached to the old instance close when the grace period ends. Clients need to reconnect, which they typically do automatically.

Does hot reload work for config file changes, or only for schema changes from the CDN?

Both. CDN polling covers execution config (schema). watch_config covers the router config file. Both take the same graceful-handoff path.

How much memory does the grace period need?

Running both old and new graph instances roughly doubles the federated graph's in-memory footprint for the grace period. Size pods with headroom; the default 30-second grace period keeps the overlap short.

Can I trigger an immediate reload without waiting for the poll interval?

Yes. Send SIGHUP to the router process: kill -HUP followed by the process id.

What doesn't hot reload cover?

Environment variables, command-line flags, and changes to the watch_config section itself require a restart.

GraphQL Router Config Hot Reload | Cosmo by WunderGraph

The problem

Why GraphQL router config changes are usually disruptive

Production routers sit in the middle of every client. Restarting them is a blunt instrument, and coordinating a whole fleet without mixed behavior is even harder.

Restarts drop connections.

A process restart terminates open HTTP and WebSocket connections. Clients see errors. Kubernetes rolling restarts stretch the pain across a rollout window instead of eliminating it.

Fleet rollouts are hard to coordinate.

Ten routers behind a load balancer all need the new config. Doing that without a window of mixed behavior (some routers on the old schema, some on the new) takes effort you'd rather spend elsewhere.

Emergency changes are slow.

When you need to flip a setting right now, waiting for the next poll cycle or the next deploy window is the wrong answer.

Our solution

Update router config live: no dropped requests, no restarts

Cosmo Router hot reload lets you apply schema and configuration changes without restarting the process. The router polls the CDN for new configs, spins up a new engine alongside the old one, hands off traffic gracefully, then retires the old instance with no dropped requests.

For local development, watch_config reloads a file-based config whenever it changes on disk. For on-demand reloads in production, sending SIGHUP to the router process triggers an immediate reload.

How the pieces fit

Cosmo Router hot reload applies schema and configuration changes without restarting the process.
The router polls the CDN for new configs, spins up a new engine alongside the old one, hands off traffic gracefully, then retires the old instance with no dropped requests.
For local development, watch_config reloads a file-based config whenever it changes on disk.
For on-demand reloads in production, sending SIGHUP to the router process triggers an immediate reload.

Same handoff path for CDN polling, file watching, and signal-driven reloads.

Config hot reload

Before & After

Before Cosmo	With Cosmo
Config changes require a restart, dropping connections	Graceful handoff keeps in-flight requests on the old instance
Fleet rollouts produce windows of mixed schema behavior	Every router polls the same CDN and converges within the poll interval
Dev iteration loops through a restart every config tweak	watch_config reloads on save for local work
Emergency changes wait for the next deploy	SIGHUP triggers an immediate reload on demand

Operations

Graceful handoff and limitations

During the grace period, both instances serve traffic. Memory use temporarily roughly doubles for the federated graph, so size the router pods with that headroom in mind. The query planner cache on the new instance is cold, so there is a brief latency bump on first requests per operation.

Limitations

WebSocket and Server-Sent Events connections attached to the old instance close when the old instance retires. Clients reconnect.
Changes to the watch_config section itself are not hot-reloaded; a restart is still required to change watch behavior.
Environment variable and command-line flag changes require a full restart.

How config hot reload works

01

Poll, watch, or signal: same handoff path.

Detect a new config

The router polls the CDN every 15 seconds by default, with jitter so replicas do not align. File-based config uses watch_interval; SIGHUP forces an immediate check.

02

Planner cache starts cold on the new instance.

Build a new graph instance

A new in-memory graph builds with a fresh query planner while the current instance keeps serving traffic.

03

No restart, no pod churn.

Route new traffic to the new instance

New requests go to the new instance; in-flight work finishes on the old one.

04

WebSockets on the old instance close at retire time.

Retire the old instance

When the grace period ends (default 30 seconds), the old instance is removed. shutdown_delay defaults to 60 seconds so long-lived server resources can close cleanly.

Use cases

Cosmo Router hot reload use cases

Zero-downtime schema deploys, fast local iteration, emergency rollouts, and observability hooks, all from one runtime behavior.

Zero-downtime schema deploys

Hot reload

Schema published via CLI lands on CDN; every router picks it up on the next poll and swaps engines. No pod restarts.

Local development iteration

watch_config

Enable watch_config with a short interval; saved changes apply within seconds. No manual restart.

Example YAML configuration

Configuration

Polling defaults, execution config watching, and router config watch, tuned for prod and local dev. Optional startup_delay under watch_config spreads reloads in clusters (see YAML above).

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

Emergency rollouts

On demand

Edit the config on the pod and send kill -HUP <pid>. The router reloads immediately.

Metrics & monitoring

Observability

Reload events are logged. Alert on failed reloads and on plan cache miss rate spiking after a reload.

Where hot reload runs

System boundary

Runs inside the Cosmo Router process (no sidecar).
CDN polling, file watching, and SIGHUP all converge on the same dual-instance handoff.
Pairs naturally with traffic shaping and other runtime YAML. Most settings hot reload.
Fits typical Kubernetes setups: point liveness and readiness probes at the router HTTP port so orchestrators know the process is up while hot reload swaps engines underneath.

Clients keep talking to the same router endpoint; only the engine behind it changes.

Ship router config without restarts

CDN polling, file watching, and SIGHUP, all with graceful handoff. Free tier included.

Start Free Read the Docs

Update the router without dropping a single request