---
name: "receptor"
section: "1"
platform: "linux"
package: "receptor"
version: "1.5.5-1+b2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/receptor"
---

# receptor(1)

Main controller daemon

## NAME

receptor - Main controller daemon

## SYNOPSIS

**receptor** \[*--\<action\>* \[*\<param\>=\<value\>* ...\] ...\]

## DESCRIPTION

**--help**: Show this help

**--config** \<filename\>: Load additional config options from a YAML file

**--bash-completion**: Generate a completion script for the bash shell

-

  Run ". \<(receptor **--bash-completion**)" to activate now

**--node**: Specifies the node configuration of this instance (required)

-

  id=\<string\>: Node ID. Defaults to the local hostname. datadir=\<string\>: Directory in which to store node data. (default: */tmp/receptor*) firewallrules=\<JSON list of JSON dict of JSON data to JSON data\>: Firewall rules, see documentation for syntax. maxidleconnectiontimeout=\<string\>: Maximum duration with no traffic before a backend connection is timed out and refreshed. receptorkubesupportreconnect=\<string\> receptorkubeclientsetqps=\<string\> receptorkubeclientsetburst=\<string\> receptorkubeclientsetratelimiter=\<string\>

**--local-only**: Runs a self-contained node with no backend

-

  local=\<bool\>

**--version**: Displays the Receptor version.

**--log-level**: Specifies the verbosity level for command output

-

  level=\<string\>: Log level: Error, Warning, Info or Debug (default: error)

**--trace**: Enables packet tracing output

**--control-service**: Runs a control service

-

  service=\<string\>: Receptor service name to listen on (default: control) filename=\<string\>: Specifies the filename of a local Unix socket to bind to the service. permissions=\<int\>: Socket file permissions (default: 0600) tls=\<string\>: Name of TLS server config for the Receptor listener tcplisten=\<string\>: Local TCP port or host:port to bind to the control service tcptls=\<string\>: Name of TLS server config for the TCP listener

Commands that configure resources used by other commands:

**--tls-server**: Define a TLS server configuration

-

  name=\<string\>: Name of this TLS server configuration (required) cert=\<string\>: Server certificate filename (required) key=\<string\>: Server private key filename (required) requireclientcert=\<bool\>: Require client certificates (default: false) clientcas=\<string\>: Filename of CA bundle to verify client certs with pinnedclientcert=\<\[\]string (may be repeated)\>: Pinned fingerprint of required client certificate skipreceptornamescheck=\<bool\>: Skip verifying ReceptorNames OIDs in certificate at startup (default: false) mintls13=\<bool\>: Set minimum TLS version to 1.3. Otherwise the minimum is 1.2 (default: false)

**--tls-client**: Define a TLS client configuration

-

  name=\<string\>: Name of this TLS client configuration (required) cert=\<string\>: Client certificate filename (required) key=\<string\>: Client private key filename (required) rootcas=\<string\>: Root CA bundle to use instead of system trust insecureskipverify=\<bool\>: Accept any server cert (default: false) pinnedservercert=\<\[\]string (may be repeated)\>: Pinned fingerprint of required server certificate skipreceptornamescheck=\<bool\>: if true, skip verifying ReceptorNames OIDs in certificate at startup mintls13=\<bool\>: Set minimum TLS version to 1.3. Otherwise the minimum is 1.2 (default: false)

Commands to configure back-ends, which connect Receptor nodes together:

**--tcp-listener**: Run a backend listener on a TCP port

-

  bindaddr=\<string\>: Local address to bind to (default: 0.0.0.0) port=\<int\>: Local TCP port to listen on (required) tls=\<string\>: Name of TLS server config cost=\<float64\>: Connection cost (weight) (default: 1.0) nodecost=\<JSON dict of string to float64\>: Per-node costs allowedpeers=\<\[\]string (may be repeated)\>: Peer node IDs to allow via this connection

**--tcp-peer**: Make an outbound backend connection to a TCP peer

-

  address=\<string\>: Remote address (Host:Port) to connect to (required) redial=\<bool\>: Keep redialing on lost connection (default: true) tls=\<string\>: Name of TLS client config cost=\<float64\>: Connection cost (weight) (default: 1.0) allowedpeers=\<\[\]string (may be repeated)\>: Peer node IDs to allow via this connection

