Skip to content

Install + Run

Running both binaries in production.

Installation

Install metad, feedd, and/or orderd on the target host(s). A minimal Linux host needs:

  • POSIX shared memory support
  • Low-latency network access to venue APIs
  • Clock synchronization (NTP/PTP)
  • Secrets delivery for venue credentials

Example binary install:

install -m 0755 metad /usr/local/bin/metad
install -m 0755 feedd /usr/local/bin/feedd
install -m 0755 orderd /usr/local/bin/orderd
mkdir -p /etc/sorcery

install is a Unix utility that copies a file to a target path and sets permissions in one step (cp + chmod). Equivalent commands:

cp metad /usr/local/bin/metad && chmod 0755 /usr/local/bin/metad
cp feedd /usr/local/bin/feedd && chmod 0755 /usr/local/bin/feedd
cp orderd /usr/local/bin/orderd && chmod 0755 /usr/local/bin/orderd
mkdir -p /etc/sorcery

Configuration reference

Each process has its own config file:

  • /etc/sorcery/metad.toml
  • /etc/sorcery/feedd.toml
  • /etc/sorcery/orderd.toml

All binaries that must interoperate MUST use the same stack.

Contract and reload semantics

  • This section defines the stable config contract.
  • Keys not listed here are out of contract for integrators.
  • Config files are read at process start.
  • Runtime SIGHUP reload is not part of the contract.
  • Runtime market-data subscription changes are done through the Control Plane, not by editing TOML in place.

Credential handling

  • Do not commit venue credentials to source control.
  • This contract is ENV-first: credentials are read from environment variables at process startup.
  • TOML carries environment variable names, not secret values.
  • Keep credential-bearing launch environments scoped to the service process only.

ENV naming convention

Recommended pattern:

  • <VENUE>_API_KEY
  • <VENUE>_API_SECRET

Where <VENUE> is the uppercase venue key from [venues.<venue>] with non-alphanumeric characters replaced by _.

Examples:

  • binance -> BINANCE_API_KEY, BINANCE_API_SECRET
  • bybit -> BYBIT_API_KEY, BYBIT_API_SECRET
  • coinbase -> COINBASE_API_KEY, COINBASE_API_SECRET
  • hyperliquid -> HYPERLIQUID_API_KEY, HYPERLIQUID_API_SECRET

/etc/sorcery/metad.toml

Key Type Required Default Restart required Notes
stack string yes none yes master or nightly. Controls metadata segment name /sorcery-{stack}-metadata.

Example:

stack = "master"

/etc/sorcery/feedd.toml

Key Type Required Default Restart required Notes
stack string yes none yes master or nightly. Controls /sorcery-{stack}-md, /sorcery-{stack}-snapshot, and metadata segment selection.
[control_plane] table no see child keys yes UDP endpoint for runtime subscribe / unsubscribe / request_snapshot commands.
control_plane.bind_host string no "127.0.0.1" yes Host/IP to bind control-plane UDP listener. Use a specific interface for remote clients.
control_plane.bind_port integer no 5510 yes UDP port for control-plane requests.
[venues.<venue>] table yes none yes One table per venue connection.
venues.<venue>.api_key_env string venue-dependent none yes Environment variable name containing the venue API key (for example BINANCE_API_KEY).
venues.<venue>.api_secret_env string venue-dependent none yes Environment variable name containing the venue API secret (for example BINANCE_API_SECRET).
venues.<venue>.subscriptions array of strings no [] yes (for boot seed) Canonical instrument keys used as initial boot subscriptions (for example perp.binance:BTCUSDT). Runtime add/remove uses control plane.

Example:

stack = "master"

[control_plane]
bind_host = "127.0.0.1"
bind_port = 5510

[venues.binance]
api_key_env = "BINANCE_API_KEY"
api_secret_env = "BINANCE_API_SECRET"
subscriptions = ["perp.binance:BTCUSDT"]

Launch example:

export BINANCE_API_KEY="..."
export BINANCE_API_SECRET="..."
feedd --config /etc/sorcery/feedd.toml

/etc/sorcery/orderd.toml

Key Type Required Default Restart required Notes
stack string yes none yes master or nightly. Controls /sorcery-{stack}-ord-req and /sorcery-{stack}-ord-rsp.
[venues.<venue>] table yes none yes One table per venue connection.
venues.<venue>.api_key_env string venue-dependent none yes Environment variable name containing the venue API key (for example BINANCE_API_KEY).
venues.<venue>.api_secret_env string venue-dependent none yes Environment variable name containing the venue API secret (for example BINANCE_API_SECRET).

Example:

stack = "master"

[venues.binance]
api_key_env = "BINANCE_API_KEY"
api_secret_env = "BINANCE_API_SECRET"

Launch example:

export BINANCE_API_KEY="..."
export BINANCE_API_SECRET="..."
orderd --config /etc/sorcery/orderd.toml

systemd units

Run one unit per process. The snippet below is a minimal metad template, not a complete production hardening profile:

[Unit]
Description=Sorcery metadata daemon
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/metad --config /etc/sorcery/metad.toml
Restart=always
RestartSec=1
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

In production, add deployment-specific directives (User=, Group=, CPU affinity/isolation, restart policy, logging target, environment/secrets injection).

Recommended ordering:

  • metad starts before feedd and orderd.
  • feedd and orderd can start independently after metad.

Container deployment

If running in containers:

  • Use host networking for lowest latency.
  • Mount /dev/shm with sufficient size.
  • Pin CPU sets for hot-path processes and consumers.
  • Keep one writer per ring.

Example run flags:

docker run --network host --ipc host --ulimit nofile=1048576:1048576 your-image:tag

Startup sequence

  1. Start metad.
  2. Wait until metadata segment is available (/sorcery-{stack}-metadata).
  3. Start feedd and/or orderd.
  4. Wait for STATUS messages showing conn_state = CONNECTED.
  5. Start downstream consumers/strategies.

Shutdown sequence (safe default):

  1. Stop strategy order submission.
  2. Stop orderd and/or feedd.
  3. Stop metad last.