Configuration reference

Every SithBit binary follows the same contract: an empty or missing config file is a runnable dev instance. Every setting has an in-code default — loopback binds, unprivileged ports, a local SQLite store — so configuration is only ever overriding a default, never satisfying a required field. The two exceptions are called out below (mail-grpc’s chain credentials, and TLS certificate paths, which have no sensible default).

The annotated example files are the canonical per-key documentation and ship with every default shown commented out:

• mail_spooler/sithbitd.example.toml
• account_api/account_api.toml
• domain_sithbit/domain_sithbit.example.toml
• ipfs_daemon/sithbit_ipfsd.example.toml
• ipfs_gateway/ipfs_gateway.example.toml

How a setting resolves

The TOML-config binaries (sithbitd, account-api, domain-sithbit) layer each setting, lowest to highest precedence:

1. the in-code default,
2. the TOML file (sithbitd.toml / account_api.toml / domain_sithbit.toml in the working directory, or the path in SITHBITD_CONFIG / ACCOUNT_API_CONFIG / DOMAIN_SITHBIT_CONFIG),
3. ./.env,
4. ./.env.$APP_ENV (APP_ENV comes from the environment or ./.env),
5. the real environment.

Environment variables address individual settings as {PREFIX}_{PATH}, with __ descending one TOML nesting level:

SITHBITD_STORE__KIND=aws                       # [store] kind
SITHBITD_SMTP__SERVER__BIND_ADDR=0.0.0.0:2525  # [smtp.server] bind_addr
SITHBITD_STORE__BLOBS__KIND=azure              # [store.blobs] kind (tagged enum)

The prefixes are SITHBITD, ACCOUNT_API, and DOMAIN_SITHBIT. Env files are read from the working directory only, and their values are exported to the process environment without overriding variables that are already set.

[health] and [observability] — every binary

Two sections shared by every TOML binary (mail-grpc’s equivalents are env vars — see its table below):

Every binary also accepts a --health-probe argument: load the same config, GET the health listener’s /readyz, exit 0/1 — this is what the compose healthcheck: entries run inside the distroless images. See Monitoring and backups for the endpoints, the metric list, and the docker-compose.otel.yml collector overlay.

sithbitd

The combined mail daemon: SMTP MX + submission, IMAP, POP, and the spooler workers in one process. Run exactly one sithbitd per store while [store] kind = "sqlite" — IMAP IDLE push and per-wallet SendMail ordering are in-process. The postgres and cloud stores lift that limit; see Scaling out.

[store] — shared with account-api

[store.blobs] selects the mail-body blob store: kind = "local" (default, path = "blobs"), "s3", or "azure" (endpoint, container, account, access_key).

[store.postgres] (for kind = "postgres"): url (default "postgres://postgres:postgres@127.0.0.1:5432/sithbit"). The schema is migrated idempotently at startup; the database itself must already exist. The URL’s password is redacted from logs and Debug output.

[store.aws] (for kind = "aws"): region, table (one DynamoDB table, default "sithbit"), queue_prefix (SQS queues named <prefix>-*, default "sithbit"), endpoint_url / sqs_endpoint_url (emulators), access_key / secret_key — omit the keys to use the ambient AWS credential chain (env, profile, IAM role). The table and queues are created idempotently at startup.

[store.azure] (for kind = "azure"): account, table, queue_prefix, table_endpoint, queue_endpoint, access_key. The defaults target a local Azurite emulator (run it with --skipApiVersionCheck); a real account derives its endpoints and needs access_key. Note the Azure blob store has no emulator key fallback: Azurite blob use needs the published well-known key passed explicitly.

[grpc] and [ipfs] — the chain pipeline

Both sections are required for mail to reach the chain; with either absent, the chain pipeline is disabled and delivered copies stay in state received (the dev default).

An empty [ipfs] section (plus [grpc]) is a complete chain setup: the embedded node imports mail blobs with the fixed CID profile (CIDv1, sha2-256, raw leaves, 256 KiB balanced dag-pb — byte-identical to Kubo) and stores blocks/pin manifests in ipfs.blobs.

[ipfs.repin] runs the repin-and-verify migration: an hourly sweep enumerates every fully chained copy and, per message, fetches the sealed bytes back from the legacy service, re-pins them on the active embedded/remote node, and releases the legacy pin only when the re-imported root CID matches the recorded on-chain one. On a mismatch (the legacy service imported with a different profile) the legacy pin is kept — the on-chain CID is immutable and must stay resolvable — and the sithbit.repin.outcomes{kind="mismatch"} counter grows. Watch that counter; once it stabilizes the migration is done: remove [ipfs.repin] (and, if nothing mismatched, the legacy credentials). Requires a store backend with candidate enumeration (SQLite today); sithbitd refuses the section otherwise at startup.

kind = "remote" delegates pin/unpin/fetch to a shared sithbit-ipfsd daemon over HTTP instead of running a node in-process — the multi-instance shape: the fleet pins through one node (one swarm identity, one block store) rather than each daemon embedding its own. [ipfs.blobs] and [ipfs.swarm] are ignored in this mode; they are the daemon’s to configure.