**--udp-listener**: Run a backend listener on a UDP port

-

  bindaddr=\<string\>: Local address to bind to (default: 0.0.0.0) port=\<int\>: Local UDP port to listen on (required) cost=\<float64\>: Connection cost (weight) (default: 1.0) nodecost=\<JSON dict of string to float64\>: Per-node costs allowedpeers=\<\[\]string (may be repeated)\>: Peer node IDs to allow via this connection

**--udp-peer**: Make an outbound backend connection to a UDP peer

-

  address=\<string\>: Host:Port to connect to (required) redial=\<bool\>: Keep redialing on lost connection (default: true) cost=\<float64\>: Connection cost (weight) (default: 1.0) allowedpeers=\<\[\]string (may be repeated)\>: Peer node IDs to allow via this connection

**--ws-listener**: Run an http server that accepts websocket connections

-

  bindaddr=\<string\>: Local address to bind to (default: 0.0.0.0) port=\<int\>: Local TCP port to run http server on (required) path=\<string\>: URI path to the websocket server (default: /) tls=\<string\>: Name of TLS server config cost=\<float64\>: Connection cost (weight) (default: 1.0) nodecost=\<JSON dict of string to float64\>: Per-node costs allowedpeers=\<\[\]string (may be repeated)\>: Peer node IDs to allow via this connection

**--ws-peer**: Connect outbound to a websocket peer

-

  address=\<string\>: URL to connect to (required) redial=\<bool\>: Keep redialing on lost connection (default: true) extraheader=\<string\>: Sends extra HTTP header on initial connection tls=\<string\>: Name of TLS client config cost=\<float64\>: Connection cost (weight) (default: 1.0) allowedpeers=\<\[\]string (may be repeated)\>: Peer node IDs to allow via this connection

Commands to configure services that run on top of the Receptor mesh:

**--command-service**: Run an interactive command via a Receptor service

-

  service=\<string\>: Receptor service name to bind to (required) command=\<string\>: Command to execute on a connection (required) tls=\<string\>: Name of TLS server config

**--ip-router**: Run an IP router using a tun interface

-

  networkname=\<string\>: Name of this network and service. (required) interface=\<string\>: Name of the local tun interface localnet=\<string\>: Local */30* CIDR address (required) routes=\<string\>: Comma separated list of CIDR subnets to advertise

**--tcp-server**: Listen for TCP and forward via Receptor

-

  port=\<int\>: Local TCP port to bind to (required) bindaddr=\<string\>: Address to bind TCP listener to (default: 0.0.0.0) remotenode=\<string\>: Receptor node to connect to (required) remoteservice=\<string\>: Receptor service name to connect to (required) tlsserver=\<string\>: Name of TLS server config for the TCP listener tlsclient=\<string\>: Name of TLS client config for the Receptor connection

**--tcp-client**: Listen on a Receptor service and forward via TCP

-

  service=\<string\>: Receptor service name to bind to (required) address=\<string\>: Address for outbound TCP connection (required) tlsserver=\<string\>: Name of TLS server config for the Receptor service tlsclient=\<string\>: Name of TLS client config for the TCP connection

**--udp-server**: Listen for UDP and forward via Receptor

-

  port=\<int\>: Local UDP port to bind to (required) bindaddr=\<string\>: Address to bind UDP listener to (default: 0.0.0.0) remotenode=\<string\>: Receptor node to connect to (required) remoteservice=\<string\>: Receptor service name to connect to (required)

**--udp-client**: Listen on a Receptor service and forward via UDP

-

  service=\<string\>: Receptor service name to bind to (required) address=\<string\>: Address for outbound UDP connection (required)

**--unix-socket-server**: Listen on a Unix socket and forward via Receptor

-

  filename=\<string\>: Socket filename, which will be overwritten (required) permissions=\<int\>: Socket file permissions (default: 0600) remotenode=\<string\>: Receptor node to connect to (required) remoteservice=\<string\>: Receptor service name to connect to (required) tls=\<string\>: Name of TLS client config for the Receptor connection

**--unix-socket-client**: Listen via Receptor and forward to a Unix socket

