Skip to main content
The serve command starts the workerd server and serves requests based on the provided configuration.

​
Usage

workerd serve <config-file> [const-name] [options]

​
Arguments

​
config-file
string
required
Path to the configuration file. Can be:
  • A Cap’n Proto text file (.capnp)
  • A binary Cap’n Proto file (with --binary flag)
  • - to read from stdin (requires --binary)
​
const-name
string
Name of the Config constant to use from the config file. Required if the file defines multiple Config constants.For nested constants, use dot notation: parentScope.constantName

​
Options

​
Configuration parsing

​
-I, --import-path
<dir>
Add a directory to the list of directories searched for non-relative imports (imports starting with /).Can be specified multiple times.
workerd serve config.capnp -I /usr/local/share/capnp -I ./schemas
​
-b, --binary
flag
Indicates that the configuration file is an encoded binary Cap’n Proto message rather than text format.Useful when driving workerd from higher-level tooling that generates binary configs.
workerd serve config.bin --binary

​
Socket configuration

​
-s, --socket-addr
<name>=<addr>
Override the socket named <name> to bind to the address <addr> instead of the address specified in the config file.
workerd serve config.capnp --socket-addr http=*:8080
​
-S, --socket-fd
<name>=<fd>
Override the socket named <name> to listen on the already-open file descriptor <fd> instead of the address specified in the config file.
workerd serve config.capnp --socket-fd http=3

​
Service overrides

​
-d, --directory-path
<name>=<path>
Override the directory named <name> to point to <path> instead of the path specified in the config file.
workerd serve config.capnp --directory-path static=/var/www
​
-e, --external-addr
<name>=<addr>
Override the external service named <name> to connect to the address <addr> instead of the address specified in the config file.
workerd serve config.capnp --external-addr backend=10.0.0.100:8080

​
Development features

​
-w, --watch
flag
Watch configuration files and the server binary. Automatically reload when changes are detected.Useful for development, but not recommended in production.
workerd serve config.capnp --watch
​
-i, --inspector-addr
<addr>
Enable the Chrome DevTools inspector protocol on the specified address.
workerd serve config.capnp --inspector-addr localhost:9229
​
--control-fd
<fd>
Enable sending control messages on the specified file descriptor. Currently reports the port each socket is listening on when ready.
workerd serve config.capnp --control-fd 4
​
--debug-port
<addr>
Listen on the specified address for debug RPC connections. Exposes a privileged interface allowing access to all services in the process.For use by Miniflare and local development only.
workerd serve config.capnp --debug-port localhost:9230

​
Python support

​
--pyodide-package-disk-cache-dir
<path>
Use the specified path as a disk cache to avoid repeatedly fetching Python packages from the internet.
workerd serve config.capnp --pyodide-package-disk-cache-dir ./cache/packages
​
--pyodide-bundle-disk-cache-dir
<path>
Use the specified path as a disk cache to avoid repeatedly fetching Pyodide bundles from the internet.
workerd serve config.capnp --pyodide-bundle-disk-cache-dir ./cache/pyodide
​
--python-save-snapshot
flag
Save a dedicated snapshot to the disk cache.
​
--python-save-baseline-snapshot
flag
Save a baseline snapshot to the disk cache.
​
--python-load-snapshot
<path>
Load a snapshot from the Python snapshot directory.
​
--python-snapshot-dir
<path>
Set the Python snapshot directory.

​
Advanced options

​
--experimental
flag
Permit the use of experimental features which may break backwards compatibility in a future release.
workerd serve config.capnp --experimental
​
-p, --perfetto-trace
<path>=<categories>
Enable Perfetto tracing output to the specified file with the given trace categories.Only available if workerd was built with Perfetto support.
workerd serve config.capnp --perfetto-trace trace.pftrace=workerd,v8

​
Examples

​
Basic usage

# Serve with default configuration
workerd serve config.capnp

# Serve with named constant
workerd serve config.capnp myConfig

# Serve with custom socket address
workerd serve config.capnp --socket-addr http=0.0.0.0:8080

​
Development workflow

# Watch for changes and enable inspector
workerd serve config.capnp --watch --inspector-addr localhost:9229

​
Binary configuration

# From file
workerd serve config.bin --binary

# From stdin
cat config.bin | workerd serve - --binary

​
Multiple overrides

workerd serve config.capnp \
  --socket-addr http=*:8080 \
  --socket-addr https=*:8443 \
  --directory-path static=/var/www \
  --external-addr backend=10.0.0.100:8080

​
Signal handling

The server responds to signals:
  • SIGTERM: Gracefully drain connections and shut down
  • SIGINT (Ctrl+C): Immediate shutdown

​
Exit codes

  • 0: Successful execution
  • 1: Configuration error or runtime error
  • Other: System-specific error codes

Build docs developers (and LLMs) love

Get started for freeTalk to us