With [ipfs.swarm] configured the node also joins the IPFS DHT: it learns peers via identify, and with provide = true announces every pinned root so stock Kubo peers can discover this node as the content’s provider (pin manifests are the source of truth — a reprovide sweep reconciles the DHT records against them on every tick, immediately at startup). While the swarm runs, the node serves its pinned blocks over bitswap (/ipfs/bitswap/1.2.0): any connected peer — or one that found us via a provider record — can ipfs get the content straight out of the configured blob store. Serving is one-way: the node answers wantlists but never fetches foreign CIDs. For public retrievability the listen addresses must be reachable from the internet (an open inbound port); behind a closed firewall the DHT records carry addresses nobody can dial.

[smtp], [submission] — the two SMTP listeners

[smtp] is the MX listener (enabled by default); [submission] is the authenticated-submission listener (disabled by default). Both share the same shape:

With the chain pipeline enabled, sithbitd checks every configured local domain against the chain at startup (via the gateway’s GetMailDomain): a domain that is unregistered, deactivated, or whose on-chain authority is not the gateway’s signing key gets one loud warning in the log — mail to it would otherwise fail silently per-message at SendMail. The check never blocks or fails the boot, and the chain-disabled dev stack skips it.

[imap], [pop]

[*.server] — the shared listener section

Every listener ([smtp.server], [submission.server], [imap.server], [pop.server]) takes the same fields:

[smtp.tls] / [submission.tls] / [imap.tls] / [pop.tls] each take certs and key (PEM file paths, e.g. fullchain.pem / privkey.pem). With no TLS section the listener runs plaintext — fine on loopback, not on the internet.

[spooler] — outbound workers

[spooler.smarthost] routes all outbound mail through a fixed relay instead of MX resolution: host, port, user, password, require_tls. [spooler.dkim] signs authenticated submissions: domain, selector, key_file (see DNS setup for the matching DNS record). A multi-domain server writes one entry per sending domain with the [[spooler.dkim]] array form (the single-table form keeps working); the signer is selected by the sender’s domain so each domain’s signature aligns for DMARC, and a sender domain with no entry spools unsigned. A domain listed twice refuses to start.

account-api

sithbit-console

The management TUI over the account API’s /v1/admin routes: accounts, mailboxes, messages with chain states, queue depths, and dead-letter requeue/discard (see Monitoring). It never touches the store directly — every read and action rides the API. Config file sithbit_console.toml (or SITHBIT_CONSOLE_CONFIG), env prefix SITHBIT_CONSOLE.

domain-sithbit

Its on-chain calls resolve the RPC endpoint the way the sithbit CLI does: the config file at ~/.config/solana/cli/config.yml, managed with sithbit config get/set,¹ overridden by a JSON_RPC_URL environment variable.

sithbit-ipfsd

The self-hosted IPFS node as its own daemon: the same embedded repo/swarm sithbitd can run in-process, behind a small HTTP pin API (POST/DELETE /pins/{name}, GET /ipfs/{cid}) for fleets that share one node via [ipfs] kind = "remote". Config file sithbit_ipfsd.toml (or SITHBIT_IPFSD_CONFIG), env prefix SITHBIT_IPFSD_.

sithbit-gateway

The read-only IPFS HTTP path gateway: GET/HEAD /ipfs/{cid} (deserialized, plus trustless ?format=raw|car) over the same block/pin bucket the node writes; locally-absent CIDs answer 404 — it never fetches from the IPFS network. Config file ipfs_gateway.toml (or IPFS_GATEWAY_CONFIG), env prefix IPFS_GATEWAY_.

mail-grpc

mail-grpc is configured by environment only (it reads ./.env first):

The alias index is derived state: it backfills from chain history on an empty database, so the file needs no backup (see Monitoring and backups).

Which services get a .env

mail_spooler, account_api, domain_sithbit, ipfs_daemon, and ipfs_gateway each ship a sample .env and .env.development in their crate directory — commented-out templates for every environment-variable override, using the precedence chain above. Copy the ones you need and uncomment.

Other crates in the workspace deliberately don’t have one:

• mail-grpc loads its configuration through a plain dotenvy::dotenv() call (which walks up from the working directory, unlike the layered .env/.env.$APP_ENV mechanism the four binaries above use) and has no .env.$APP_ENV overlay concept at all. It’s already served by the workspace-root .env, which deliberately lives there holding devnet secrets (see “Important: secrets in the tree” in the workspace’s CLAUDE.md) — a second mail_grpc/.env would just duplicate or shadow it.
• The sithbit CLI (mail_client) reads no .env at all; its only configuration inputs are the config file sithbit config manages¹ and the JSON_RPC_URL environment variable.
• mail_program / alias_program are on-chain SBF programs with no runtime environment.
• Every other workspace crate is a library with no binary target, so there’s nothing to configure at runtime.

1. This is the same file (~/.config/solana/cli/config.yml, same location on Windows too) the Solana CLI’s own solana config command reads and writes, if you already have it installed — see Getting Started. ↩ ↩2