-

  service=\<string\>: Receptor service name to bind to (required) filename=\<string\>: Socket filename, which must already exist (required) tls=\<string\>: Name of TLS server config for the Receptor connection

Commands to configure workers that process units of work:

**--work-signing**: Private key to sign work submissions

-

  privatekey=\<string\>: Private key to sign work submissions tokenexpiration=\<string\>: Expiration of the signed json web token, e.g. 3h or 3h30m

**--work-verification**: Public key to verify work submissions

-

  publickey=\<string\>: Public key to verify signed work submissions

**--work-command**: Run a worker using an external command

-

  worktype=\<string\>: Name for this worker type (required) command=\<string\>: Command to run to process units of work (required) params=\<string\>: Command-line parameters allowruntimeparams=\<bool\>: Allow users to add more parameters (default: false) verifysignature=\<bool\>: Verify a signed work submission (default: false)

**--work-kubernetes**: Run a worker using Kubernetes

-

  worktype=\<string\>: Name for this worker type (required) namespace=\<string\>: Kubernetes namespace to create pods in image=\<string\>: Container image to use for the worker pod command=\<string\>: Command to run in the container (overrides entrypoint) params=\<string\>: Command-line parameters to pass to the entrypoint authmethod=\<string\>: One of: kubeconfig, incluster (default: incluster) kubeconfig=\<string\>: Kubeconfig filename (for authmethod=kubeconfig) pod=\<string\>: Pod definition filename, in json or yaml format allowruntimeauth=\<bool\>: Allow passing API parameters at runtime (default: false) allowruntimecommand=\<bool\>: Allow specifying image & command at runtime (default: false) allowruntimeparams=\<bool\>: Allow adding command parameters at runtime (default: false) allowruntimepod=\<bool\>: Allow passing Pod at runtime (default: false) deletepodonrestart=\<bool\>: On restart, delete the pod if in pending state (default: true) streammethod=\<string\>: Method for connecting to worker pods: logger or tcp (default: logger) verifysignature=\<bool\>: Verify a signed work submission (default: false)

**--work-python**: Run a worker using a Python plugin

\[DEPRECATION WARNING\] This option is not currently being used. This feature will be removed from receptor in a future release.

-

  worktype=\<string\>: Name for this worker type (required) plugin=\<string\>: Python module name of the worker plugin (required) function=\<string\>: Receptor-exported function to call (required) config=\<JSON dict with string keys\>: Plugin-specific configuration

Commands to generate certificates and run a certificate authority

**--cert-init**: Initialize PKI CA

-

  commonname=\<string\>: Common name to assign to the certificate (required) bits=\<int\>: Bit length of the encryption keys of the certificate (required) notbefore=\<string\>: Effective (NotBefore) date/time, in RFC3339 format notafter=\<string\>: Expiration (NotAfter) date/time, in RFC3339 format outcert=\<string\>: File to save the CA certificate to (required) outkey=\<string\>: File to save the CA private key to (required)

**--cert-makereq**: Create certificate request

-

  commonname=\<string\>: Common name to assign to the certificate (required) bits=\<int\>: Bit length of the encryption keys of the certificate dnsname=\<\[\]string (may be repeated)\>: DNS names to add to the certificate ipaddress=\<\[\]string (may be repeated)\>: IP addresses to add to the certificate nodeid=\<\[\]string (may be repeated)\>: Receptor node IDs to add to the certificate outreq=\<string\>: File to save the certificate request to (required) inkey=\<string\>: Private key to use for the request outkey=\<string\>: File to save the private key to (new key will be generated)

**--cert-signreq**: Sign request and produce certificate

-

  req=\<string\>: Certificate Request PEM filename (required) cacert=\<string\>: CA certificate PEM filename (required) cakey=\<string\>: CA private key PEM filename (required) notbefore=\<string\>: Effective (NotBefore) date/time, in RFC3339 format notafter=\<string\>: Expiration (NotAfter) date/time, in RFC3339 format outcert=\<string\>: File to save the signed certificate to (required) verify=\<bool\>: If true, do not prompt the user for verification (default: False)

## SEE ALSO

The full documentation for **receptor** is maintained as a Texinfo manual.  If the **info** and **receptor** programs are properly installed at your site, the command

-

  **info receptor**

should give you access to the complete manual.