Skip to main content
The compile command creates a self-contained executable that embeds the workerd runtime, your configuration, and all associated worker code and data.

​
Usage

workerd compile <config-file> [const-name] [options] > output-binary

​
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 compile config.capnp -I /usr/local/share/capnp -I ./schemas > server
​
-b, --binary
flag
Indicates that the configuration file is an encoded binary Cap’n Proto message rather than text format.
workerd compile config.bin --binary > server

​
Output options

​
--config-only
flag
Only write the encoded binary config to stdout. Do not attach it to an executable.The encoded config can be used as input to the serve command with the --binary flag.
workerd compile config.capnp --config-only > config.bin
workerd serve config.bin --binary

​
How it works

The compile command creates a self-contained binary by:
  1. Copying the workerd executable to the output
  2. Appending the compiled configuration and all embedded resources
  3. Adding metadata to allow the runtime to locate the embedded config
The resulting binary can be executed directly: 
./output-binary [serve options]
It will automatically use the embedded configuration without requiring a separate config file.

​
Binary format

The compiled binary has the following structure: 
┌─────────────────────────────────┐
│ Original workerd executable     │
├─────────────────────────────────┤
│ Padding to 8-byte boundary      │
├─────────────────────────────────┤
│ Cap'n Proto encoded config      │
├─────────────────────────────────┤
│ Config size (8 bytes, word cnt) │
├─────────────────────────────────┤
│ Magic number (16 bytes)         │
└─────────────────────────────────┘
The magic number identifies the binary as having an embedded configuration. The size field allows the runtime to locate and read the config.

​
Examples

​
Basic compilation

# Compile to a binary
workerd compile config.capnp > my-server
chmod +x my-server

# Run the compiled binary
./my-server

​
With import paths

workerd compile config.capnp \
  -I /usr/local/share/capnp \
  -I ./schemas \
  > my-server

​
Config-only output

# Generate binary config
workerd compile config.capnp --config-only > config.bin

# Use with serve command
workerd serve config.bin --binary

​
Named constant

# Use specific config constant
workerd compile config.capnp productionConfig > prod-server
workerd compile config.capnp stagingConfig > staging-server

​
Deployment

Compiled binaries are ideal for deployment because:
  • Self-contained: No external config files needed
  • Portable: Single file to deploy
  • Immutable: Config cannot be changed without rebuilding
  • Simple: Just copy and execute
Example deployment: 
# Build
workerd compile config.capnp > server
chmod +x server

# Deploy
scp server user@production:/opt/server/
ssh user@production 'systemctl restart server'

​
Overriding embedded config

Even with an embedded config, you can still override certain settings at runtime: 
# Override socket address
./my-server --socket-addr http=*:8080

# Override directory paths
./my-server --directory-path static=/var/www

# Enable watch mode for development
./my-server --watch

​
Limitations

  • The output file must be written to a regular file or a pipe, not to a terminal. The command will refuse to write binary data to a terminal.
  • The compiled binary includes the full workerd runtime, so it will be at least as large as the workerd executable itself (typically 50-100 MB).
  • On systems with executable permission bits, the output file will automatically be marked as executable if it’s a new regular file.

​
Exit codes

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

Build docs developers (and LLMs) love

Get started for freeTalk to us