Skip to main content
The Service struct defines a named service that can handle requests. Services are private within the config and referenced by name from sockets and bindings.

​
Structure

​
name
Text
required
Name of the service. Used to refer to the service from elsewhere in the config file.Services are not accessible unless explicitly configured through a Socket or binding.

​
Service types

Each service must be one of the following types:

​
Worker

​
worker
Worker
A JavaScript/WebAssembly worker.See Worker schema for details.

​
Network

​
network
Network
A service that implements access to a network. fetch() requests are routed according to the URL hostname.
​
network.allow
List<Text>
default:"[\"public\"]"
Network addresses the worker can connect to, in CIDR notation or special strings:
  • public: Publicly-routable IP addresses
  • private: Private network addresses (superset of local)
  • local: Local machine addresses only
  • network: Opposite of local
  • unix: Unix domain socket addresses
  • unix-abstract: Linux abstract Unix domain addresses
Examples: 192.0.2.0/24, 2001:db8::/32
​
network.deny
List<Text>
Network addresses to deny, using the same format as allow.
​
network.tlsOptions
TlsOptions
TLS configuration for network connections.

​
External server

​
external
ExternalServer
A service that forwards all requests to a specific remote server, typically a back-end on your internal network.
​
external.address
Text
Address/port of the server. Examples:
  • 1.2.3.4:80: IPv4 address and port
  • [1234:5678::abcd]:80: IPv6 address and port
  • unix:/path/to/socket: Unix domain socket
  • unix-abstract:name: Linux abstract Unix socket
  • example.com:80: DNS hostname
​
external.http
HttpOptions
Connect over unencrypted HTTP.
​
external.https
group
Connect over encrypted HTTPS.
  • options: HttpOptions
  • tlsOptions: TlsOptions
  • certificateHost: Expected hostname in certificate

​
Disk directory

​
disk
DiskDirectory
An HTTP service backed by a directory on disk, supporting basic HTTP GET/PUT.Not intended for direct internet exposure. Typically wrapped by a worker that adds proper Content-Type handling.
​
disk.path
Text
Filesystem path of the directory. Relative paths are interpreted relative to the server’s working directory.If not specified, must be provided via --directory-path <service-name>=<path> command-line flag.
​
disk.writable
Bool
default:"false"
Whether to support PUT requests for writing. Uses atomic file operations.
​
disk.allowDotfiles
Bool
default:"false"
Whether to allow access to files/directories starting with .. These are hidden by default since they often contain metadata.

​
Example

services = [
  ( name = "main",
    worker = (
      modules = [(name = "worker.js", esModule = embed "worker.js")],
      compatibilityDate = "2024-01-01",
    )
  ),
  ( name = "internet",
    network = (
      allow = ["public"],
      tlsOptions = (trustBrowserCas = true)
    )
  ),
  ( name = "backend",
    external = (
      address = "10.0.0.100:8080",
      http = ()
    )
  ),
  ( name = "static",
    disk = (
      path = "/var/www/static",
      allowDotfiles = false
    )
  )
]

​
Service designator

When referring to a service from elsewhere in the config (e.g., from a binding), use a ServiceDesignator:
​
name
Text
required
Name of the service in the Config.services list.
​
entrypoint
Text
For modules-syntax workers with multiple named exports, specifies which entrypoint to use. Defaults to the default export.
​
props
union
Value to provide in ctx.props in the target worker.
  • empty: Empty object (default)
  • json: JSON-encoded value
In simple cases where only name is needed, you can use a raw string: 
bindings = [(service = "foo")]  # equivalent to (service = (name = "foo"))

Build docs developers (and LLMs) love

Get started for freeTalk to us