Skip to main content
workerd uses a capability-based configuration system written in Cap’n Proto text format. This approach provides strong typing, security through explicit capability grants, and clear visibility into what resources each worker can access.

​
Configuration philosophy

workerd’s configuration follows several key principles:
  • Capability-based security: Workers have no access to external resources by default. You must explicitly declare bindings to grant access to specific resources.
  • No global namespaces: Resources are not accessed by name. Instead, workers receive JavaScript API objects (bindings) that point to specific resources.
  • Composability: By changing config alone, you can fully control which resources a worker connects to, without modifying code.
  • Service-oriented: Each workerd instance is composed of multiple named services that can be workers, network access, external servers, or disk directories.

​
Basic structure

A workerd configuration file has three main components:
  1. Services: Named services that define workers and other capabilities
  2. Sockets: Network listeners that expose services
  3. Extensions: Optional capabilities provided to all workers
using Workerd = import "/workerd/workerd.capnp";

const config :Workerd.Config = (
  services = [
    (name = "main", worker = .mainWorker),
  ],

  sockets = [
    ( name = "http",
      address = "*:8080",
      http = (),
      service = "main"
    ),
  ]
);

const mainWorker :Workerd.Worker = (
  serviceWorkerScript = embed "worker.js",
  compatibilityDate = "2023-02-28",
);

​
Cap’n Proto text format

workerd configuration files use Cap’n Proto text format, which provides:
  • Strong typing: The schema validates your configuration at parse time
  • Structured data: Complex nested structures with unions and optional fields
  • File embedding: Use embed "file.js" to include external files directly
  • Comments: Use # for single-line comments

​
Common syntax patterns

using Workerd = import "/workerd/workerd.capnp";

​
Top-level configuration

The Config struct accepts these fields:
​
services
List(Service)
required
List of named services defined by this server. Service names are private and used only within this config file for references and logging.
​
sockets
List(Socket)
List of sockets on which the server will listen and the services exposed through them.
​
extensions
List(Extension)
Extensions that provide capabilities to all workers. Extensions are typically prepared separately and late-linked with the app.
​
v8Flags
List(Text)
Command-line flags to pass to V8, like --expose-gc. Use with caution as V8 flags can have unpredictable effects and are not guaranteed to be stable between V8 versions.
Most users should not set any V8 flags. Use at your own risk.
​
autogates
List(Text)
List of gates which are enabled. These are used to gate features/changes in workerd.
​
logging
LoggingOptions
Console and stdio logging configuration options.
logging = (
  structuredLogging = true,
  stdoutPrefix = "out: ",
  stderrPrefix = "err: ",
)

​
Command-line usage

Once you have a configuration file, you can run workerd with: 
workerd serve my-config.capnp

​
Overriding configuration

You can override certain configuration values from the command line: 
# Override socket addresses
workerd serve config.capnp --socket-addr http=*:3000

# Use file descriptors for sockets
workerd serve config.capnp --socket-fd http=3

# Override external server addresses
workerd serve config.capnp --external-addr backend=10.0.1.5:8080

# Override directory paths
workerd serve config.capnp --directory-path assets=/var/www/static

# Enable verbose logging
workerd serve config.capnp --verbose

​
Compiling standalone binaries

You can compile your configuration and code into a standalone binary: 
workerd compile my-config.capnp constantName -o my-server-bin
This binary combines the workerd runtime with your configuration and all source code, and can be run without any additional files.

​
Multiple configurations

A single .capnp file can contain multiple configuration constants. Specify which one to use: 
const devConfig :Workerd.Config = (
  # Development configuration
);

const prodConfig :Workerd.Config = (
  # Production configuration
);

workerd serve config.capnp devConfig
workerd serve config.capnp prodConfig

​
The “internet” service

If you don’t define a service called “internet”, one is created implicitly: 
( name = "internet",
  network = (
    allow = ["public"],   # Public addresses only
    tlsOptions = (trustBrowserCas = true)
  )
)
This service backs the global fetch() function unless you specify a different globalOutbound service in your worker configuration.
The default “internet” service blocks private network addresses to prevent SSRF attacks.

​
Next steps

Services

Learn about the different types of services

Workers

Configure worker services

Sockets

Set up network listeners

Bindings

Grant capabilities through bindings

Build docs developers (and LLMs) love

Get started for freeTalk to us