콘텐츠로 이동
한국어

Configuration

이 콘텐츠는 아직 번역되지 않았습니다.

actor-ts uses HOCON for configuration — a superset of JSON common in JVM config files, with substitutions, durations and sizes. (include directives are refused — compose the sources in code.) Six layers, resolved highest-first:

  1. Constructor arguments to ActorSystem.create(name, settings) — explicit fields such as logger or logLevel, which beat any key.
  2. The inline config object in the settings — the code overrides, above every file.
  3. The secrets file — secrets.conf, optional, with its active profile (Secrets file).
  4. The application file — application.conf at the project root, or an explicit path via configFile, with its active profile (Profiles).
  5. The project’s defaults — its own reference.conf, optional, with its active profile (The project reference.conf).
  6. Reference defaults — bundled in the framework as REFERENCE_CONF (see src/config/Reference.ts).

Anything not specified in layers 1 to 5 falls through to the bundled default, and a ${VAR} in any of the files may read a .env file as well as the environment. Loading order spells out the whole chain.

This page explains what each key does. For the exhaustive list — every setting the framework ships, verbatim from the bundled file — see The full reference.conf.

This sample shows a representative selection of blocks, not every key; for the full list, see The full reference.conf.

actor-ts {
system { name = "my-app" }
logger { level = "info" }
dispatcher {
default = "hybrid" # hybrid | immediate | microtask | throughput
throughput = 16
}
cluster {
gossip-interval = 1s
seed-retry-interval = 3s
weakly-up-after = 0s # 0 = opt-in only
max-members = 1000
max-tombstones = 10000
tombstone {
time-to-live = 24h
prune-interval = 5m
min-retention = 0s # 0 = derive from down-after
}
failure-detector {
implementation = simple # simple | phi
heartbeat-interval = 500ms # shared by both implementations
auto-down = on # on = remove at down-after, off = park at unreachable
unreachable-after = 2s
down-after = 5s
phi {
unreachable-threshold = 8
down-threshold = 12
max-sample-size = 200
min-std-deviation = 100ms
acceptable-heartbeat-pause = 3s
expected-response-after = "auto" # auto = heartbeat-interval
}
}
split-brain-resolver {
active-strategy = off # off | keep-majority | keep-oldest | keep-referee | static-quorum | lease-majority
stable-after = 20s
down-all-when-unstable = off
}
pub-sub {
gossip-interval = 1s
max-subscribers-per-topic = 10000
max-topics = 10000
max-remote-nodes-per-topic = 1000
send-to-dead-letters-when-no-subscribers = on
}
receptionist {
gossip-interval = 1s
max-subscribers-per-key = 1000
max-subscriptions-total = 10000
}
}
distributed-data {
gossip-interval = 1s
max-pending-quorum-requests = 1000 # 0 = no cap
max-quorum-timeout = 30s # 0 = no ceiling
max-gossip-bytes = 1M # per gossip frame; 0 = no budget
}
remote {
tcp {
host = "0.0.0.0"
port = ${?ACTOR_TS_PORT} # unset: CLUSTER_PORT (bootstrap), then 2552
}
max-frame-bytes = 16M
}
persistence {
journal { plugin = "actor-ts.persistence.journal.in-memory" }
snapshot-store { plugin = "actor-ts.persistence.snapshot-store.in-memory" }
}
sharding {
number-of-shards = 64
role = "" # "" = unrestricted; names a role, never grants one
rebalance-interval = 2s
hand-off-timeout = 10s
acquire-retry-interval = 5s # retry a failed coordinator lease acquire
remember-entities = false
passivation-idle = 5m # 0 disables auto-passivation
# shard-passivation-idle # unset: follows passivation-idle
max-entities = 0 # 0 = no per-node cap
buffer-size = 100000 # region-wide; 0 = never buffer
register-retry-interval = 500ms
shard-region-query-timeout = 5s
entity-recovery { # how remembered entities come back
strategy = all # all | constant-rate
constant-rate.frequency = 100ms
constant-rate.number-of-entities = 5 # region-wide, not per shard
}
}
}

Place this at the project root. The framework auto-loads it on ActorSystem.create.

KeyDefaultPurpose
system.name"default"System name — used in actor paths and cluster identification. Applies when ActorSystem.create() is called without a name; an explicit create('billing') wins.
system.shutdown-drain-timeout2sHow long terminate() lets the actors under /user finish queued work before the stop cascade starts. Returns as soon as the tree is quiet, so an idle system pays a tick. Keep it under coordinated-shutdown.default-phase-timeout; 0 disables draining.
KeyDefaultPurpose
logger.level"info"One of debug / info / warn / error / off.
KeyDefaultPurpose
actor.throughput16User messages one actor handles per dispatcher turn before yielding. Override it per path with an actor-ts.deployment entry, and per actor with ActorOptions.withThroughput(), which wins over both.
actor.ask-timeout5sDeadline ActorRef.ask arms when the caller names no timeoutMs. A per-call ask(message, ms) always wins. Not honoured by every ref — see below.

ask-timeout reaches most refs, not all of them, and that is worth knowing before you tune it. A ref applies the configured value only if it can reach the ActorSystem that read it. Seven can: the ordinary local ref, TestProbe, RemoteActorRef, ClusterSingletonProxy, the two shard refs, and EntityRef through its region. The rest carry a system name and no system, and keep the built-in 5 s — the dead-letter ref, Nobody, an unresolved-path ref and the one-shot reply ref an ask synthesises for itself, plus two framework-internal handles (a WebSocket connection and the graceful-stop watcher) that nothing can reply to at all. Every one of them is a ref you hold where no live actor is behind it, so an ask on one is waiting for a reply that is not coming — the timeout decides how fast you find that out, not whether you find it out.

A bad value is refused, not clamped — unlike actor.throughput above. ask-timeout = 0 would arm no deadline, and an ask with no deadline can never settle, so there is no nearest-sensible value to fall back to; the system throws at ActorSystem.create, naming the key, rather than at every ask site later.

Below 4.6s it collides with scatter-gather routing. A router from Router.scatterGatherFirstCompleted(…) defaults to a 4.5 s deadline precisely so that it can collect its routees’ failures and answer before the caller’s own ask gives up. Configure an ask timeout under that and the caller sees AskTimeoutError instead of the AggregateError naming the failing routees. The system logs one warn at startup when it happens; give the router its own ScatterGatherOptions.withTimeoutMs() if the shorter ask deadline is what you want.

KeyDefaultPurpose
diagnostics.log-dead-letters10Dead letters logged in full before logging suspends. 0 turns dead-letter logging off entirely. Every letter is captured and published on the event stream either way — this gates the log line and nothing else.
diagnostics.log-dead-letters-during-shutdownoffLog the burst terminate() produces while it drains mailboxes to dead letters. Off because an orderly shutdown drains every queued and stashed message that way; an individual ref.stop() still logs, because the system is not terminating.
diagnostics.log-dead-letters-suspend-duration5mHow long logging stays suspended once the count above is reached. 0 never suspends, which is how “log every dead letter” is spelled.
diagnostics.log-config-on-startoffWrite the merged configuration to the log once at startup — one info record, every key with the layer that set it, sorted by path. The answer to “why is this setting not what I wrote”. Read the redaction note below before turning it on.
diagnostics.debug.unhandledoffOne debug record per message an actor was handed and declined: recipient path, message class, sender. The count (actor_unhandled_total) and the dead letter happen either way.
diagnostics.debug.lifecycleoffOne debug record per actor start, stop and restart. ActorStarted / ActorStopped / ActorRestarted on the event stream carry the same facts to a subscriber that can be selective, which a log level cannot.
diagnostics.debug.event-streamoffOne debug record per event-stream subscribe and unsubscribe — never per publish, which runs on every actor start, every stop and every dead letter. A whole-actor unsubscribe that removed nothing is not recorded; every actor stop makes one.

The record names the recipient path, the sender when there is one, and the message’s class — never the payload, for the same data-protection reason dead-letters.store defaults to off. Every key here is also settable in code, field by field, through ActorSystemOptions.withDiagnostics(…). See Dead letters for the whole picture.

The debug.* keys need two switches, not one. The key decides whether a record is produced; logger.level = debug decides whether it is written. Setting only one of them looks exactly like a switch that does not work. log-config-on-start is deliberately not in that family — it is an info record, because an operator who asked for a config dump asked for output.

What the config dump redacts, and what it does not. A value is withheld when any whole word of its key is password, passphrase, passwd, pass, secret, token, key, credential, auth or authorization, singular or plural — so cache.redis.password and an api-key print as <redacted>, and so does every key beneath a branch named credentials. Any word, wherever it stands in the name: an auth-header carries a bearer token although it ends on header. And whole words only — a name is cut into words at every character that is not a letter or a digit, at each camelCase hump and in front of a digit after a letter, so passivation-idle holds no pass and keyspace no key, while password2 holds the word it numbers. Glued onto another word those words count as well (pgpassword, clientsecret, ghtoken), all but key, pass and auth, which end too many ordinary words; of the …key names apikey, accesskey, secretkey and privatekey count, and pwd counts beside another word of the key’s path, as in mysql-pwd or db.pwd — only a variable called just PWD, a shell’s working directory, does not. An sshkey is not read. A value whose name holds such a word is withheld even when it is tuning: a token-bucket-size of your own prints as <redacted>, and only the keys reference.conf ships, such as cluster.receptionist.max-subscribers-per-key and cache.redis.key-prefix, are exempted by name. A value that is a boolean is never withheld whatever its key is called, since both of its states are public.

A URL’s credentials are masked whatever its key is called. The userinfo of every scheme://user:password@host in a printed value — and in each element of a list — is replaced with ***. A cache.redis.url that ${?REDIS_URL} set to redis://default:s3cret@redis.example:6379/0 prints as "redis://***@redis.example:6379/0", and so does a dsn, a connection-string or a uri of your own that holds one. The userinfo runs to the last @ before the next ://, so a password with an unescaped /, ? or # in it is masked whole. The scheme and everything after that @ — host, port, path and query — print exactly as written, which is what tells you which Redis is configured, and the header counts these values beside the keys it withheld. The price is paid by a value with no credential and an @ further on, in a path or a query: https://host/a@b prints as https://***@b.

A value the secrets file set is withheld whatever its key is called, and the header counts those keys apart from the ones withheld by name. The key rule also reads the fields of an object inside a list, which is one key: in upstreams = [ { host = "db-1", password = "…" } ] the password prints as "<redacted>" and the host as written.

A value an environment variable supplied is withheld when the variable’s name names a credential, by the same rule a key is read by, whatever the key is called: my-app.dsn = ${DB_PASSWORD} prints as <redacted>, and so does a key that refers to it and a string built from it. That holds for a variable from the real environment and from the .env file alike, in whichever layer read it — a code override that replaced the key included — and in a WorkerMesh worker’s dump. Every line names the variables behind its value, withheld or not — my-app.db.host = "db-1" [application, from $DB_HOST] — and the header counts these keys apart from the other two reasons.

The key rule is a heuristic over names, and it is the weakest of the four. What none of them can see is printed in full: a bare password written out under a key that does not name one, outside the secrets file and not taken from a credential-named variable; a credential in a query string (?password=…, ?authToken=…); SQL Server’s Server=…;Password=… connection string; and memcached’s scheme-less user:password@host:11211 server list. Nor is the list widened further: seed would redact cluster.seed-nodes, and a dump whose ordinary keys read <redacted> is a dump nobody reads. So treat the output as sensitive, keep the key off outside an investigation, and check what your own keys are called before pasting a dump into a ticket. The same rules, the same lists and the same limits apply to the DevTools config panel.

KeyDefaultPurpose
mailbox.default.capacity0Bound every actor the application wrote at this many queued user messages, without touching a spawn site. 0 means no global bound, which is the shipped behaviour — so this is not a retune, it is the switch that introduces message loss for every application actor at once.
mailbox.default.overflow"drop-head"System-wide policy for any bounded mailbox: the global bound above, and every actor that sets withMailboxCapacity() without naming a policy of its own. drop-head / drop-new / reject.

The bound reaches the actors the application wrote, which is not the same set as the actors under /user: a sharded entity is spawned by its shard and a cluster singleton by its manager, both under /system, and both are the application’s classes. Exempt are the framework’s own actors — shard regions and shards, singleton managers, the pub-sub mediator, the reliable-delivery producer, the DevTools hub — because shedding their traffic would break invariants the application never asked about and cannot see. (A framework class run as an entity is an entity: the host ShardedDaemonProcess runs each daemon in is bounded.) A spawn site wins over both keys: ActorOptions.withMailboxCapacity() overrides the capacity, withMailbox() replaces the queue outright. Between the two sits the actor-ts.deployment entry matching an actor’s path: its capacity and policy win over these keys for the paths it names, and its mailbox-capacity = 0 exempts them from the global bound.

Read Mailbox sizing before turning it on. This key and a deployment entry’s mailbox-capacity are the two in this file that can lose a message in an actor whose code says nothing about a mailbox — this one in every application actor at once — and the page names the framework-written actors a blanket bound still reaches because application code spawns them — the WebSocket hub and its connections, the broker adapters, the gRPC client and server.

Per-path settings: a throughput and a mailbox for the actors whose path a key matches, without touching their spawn sites (#868). The block ships empty — its keys are your actor paths — so nothing changes until you write an entry.

actor-ts.deployment {
"/user/ingest" {
throughput = 64
mailbox-capacity = 10000
mailbox-overflow = "drop-new"
}
"/user/chat/ws-*" { mailbox-capacity = 256 }
"/system/cluster/sharding/region-orders/**" { mailbox-capacity = 5000 }
}
KeyDefaultPurpose
deployment."<path>".throughputunsetUser messages a matched actor handles per dispatcher turn. An integer; 0 or below reads as 1, as actor.throughput does.
deployment."<path>".mailbox-capacityunsetQueued user messages before the overflow policy acts. An integer, 0 or above; 0 leaves the matched actors unbounded however mailbox.default.capacity is set.
deployment."<path>".mailbox-overflowunsetdrop-head / drop-new / reject, for any bounded mailbox of a matched actor: this entry’s capacity, a spawn-site one that names no policy, or the global one.

Keys are absolute path patterns, in quotes. /user/ingest names one actor; * is any run of characters inside one segment (/user/pool/routee-*), and a segment that is exactly ** is one or more whole segments (/user/hub/**) — the grammar parallelism.offload uses. Quote every key: an unquoted one does not parse, and a . in an actor name would split it. The keys carry no scheme and no system name, so they keep matching when the system is renamed, and an actor parallelism.offload moves onto a worker matches inside the worker too, whose system has a name of its own.

Each leaf resolves on its own: the spawn site (ActorOptions) first, then the matching entry, then actor.throughput / mailbox.default, then the built-in value. withMailbox() still replaces the queue outright, whatever the entry says.

One entry per actor, chosen whole. When several keys match, the most specific wins: an exact path, then keys with a * but no ** segment, then keys with a ** segment; within each, the longer literal prefix (the text before the first *), then more literal characters, then plain string order. A leaf the chosen entry leaves out falls through to the system layer, never to a less specific entry — so with "/user/**" { throughput = 8 } beside it, an empty "/user/special" { } runs /user/special at actor.throughput.

Who wrote the class decides what an entry reaches, as for mailbox.default: the actors your application wrote, including the sharded entities and singleton instances the framework spawns for you under /system, and never one of the framework’s own actors, whatever the key says. So /system is not refused here as it is in parallelism.offload: /system/cluster/sharding/region-orders/** bounds that region’s entities and leaves its shards alone.

A key that matches nothing does nothing. The system refuses to start, with a ConfigError naming actor-ts.deployment."<key>" and the leaf, on a key that is not absolute, has an empty, . or .. segment, or can name only the root or a guardian (/user, /*); on an entry that is not a block; on a leaf other than the three; and on a value outside its range.

KeyDefaultPurpose
dispatcher.default"hybrid"hybrid (default) — wakes actors on the microtask queue and spends every 64th unit on a macrotask, so timers and I/O still run; immediate — the previous default, one setImmediate per turn: fair, at ~2.4 µs a hop; microtask — unbounded, starves the event loop under sustained load, for measurement only; throughput — drains up to dispatcher.throughput queued turns per tick, across actors. An unset or unrecognised value falls back to hybrid.
dispatcher.throughput16Queued actor turns a ThroughputDispatcher drains per tick, across actors — not messages, and not per actor. See actor.throughput above for the per-actor batch. An integer from 1 up; unlike actor.throughput it is not raised to 1 — with default = throughput, a 0 or below fails ActorSystem.create with an OptionsError from ThroughputDispatcher.
KeyDefaultPurpose
dead-letters.store"off"Ordered by how much is kept: off = publish only, keep nothing / metrics = count them, keep no payload / memory = a bounded ring / persistent = also write to the journal, so the queue survives a restart.
dead-letters.max-entries1000Letters held before the oldest is evicted. Ignored by off and metrics, which hold none.
dead-letters.retention1hAge letters out after this long. 0 disables ageing and leaves max-entries as the only bound.
dead-letters.max-replays3How often one letter may be replayed before it is quarantined.
dead-letters.persistence-id""Journal stream the persistent store writes to. Empty derives it from the system name, so two systems sharing a journal keep separate queues.

Every key here is also settable in code, field by field, through ActorSystemOptions.withDeadLetters(…) — which wins over this block, as explicit options always do. See Dead letters for what the queue holds and how to replay from it.

KeyDefaultPurpose
cluster.gossip-interval1sHow often gossip is exchanged with a random peer.
cluster.seed-nodes[]Peers this node announces itself to at start-up, "system@host:port" (or "host:port"). Empty = “I am the first node” — see below.
cluster.roles[]Role tags this node carries. Shard regions, singletons, the per-role thresholds and the role-filtered downing strategies all place by role.
cluster.app-version(unset)The application version this node states to its peers — a label for operators, shown on /cluster/members and wherever a member is printed; nothing places, routes or downs on it. Comment-only in reference.conf: unset states none and puts nothing on the wire — see below.
cluster.seed-retry-interval3sHow often to retry seed connections during join.
cluster.weakly-up-after0sAuto-promote a joining member to weakly-up after this long. 0 disables it — see Weakly-up.
cluster.publish-stats-interval0sHow often this node publishes a ClusterStatsPublished sample of its membership view on system.eventStream. 0 arms no timer — see below.
cluster.shutdown-after-unsuccessful-join0sHow long a node may stay joining or weakly-up before it gives up the join. At the deadline, if nothing can promote it any more, it logs a warning, leaves and runs the coordinated-shutdown pipeline with ClusterJoinUnsuccessfulReason; otherwise it asks again every seed-retry-interval. 0 sets no deadline — see Joining and seeds.
cluster.max-members1000Cap on live member entries gossip may introduce. 0 disables the cap.
cluster.max-tombstones10000Cap on removed tombstones gossip may introduce. 0 disables the cap.
cluster.minimum-members-before-up1Members that must be present before anything is promoted to up. 1 is the historical behaviour — see below.
cluster.role.<role>.minimum-members-before-up(unset)Per-role threshold, composed with the one above as an AND. Comment-only in reference.conf, since role names are per-deployment.
cluster.run-coordinated-shutdown-when-downonWhat a node does once its own downing decision removes it. on leaves, then runs the coordinated-shutdown pipeline with ClusterDowningReason, which ends the actor system; off leaves the membership and keeps its actors running. See below.
cluster.down-smaller-islandoffWhen two same-name clusters that formed during a startup partition meet, the smaller one downs itself (on a tie, the one whose lowest address sorts higher). Off: the meeting is logged at error and the other island’s frames are refused; an operator restarts one side (#1176).
cluster.tombstone.time-to-live24hHow long a removed tombstone is kept before it is pruned.
cluster.tombstone.prune-interval5mHow often the prune pass runs.
cluster.tombstone.min-retention0sFloor on tombstone age before pruning is allowed. 0 derives it from failure-detector.down-after (6×).
cluster.failure-detector.implementationsimpleWhich detection algorithm this node runs — simple (elapsed-time thresholds) or phi (variance-aware φ-accrual).
cluster.failure-detector.heartbeat-interval500msHow often heartbeats are sent. Shared by both implementations — see below.
cluster.failure-detector.unreachable-after2sSuspicion threshold for unreachable status. simple only.
cluster.failure-detector.down-after5sSilence after which the verdict is down. With no split-brain strategy that removes the peer, under the default auto-down = on; with a strategy, or under auto-down = off, the peer is parked at unreachable. Measured from the last heartbeat, so it must exceed unreachable-after. simple only.
cluster.failure-detector.auto-downonWhat a down verdict does when no split-brain strategy is configured. on lets the detector remove the peer, so the surviving nodes take over its shards and singletons — and every side of a partition then does it to the other, unless a strategy such as lease-majority is configured. off is the opt-out: it parks the peer at unreachable until a strategy, Cluster.down or POST /cluster/down removes it. Both implementations. A configured strategy decides every removal, whatever this says — see below.
cluster.failure-detector.phi.unreachable-threshold8φ value above which the peer is flagged unreachable. A continuous score, so fractions are fine.
cluster.failure-detector.phi.down-threshold12φ value above which the peer is flagged down. Must exceed phi.unreachable-threshold.
cluster.failure-detector.phi.max-sample-size200How many recent inter-arrival times are kept per peer.
cluster.failure-detector.phi.min-std-deviation100msFloor on the sampled standard deviation, so a very steady peer is not flagged on noise.
cluster.failure-detector.phi.acceptable-heartbeat-pause3sGrace added to the last heartbeat before φ starts rising — a pure offset, so a stall up to ~3.5 s past the expected beat passes at the default cadence. Chosen by measurement; see the φ-accrual detector.
cluster.failure-detector.phi.expected-response-after"auto"The inter-arrival time φ assumes until a peer’s first heartbeat interval is measured, with a deviation of a quarter of it. "auto" is heartbeat-interval; a duration decouples the two.
cluster.split-brain-resolver.active-strategyoffWhich downing strategy arbitrates a partition — off, keep-majority, keep-oldest, keep-referee, static-quorum or lease-majority.
cluster.split-brain-resolver.stable-after20sHow long the membership and reachability view must hold still before the strategy is consulted — or, if it never does, half of how long one peer must have been continuously unreachable. See below.
cluster.split-brain-resolver.down-all-when-unstableoffDown every member, this node included, when the view never once holds still for stable-after across 3 × stable-after of churn. Off — see below.
cluster.split-brain-resolver.keep-majority.role""Only members carrying this role count toward the majority. "" counts every member.
cluster.split-brain-resolver.keep-oldest.role""Only members with this role are eligible “oldest”. "" considers every member.
cluster.split-brain-resolver.keep-oldest.down-if-aloneonWhether the oldest loses when it is the only member on its side, against two or more on the other. On, a crash of the oldest leaves the rest running; off, every survivor downs itself (#932).
cluster.split-brain-resolver.static-quorum.role""Only members carrying this role count toward quorum. "" counts every member.
cluster.split-brain-resolver.static-quorum.quorum-size(unset)Reachable members required to keep running. Required by static-quorum; comment-only in reference.conf — see below.
cluster.split-brain-resolver.keep-referee.referee-address(unset)The referee node’s address; the side containing it wins. Required by keep-referee; comment-only.
cluster.split-brain-resolver.keep-referee.down-all-if-below-quorum(unset)Down everyone if the referee’s own side is smaller than this. Optional; comment-only.
cluster.configuration-compatibility-check.enforceoffWhat a divergence does beyond being reported. on also bars the diverging peer from this node’s placement candidates — see below.
cluster.configuration-compatibility-check.checked-paths["actor-ts.remote.max-frame-bytes"]Settings whose effective values this node publishes to its peers and compares theirs against.

These are layered under whatever Cluster.join(system, options) passes, so an explicit withGossipIntervalMs(…) still wins. The failure detector merges per threshold: setting only down-after in code keeps the other two from the file. The phi block merges the same way, per field, against withPhiAccrual(…).

heartbeat-interval is deliberately outside phi and has no copy inside it. The cadence belongs to the cluster’s heartbeat loop rather than to either algorithm, so switching implementation cannot change how often this node talks to its peers. phi.expected-response-after follows it under auto: the detector resolves the word against the cadence it is given, so a heartbeat-interval tuned in this file or in code carries the estimate along. auto-down sits outside phi for the same reason: both detectors reach a down verdict, so what that verdict does is not a property of either. Everything else under failure-detector belongs to exactly one implementation and is ignored by the other.

The HOCON tree and the ClusterOptions fields are deliberately not isomorphic: the three tombstone knobs are grouped under tombstone because that is how you tune them, while the fields stay flat (withTombstoneTtlMs(…), …). remote.tcp.host → host already makes the same translation.

min-retention = 0s means derive the floor from the failure detector, not no floor — the same thing leaving the field unset means, so a file that spells the default out behaves like one that omits it.

The two max-* caps bound the local member map. remote.max-frame-bytes bounds one gossip frame; these bound what a sequence of well-formed frames can accumulate, which is a different quantity — see Cluster security.

publish-stats-interval arms a fifth periodic task on this node, and only when it is positive: every interval it publishes one ClusterStatsPublished — member count, up count, unreachable count, leader and this node’s address — on system.eventStream and to every cluster.subscribe listener. Every figure is already reachable through the Cluster API; what the key buys is the cadence. It is node-local and deliberately not on the cluster-wide cluster.eventStream, where a per-node periodic sample would cost N frames per node per interval. It is also actor-ts.devtools.stats-interval’s sibling rather than its replacement: same figures, different channel, and neither forwards into the other. See Cluster overview.

split-brain-resolver.active-strategy names a strategy rather than describing one, which is why the object it builds needs no HOCON shape of its own. The provider it constructs lands in the same slot withDowning(…) fills, and the same precedence applies: an explicit withDowning(…) wins, an absent one falls through to the file. See Downing strategies for what each strategy decides.

Three of its keys ship comment-only in reference.conf, so they are absent until you write them. Each is required or bounded and has no legal default: quorum-size = 0 and referee-address = "" are both refused by the strategies’ own validators, so a shipped leaf could only be a value that stops the node from starting. Naming static-quorum without quorum-size, or keep-referee without referee-address, is refused at startup with the missing key in the message.

lease-majority arbitrates through a lease the framework builds from actor-ts.coordination.lease, so it needs a backend there: with the shipped backend = none the strategy is refused at startup rather than run with nothing to arbitrate through. The lease is named <system>-split-brain-resolver, owned by this node, and built at the strategy’s first decision — the node’s address does not exist yet when the strategy does. There is no lease-majority block: its role and acquire timeout stay in code, withDowning(new LeaseMajority(…)), and a key written under split-brain-resolver.lease-majority is refused.

stable-after and down-all-when-unstable are the block’s policy half: they decide when the strategy is asked, not which one. Both are ignored while active-strategy = off. With no resolver there is no decision for a window to delay: by default the failure detector removes a peer it declares down itself, at failure-detector.down-after, and under failure-detector.auto-down = off it parks the peer at unreachable until someone removes it — a second window in front of that would be two thresholds for one decision.

failure-detector.auto-down is the switch for that no-resolver case; beside a configured strategy it changes nothing, because the strategy decides every removal whatever it says. on is the default because an n-node cluster has to stay operational with only one node left: a crashed peer is removed at down-after, and the last available node takes over its shards and singletons. The price is paid under a partition: the detector cannot tell a crash from one, every side’s detector reaches down-after for the other side at about the same moment, and removing on that verdict forks the cluster into two that do not merge again when the network heals — configure lease-majority or another strategy for production. off is the opt-out, and its price is paid on a crash: the crashed node stays a member, its shards are not reallocated and its remote watchers get no Terminated, until a strategy, Cluster.down or POST /cluster/down (with actor-ts.management.enable-down-endpoint = on) removes it, or it restarts on the same address. The node logs one warning per parked peer naming those three. See the failure detector.

stable-after is what makes a decision be about a settled fact. Every bundled strategy is a pure function of one view, so a view read mid-churn — half the peers already unreachable, the rest about to be — yields a verdict about a cluster that existed at no instant. The clock is the failure-detection tick, so the effective resolution is failure-detector.heartbeat-interval: invisible at twenty seconds, worth knowing at two hundred milliseconds. There is deliberately no upper bound tying it to failure-detector.down-after: with a strategy configured the detector parks an unreachable peer and evicts nothing, so the window has no deadline to out-run.

It is a preference rather than a precondition. The view it watches is every member’s address and status, so any join, leave or transition anywhere restarts it — and a deployment whose membership moves more often than stable-after would otherwise never arbitrate a partition at all, with the detector no longer evicting to fall back on. A peer that has been continuously unreachable for 2 × stable-after is therefore put to the strategy whatever else is moving. That multiple sits above one window, so a view that does settle is always arbitrated the ordinary way first, and below the 3 × stable-after escalation deadline, so a strategy is asked before down-all-when-unstable can stop the cluster.

down-all-when-unstable is the escalation for the cluster that never settles: when the view has not once held still for a whole stable-after across 3 × stable-after of continuous change — and something is still unreachable — every member is downed, this node included, and the log says so at warn. The margin is derived rather than configured, because it only ever means “several times however long this deployment thinks a view needs to settle”, and a margin below the window could never observe one quiet window before firing.

It ships off, and turning it on is a durability-over-availability posture rather than a detail. It is the only setting in this subsystem that stops the whole cluster, and it is reached by a timer rather than by a strategy’s verdict — a rolling restart whose replacements arrive less than stable-after apart looks exactly like a cluster that will not settle. A view that moves only because members join and leave cleanly never escalates: churn is not a partition, which is why an empty unreachable set is a hard precondition.

run-coordinated-shutdown-when-down is what a node does once its own downing decision removes it — a strategy’s verdict that includes this node, or down-all-when-unstable. Under off it only leaves: its peers stop counting it, but the node keeps running its actors — the entities and singletons it hosted, an HTTP binding — beside the side that won, which is the second writer a downing decision exists to prevent. Under on, the default, it leaves and then runs the coordinated-shutdown pipeline with ClusterDowningReason, even when the leave fails; coordinated-shutdown.terminate-actor-system and exit-process decide what that run ends in, as they do for a signal. The price of on is that a wrong self-down terminates a node; the two known ones — static-quorum downing a cluster still smaller than quorum-size (issue #933), and keep-oldest downing every survivor once the lowest-addressed node crashed (issue #932) — are fixed, which is when the default moved to on. A downing a peer decides about this node reaches the switch only through this node’s own strategy: a peer that removed it refuses its heartbeats, and a node every peer refuses has its strategy asked at once (issue #940).

configuration-compatibility-check compares effective values, not config values. Each node publishes what it actually resolved for every setting in checked-paths and compares what its peers publish back, so two nodes that differ only because one called .withMaxFrameBytes(…) are still caught — which comparing the config tree could not do, since an explicit option sits above it. checked-paths is an allow-list of what leaves the node, so a setting absent from it is never gossiped; only names something publishes can be compared, and the framework publishes three of them (see Joining and seeds). Absence on either side is silence, so a mixed-version cluster reports nothing rather than everything.

enforce = on bars the diverging peer from this node’s placement candidates and does nothing else. It never downs or quarantines anyone: a misconfigured majority would then evict the correctly-configured minority, which turns a warning into an outage — and the candidate set is a per-node view, so nothing that elects a role from it (a singleton’s host, a shard’s home) reads it, or two nodes would elect two winners.

minimum-members-before-up holds the joining / weakly-up → up transition until the local member map holds at least that many members — the leader’s promotions and a founder’s own self-election alike. It counts members in joining, weakly-up and up, so a leaving member does not hold the threshold open for its replacement, and it is never evaluated in reverse: there is no up → joining transition, so a cluster that later shrinks keeps the members it promoted and holds only new ones.

Per-role thresholds compose with it as an AND — the global count and every configured role’s count must be met. They are written cluster.role.<role>.minimum-members-before-up and ship comment-only, since no leaf here could name a role your deployment invented. What they buy is “do not place work on a cluster that has no backend yet”: shard regions and singletons are hosted by role, so an all-frontend cluster satisfies a global count while being useless to place on.

It is not cluster.bootstrap.minimum-members, which is a wait predicate for awaitReady / isReady and never changes a member’s status. Setting this one largely subsumes that one — a node that is up at all already implies the threshold was met — so there is rarely a reason to set both. And it is not a quorum or a security control: any node may announce itself up, so it bounds accidents rather than adversaries. Arbitration is split-brain-resolver above; note that static-quorum has no “nothing is unreachable” early return yet, so pair a threshold above 1 with a downing strategy you have checked at that cluster size.

While the threshold is unmet the node stays joining, and it says so once — naming the key and the current count — rather than reporting the cold-start stall diagnosis, which would be a false verdict here. See Joining and seeds.

seed-nodes is one list that is correct on every node of a deployment, which is why it is a key at all. A node removes its own address from the list before dialling, so naming the designated first node and shipping the same file everywhere leaves that node with an empty list — and self-electing — while every other node dials it. The shape that does not work is the symmetric one, every node listed: self-exclusion then leaves nobody with the empty list selfElection: 'immediate' requires, so nobody is ever promoted. Config does not create that trap, and the node diagnoses it, but it does make it a one-line mistake — cluster bootstrap with stable observation, which stays a code option, is the way out when the members are not known in advance.

Both leaves are read as lists and only as lists, so a single seed-nodes = ${?SEED_NODES} is refused at start-up rather than split on commas. Write one optional substitution per entry — unset ones drop out of the array:

actor-ts.cluster {
seed-nodes = [ ${?SEED_1}, ${?SEED_2}, ${?SEED_3} ]
roles = [ ${?NODE_ROLE} ]
}

For the single comma-separated variable, seedsFromEnv(...) in code is the first-class form — see seed providers. A malformed entry is refused by Cluster.join before the transport binds, with the offending string in the message.

cluster.seed-nodes and discovery.config.seeds are not two answers to one question, and the order between them is fixed: Cluster.bootstrap runs discovery first and forwards what it found, so a discovered seed wins; this key applies when discovery named nobody or only this node — a discovered list that is this node alone is filtered to nothing, which is silence. CLUSTER_SEEDS is a rung of the same discovery ladder, so a seed it names wins over this key too. An explicit seeds: [] passed to Cluster.bootstrap still wins over both — it says “there is nobody else”, which is an answer rather than a silence, and it is refused while cluster.bootstrap.new-cluster-enabled is off. See actor-ts.discovery.

app-version is the application version this node states to its peers, so the window of a rolling update in which old and new code share one cluster can be read off the cluster itself: it is shown on GET /cluster/members and in every log line that prints a member. It is a label and nothing more — nothing places, routes or downs on it. It ships comment-only, the remote.tcp.advertised-host shape: unset states no version and puts nothing on the wire. It changes per release rather than per node, so the substitution is the usual form, and an unset variable drops the key:

actor-ts.cluster.app-version = ${?APP_VERSION}

A literal version goes in quotes: app-version = 1.0 is a number to HOCON and reaches the peers as "1".

A value from the environment is read as JSON first wherever it parses as JSON. A version that reads as a number comes back in that number’s own spelling — 1.10 as 1.1, 2.0 as 2, 1e3 as 1000 — so releases 1.1 and 1.10 print the same label, a whole number past Number.MAX_SAFE_INTEGER can come back with other last digits (20261104123456789 as 20261104123456788), and one that reads as null, a list or an object stops the start with a ConfigError; a version with a second dot (1.2.3) or a letter (v1.10) is unchanged. Quote such a value inside the variable (APP_VERSION='"1.10"'), or set it in code with withAppVersion(...).

A label is 1 to 64 visible ASCII characters — no whitespace and no control character, because every peer prints it — and Cluster.join refuses one that is not, an empty one included, before the transport binds. A peer’s label that breaks the rule is dropped, never the member. withAppVersion(...) in code wins over the file, as explicit options always do.

selfElection and the transport have no HOCON form. The transport is an object a config file cannot express. selfElection is the one setting whose shared value is not merely useless but unsafe: all-'never' never starts a cluster and all-<delay> has every node self-elect at the same moment, which is the split brain the option exists to close — cluster bootstrap is what hands out a per-node value.

KeyDefaultPurpose
cluster.client.contact-points(unset)Cluster nodes a client with no explicit list dials — each host:port or <system>@host:port, tried in order. Comment-only in reference.conf; see below.
cluster.client.system-name"cluster-client"Synthetic system name the client puts in its hello. It names the client’s side of the handshake and is not an identity.
cluster.client.ask-timeout5sDeadline for ask(path, message) when the call itself names none. A per-call timeoutMs still wins.
cluster.client.connect-timeout5sHow long one contact point gets to answer the hello handshake before the client gives up on it and dials the next.
cluster.client.receptionist.ask-timeout5sDeadline for the ask a cluster node makes on a client’s behalf when an arriving envelope carries an askId.

This block is read differently from every other one on this page, and ClusterClient is why: a client is by definition outside the cluster, so it holds no ActorSystem and there is no system.config above it. Its constructor therefore loads the configuration itself — the same chain ActorSystem.create uses, ACTOR_TS_CONFIG then ./application.conf then the built-in defaults — which is what makes a client built with no options at all a configurable thing rather than a broken one. Pass a Config as the constructor’s second argument to pin it instead, and the filesystem is never consulted.

The receptionist half is the asymmetric one. ClusterClientReceptionist runs inside a system, so it reads that system’s config and loads nothing. It nests under cluster.client rather than joining actor-ts.cluster.receptionist above, which belongs to the discovery Receptionist — a different actor with a different protocol that happens to share the word.

contact-points ships comment-only, the same shape as remote.tcp.advertised-host: the list is per-deployment identity that no default could state, and [] is not the absence of one — an empty list is refused by the validator, so a shipped leaf could only be a value that stops every client that merely copied the file.

client-identity, tls and logger have no HOCON form at all. The last two are certificate material and a Logger instance. The first is the one that is a security decision rather than a packaging one: a client’s synthetic port is drawn from the CSPRNG so that no peer can predict, address or pre-claim its slot, and a fleet sharing one configured value is exactly what that draw exists to prevent. Set it with withClientIdentity(host, port) if you need a stable one.

The transport has no HOCON form — it is an object a config file cannot express. seeds and roles do have one, cluster.seed-nodes and cluster.roles above: they are per-deployment identity, which is why each entry takes its own optional substitution rather than a shared default. A per-role threshold names a role rather than assigning one, so it reads from the file even though the assignment still happens at the join site.

KeyDefaultPurpose
cluster.singleton.role""Restrict hosting to nodes carrying this role tag. "" = any node may host; the empty string is dropped, never passed on.
cluster.singleton.buffer-size1000Messages a proxy holds while the cluster has no host, before it drops the newest to dead letters.
cluster.singleton.hand-over-timeout10sHow long an incoming host waits for every eligible peer to confirm it is not running the singleton, before hosting anyway.
cluster.singleton.use-leaseoffGive every singleton this node starts a lease built from actor-ts.coordination.lease, so only the holder hosts. Refused at start() while coordination.lease.backend = none; a withLease(…) in code wins, and withUseLease(false) opts one singleton out.
cluster.singleton.acquire-retry-interval5sHow long the manager waits before re-acquire()ing a lease it failed to take. Only reached when the singleton has a lease — passed in code, or built by use-lease.
cluster.singleton.max-hand-over-state-bytes1MCap on a warm-hand-over snapshot. A snapshot above it is not sent and the successor starts cold.
cluster.singleton.restart-on-terminationonRe-spawn the singleton after its instance dies unexpectedly — as against the planned teardown of a hand-over.

The block is read by both doors, and the second one is why it exists. cluster.singleton.start(...) layers it under the caller’s StartSingletonOptions, so an explicit withBufferSize(…) still wins per field. cluster.singleton.ref(...) takes no options object at all, so before this block a proxy-only node had no way whatsoever to set its buffer cap — or to learn that the singleton is role-restricted, which is worse: a configured role reaching only start() leaves such a node routing at the plain leader while the managers host on the role member.

Precedence has one turn that reads backwards: a role declared on the actor class’s SingletonKey — or passed to withRole(…) — beats the config file, because both are code and code is the higher layer. That holds on the proxy too, and in either call order: a node that calls ref before start builds its proxy from the file, and the explicit role the start carries then replaces it rather than losing to it. A configured role arriving after an explicit one is discarded in silence for the same reason — it is precedence resolving, not a problem to report.

What the proxy does warn about is two roles from the same layer — two withRole calls, or a key and an options object that disagree. One singleton cannot be restricted two ways and nothing outranks anything, so it keeps the first and names the second in the log.

role = "" is the shape of the key, not a value anyone runs with. It is dropped rather than passed on, and here that is load-bearing twice over: '' would shadow an explicit withRole(…) on the layer above, and StartSingletonOptionsValidator refuses an empty role outright, so a node that copied the shipped file unedited would fail every start().

use-lease builds the singleton’s lease from the coordination block: named <system>-singleton-<type>, owned by this node — its cluster address and incarnation — and renewed on the system’s scheduler. The file picks the backend and nothing about identity, so there is no lease-name: one value for the block would put every singleton on one record, and one written there is refused by start() and ref() alike.

Two more keys are deliberately not here. singleton-identification-interval configures a poll this proxy does not do (it subscribes to cluster events instead), and min-number-of-hand-over-retries counts attempts nothing counts — the wait is bounded by hand-over-timeout. The hand-over re-send cadence is a correctness property of the exchange rather than a tuning knob, and stays a constant.

KeyDefaultPurpose
cluster.pub-sub.gossip-interval1sHow often a mediator pushes its topic set to a random peer.
cluster.pub-sub.max-subscribers-per-topic10000Cap on local subscribers for one topic. A Subscribe past it is answered with SubscribeRejected.
cluster.pub-sub.max-topics10000Cap on distinct topics one mediator tracks — enforced against gossiped topic claims as well as local subscribes.
cluster.pub-sub.max-remote-nodes-per-topic1000Cap on peers that may claim subscribers for one topic.
cluster.pub-sub.send-to-dead-letters-when-no-subscribersonRoute a publish that reached nobody to system.deadLetters instead of discarding it.

The three caps bound what one mediator can be made to hold, and publish fan-out walks all of them — so they are a latency bound as much as a memory one. The gossip half is the one worth knowing about: a peer announcing topics it claims subscribers for used to allocate an entry per name on every receiver, with no local Subscribe involved. See DistributedPubSub.

KeyDefaultPurpose
cluster.receptionist.gossip-interval1sHow often the receptionist gossips its local registrations.
cluster.receptionist.max-subscribers-per-key1000Cap on subscribers for one service key. A Subscribe past it is answered with ReceptionistSubscribeRejected.
cluster.receptionist.max-subscriptions-total10000Cap on key/subscriber pairs across every key on this node — one subscriber on three keys counts as three.

Both blocks layer under whatever the extension’s start(...) was passed, so an explicit withMaxTopics(…) still wins. Stopped subscribers are released by death watch and do not count against either cap.

KeyDefaultPurpose
distributed-data.gossip-interval1sHow often a replica pushes its key set to a random peer.
distributed-data.quorum-timeout5sDeadline for an updateAsync / getAsync that names no timeoutMs; a per-call timeoutMs still wins. Clamped by max-quorum-timeout like a caller’s value. Must be positive.
distributed-data.max-pending-quorum-requests1000Cap on unsettled quorum requests — updateAsync and getAsync share one budget. A request past it is rejected outright. 0 disables the cap.
distributed-data.max-quorum-timeout30sCeiling on a quorum deadline — a call’s own timeoutMs, or quorum-timeout when it names none; a larger value is clamped down to this one. 0 disables the ceiling.
distributed-data.max-gossip-bytes1MByte budget for one gossip frame’s payload. A larger store is pushed a slice per tick, resuming where the last one stopped. 0 removes the budget.
distributed-data.log-data-size-exceeding100KWarn (rate-limited) about a key whose own encoding passes this many bytes. Reports only — the key is gossiped exactly as it would have been. 0 never warns.
distributed-data.durable-keys[]Which keys a configured durableStore persists. Empty means every key. An entry is an exact key name or a prefix with one trailing *.

max-gossip-bytes is always clamped down to remote.max-frame-bytes, so lowering the wire cap lowers the gossip budget with it and no setting can put gossip back over the edge. It matters because the two failures are not comparable: a frame past the wire cap is rejected on its 4-byte length prefix and the receiving transport drops the whole peer association — heartbeats, membership gossip and every cross-node tell along with it — while a budget merely spreads the same state over more ticks. A single key whose own encoding exceeds the budget cannot be sliced; it is skipped with a rate-limited warning naming the key and both sizes, counted in distributed_data_gossip_skipped_keys_total, and it does not converge.

The block is top-level rather than under cluster.* (where pub-sub and receptionist live) because the module is: DistributedData ships from src/crdt/, and the cluster is a positional argument to start(cluster) rather than one of its tunables. durableStore has no key here — it is a DurableStateStore instance, which a config file cannot express.

Both caps bound the unsettled set itself. Every pending quorum request holds a promise, a timer and a target set alive until its deadline passes, so an uncapped replicator under load accumulates all three with nothing to stop it. Refusing past max-pending-quorum-requests turns what would arrive later as a timeout storm into immediate rejections that name the knob. See Quorum reads and writes.

log-data-size-exceeding reports on the same measurement max-gossip-bytes takes, one order of magnitude earlier, and changes nothing about what travels. A key past the whole budget is already loud; a key at a large fraction of it gossips perfectly while consuming that fraction of every tick it appears in, so the rest of the store sweeps proportionally slower with nothing to say why. 100K is roughly a tenth of the shipped budget — ten such keys fill a whole frame — and deliberately not Akka’s 10KiB, which is a tenth of that again and would fire on the first legitimate ORSet a deployment stores. The line has its own quiet period rather than sharing the oversize warning’s: raising max-gossip-bytes is the fix for that one and makes this one more relevant, so neither may silence the other.

durable-keys narrows what a configured durableStore writes; without a store it is inert, and a non-empty list with no store is warned about at startup. An empty list means every key — the behaviour of every release before the option existed — never “persist nothing”; persisting nothing is what configuring no store does. An entry is an exact key name or a prefix with one trailing * (session-*), and that is the entire syntax: a richer pattern would mean compiling a matcher out of a config file, and new RegExp(…) over operator-supplied text is a ReDoS surface on the path that decides what survives a restart. A replica’s record is rewritten whole on every save, so removing an entry drops the keys it named from the persisted record on the next mutation. See Durable storage.

max-quorum-timeout bounds the other axis. A pending request holds one of those slots for its whole deadline, so a single caller passing an hour-long timeoutMs parks the budget for an hour and locks out later callers who never came near the cap themselves.

quorum-timeout is the deadline a quorum call gets when it names none, and max-quorum-timeout clamps it exactly as it clamps a caller’s timeoutMs. It is a key of its own rather than actor.ask-timeout: that one moves the default of ActorRef.ask, and how long a replica holds a pending slot for its peers to answer is a different wait. Unlike the two caps it has no off switch, and 0 cannot be one: the replicator arms a 0 deadline like any other, so it expires at the next timer tick — a write fails there and a read settles for what this replica alone holds — unless every replica it waits on has already answered, and the validator refuses it.

KeyDefaultPurpose
coordination.lease.backendnoneWhat the framework builds its leases with — none or kubernetes — when a consumer’s switch asks for one. in-memory is refused by name. See leases the framework builds.
coordination.lease.ttl(unset)Lease TTL for the whole deployment. Ships no leaf — a value here would supply ttlMs for every lease in the process and make the “ttlMs is required” guard unreachable.
coordination.lease.renewal-interval(unset)How often a held lease is renewed. Ships no leaf — unset selects a third of the TTL with a floor (100 ms in-memory, 500 ms Kubernetes), capped at half the TTL so a renewal always comes round before the record lapses, and 0 cannot mean “derive it” because the validator rejects it.
coordination.lease.kubernetes.namespace(unset)Namespace holding the Lease object. Ships no leaf — unset means “read namespace-path from the Pod’s ServiceAccount mount”, and "" is rejected.
coordination.lease.kubernetes.namespace-path"/var/run/secrets/kubernetes.io/serviceaccount/namespace"File the Pod’s namespace is read from.
coordination.lease.kubernetes.token-path"/var/run/secrets/kubernetes.io/serviceaccount/token"File the bearer token is read from. A path, never the token.
coordination.lease.kubernetes.ca-path"/var/run/secrets/kubernetes.io/serviceaccount/ca.crt"File the CA cert pinning the API server’s TLS is read from.
coordination.lease.kubernetes.token-reload-interval1mHow long a credential read from that mount is reused before the token file’s mtime is checked again. No effect on an explicit authToken.
coordination.lease.kubernetes.operation-timeout10sCeiling on one API-server request.
coordination.lease.kubernetes.lease-name-max-length253Lease object names longer than this are truncated to a stable head plus a hash of the full name. 253 is the DNS-1123 subdomain bound the API server enforces.

The block serves two kinds of lease. One the framework builds for a consumer that asks reads it from the node’s own configuration — see below. One you build in code reads it under the options you pass to new InMemoryLease(…) / new KubernetesLease(…), in the usual order: explicit options win, then this block, then the built-in defaults. Such a lease may have no ActorSystem in scope, so its constructor loads the config chain itself, honouring ACTOR_TS_CONFIG and ./application.conf — unless you hand it one: new KubernetesLease(options, system.config) reads that config and nothing else, overrides included.

Three keys ship no leaf at all and are listed above only so the names are discoverable. Each is a field the code requires or derives, and a shipped value would make hasPath true forever — which is precisely how the thing it stands in for becomes unreachable. Set one in your own application.conf and it is read normally:

actor-ts.coordination.lease {
ttl = 30s
kubernetes.namespace = "actors"
}

acquire-retries and acquire-retry-delay are not settable here. The two backends ship different built-in defaults — 3 attempts / 100 ms for Kubernetes, 1 / 50 ms in memory — and one leaf could not express both without silently unifying them. Set them per lease in code.

Three consumers ask for a lease by configuration, and all three get it from this block:

SwitchLease nameRefused, if misconfigured, when
sharding.use-lease = on<system>-sharding-<type>, one per sharded typethe type starts
cluster.singleton.use-lease = on<system>-singleton-<type>, one per singletonthe singleton starts
split-brain-resolver.active-strategy = lease-majority<system>-split-brain-resolver, one per clusterthe node joins its cluster
actor-ts.coordination.lease {
backend = kubernetes
ttl = 15s
}
actor-ts.cluster.singleton.use-lease = on

The file chooses the backend and its tuning, and nothing about identity. The name is derived per consumer — lower-cased into a valid Kubernetes object name, with a hash of the original appended when that changed it, so OrderService and orderservice stay two records — and fitted into kubernetes.lease-name-max-length. The owner is the node that builds the lease: its cluster address and its incarnation, so a restarted pod waits out its predecessor’s TTL instead of inheriting a record the predecessor may still be acting on. Neither has a key; name, owner, plugin, acquire-retries and acquire-retry-delay written into this block are refused rather than ignored, and so are a lease-name in the sharding or singleton block and any key under split-brain-resolver.lease-majority.

What else is refused, each naming the key: a switch that asks for a lease while backend = none, an unknown backend, in-memory — its store lives in one process or worker thread, so a lease built from it would gate nothing — and a missing ttl, which no default can stand in for. The block itself is checked whenever a node joins its cluster, so a misspelt backend does not wait for the first consumer that asks. An explicit withLease(…) still wins over a switch, and withUseLease(false) opts one sharded type or singleton out of a deployment-wide on.

A backend that is named but cannot be reached — no API server, no ServiceAccount mount, credentials the server rejects — is not refused at startup, because nothing in a file can tell. The consumer starts with its lease and fails closed: every acquire that fails is retried — the singleton manager and the coordinator log it at warn and wait out their acquire-retry-interval, lease-majority asks again at its next decision — and until one succeeds no node hosts the singleton, the coordinator allocates no shards and lease-majority reaches no verdict. Nothing runs as though it held a lease it could not acquire.

Persistence’s per-entity lease() hooks on PersistentActor and ReplicatedEventSourcedActor stay code: they need a lease per persistence id, which a switch cannot express.

KeyDefaultPurpose
cluster.bootstrap.stable-margin5sHow long the contact-point set must be unchanged before the observation calls it stable.
cluster.bootstrap.poll-interval1sHow often discovery is polled during the observation.
cluster.bootstrap.max-wait60sTotal budget for the observation before it gives up and fails the bootstrap.
cluster.bootstrap.required-contact-points1How many contact points a stable set must contain. 1 keeps single-node development working; a value matching the expected replica count is what catches discovery that is stably wrong rather than merely slow.
cluster.bootstrap.self-election-grace10sHow long the lowest-addressed node waits for a peer to promote it before forming a cluster itself.
cluster.bootstrap.new-cluster-enabledonWhether a node that finds nobody to join may found a cluster. on is right for a deployment’s first start only, and every start logs a warning while it is; set it off once the cluster exists. Off, no bootstrapped node self-elects, on either path, and an explicit seeds: [] is refused — a node that finds nobody fails its readiness wait instead of starting alone.
cluster.bootstrap.minimum-members1Fewest up members — self included — before awaitReady / Cluster.isReady counts the cluster as ready.
cluster.bootstrap.await-ready(unset)Readiness budget. Comment-only in reference.conf: unset is what selects the computed default (self-election-grace + 5s behind stable observation with new-cluster-enabled on, 5s otherwise), and a key that is always present could not express it.
cluster.bootstrap.discovery.method"auto"Which seed provider the bootstrap builds — auto, config, dns or kubernetes. auto is the ladder; the other three pin one rung so a misconfigured deployment fails loudly instead of falling through.
cluster.bootstrap.discovery.service-name""The DNS name the dns provider resolves and the Kubernetes Service whose Endpoints the kubernetes provider reads. "" means “not stated here”, and CLUSTER_SERVICE_NAME then answers.

The five observation timings are read only when stableObservation is on; new-cluster-enabled, the readiness pair and the discovery sub-block are read by every Cluster.bootstrap call. All of them layer under the explicit options, so a withRequiredContactPoints(…), a discovery: 'dns' or a withNewClusterEnabled(false) in code still wins.

A method outside those four names is refused, not ignored. Falling back to auto on a typo would leave one node discovering differently from its peers, which is the cold-start split brain the observation exists to close.

selfElection has no key here and will not get one: it differs per node by construction, so one shared value would either stop every node from starting or have all of them form a cluster at once. new-cluster-enabled is the shared value that is safe: it picks no policy per node, it only takes “found a cluster” off the table, so off on every node of a running cluster is correct on all of them. See Cluster bootstrap.

KeyDefaultPurpose
discovery.dns.cache-ttl60sHow long the DNS provider reuses one resolved answer. In-process and per provider; failures are never cached. 0 disables caching.
discovery.dns.use-srvfalseRead SRV records instead of A records. SRV carries a port per target, so each address is paired with the record’s port rather than this node’s remoting port.
discovery.dns.pinned-addresses(unset)CIDRs (A-record mode) and/or host suffixes (SRV mode) a resolved address must match; anything else is discarded rather than offered as a seed. Comment-only in reference.conf, because an always-present empty list could not say “no pinning” — see below.
discovery.kubernetes.request-timeout10sCeiling on the one HTTPS request the Kubernetes provider makes to the API server — a deadline on the whole exchange, TLS handshake included, so a server that accepts the connection and never answers fails the lookup instead of hanging the bootstrap.
discovery.kubernetes.namespace(unset)Namespace whose Endpoints object the Kubernetes provider reads. Comment-only in reference.conf, for a different reason than the pin lists: CLUSTER_NAMESPACE sits underneath it, so a published value would be the config layer on every node and the variable would be unreachable. Unset, the chain is this key, then the variable, then the built-in "default".
discovery.kubernetes.pinned-addresses(unset)CIDRs the discovered pod IPs must fall inside. CIDRs only — Endpoints resolve to IPs, so a host suffix could never match. Comment-only, same reason.
discovery.config.seeds(unset)Static [system@]host:port list — the first rung of the auto ladder and the whole of method = "config". A deployment topology: one list is correct on every node when it names the designated first node by the address it advertises; a list naming every node never cold-starts without stableObservation. Comment-only for precedence: CLUSTER_SEEDS sits beneath it, and even a published [] would silence it — [] drops this rung rather than meaning “unset”, and method = "config" refuses it.

Top-level rather than under cluster.* for the reason distributed-data is: the module is. A SeedProvider is built and then handed to the cluster, and the same providers serve a hand-wired Cluster.join that never bootstraps. Which provider runs is not here either — that is cluster.bootstrap.discovery.method above, a property of the join rather than of a provider, so a deployment can pin the DNS answer without also deciding the ladder.

A static seed list has two homes, and the order between them is fixed. Under Cluster.bootstrap discovery runs first and what it returns is forwarded — discovery.config.seeds, or CLUSTER_SEEDS when the file names none, both rungs of this ladder — so a discovered seed wins, and cluster.seed-nodes applies only when discovery named nobody or only this node. An explicit seeds: [] passed to Cluster.bootstrap outranks both, while new-cluster-enabled allows it at all. Either list is written the same way: name the designated first node and ship one file everywhere. A list naming every node is the symmetric trap in both homes.

Discovery has always been steerable by CLUSTER_SEEDS, CLUSTER_SERVICE_NAME and CLUSTER_NAMESPACE. Those variables kept their meaning and moved below this block rather than above it:

explicit options > actor-ts.discovery.* > CLUSTER_* > built-in defaults

which is the framework’s ordinary precedence with the environment appended at the bottom, not a fourth layer bolted on top of it. An env-only deployment therefore behaves exactly as it did before these keys existed, and an application.conf can now override a variable it could not previously reach.

That last claim is about reference.conf as much as about the ordering, and it is what decides which of these keys may ship a value at all. Presence is the read — a published leaf is a configured value on a node that configured nothing — so a key with a CLUSTER_* variable beneath it ships comment-only: discovery.kubernetes.namespace and discovery.config.seeds, with cluster.bootstrap.discovery.service-name solving the same problem the other way, published as "" and dropped by its reader. cache-ttl, use-srv and kubernetes.request-timeout carry published values because nothing sits under them to shadow.

A deployment that wants a variable to outrank its own application.conf lifts it there itself:

actor-ts.cluster.bootstrap.discovery.service-name = ${?CLUSTER_SERVICE_NAME}
actor-ts.discovery.kubernetes.namespace = ${?CLUSTER_NAMESPACE}

That is a read during parsing (see Environment substitution), not a precedence layer — the value lands in whichever config layer the file belongs to, and the usual order applies from there.

KeyDefaultPurpose
remote.tcp.host(unset)The interface to bind. Read when the options leave host unset. Comment-only in reference.conf: on the Cluster.bootstrap path CLUSTER_HOST / POD_IP / HOSTNAME sit beneath it, and a published value would make them unreachable. Unset, the chain goes on through those variables (bootstrap only) to the built-in "0.0.0.0" — a wildcard belongs here and is the default.
remote.tcp.advertised-host(unset)The address peers dial — this node’s identity. Unset, it follows remote.tcp.host when that is routable, then CLUSTER_HOST / POD_IP / HOSTNAME, then loopback. A wildcard is refused. Deliberately absent from reference.conf, because a shipped value is what “unset” would have to be distinguishable from.
remote.tcp.port(unset)The port to bind. Read when the options leave port unset. Comment-only for the same reason, with CLUSTER_PORT beneath it on the bootstrap path; the built-in default is 2552.
remote.tcp.advertised-port(unset)The port peers dial. Unset means the same as remote.tcp.port — set it only where the deployment publishes the process on a different one. Absent from reference.conf for the same reason as advertised-host.
remote.max-frame-bytes16MPer-frame wire cap. A frame whose length-prefix exceeds it is rejected before any payload is buffered.
remote.tls.enabledfalseNot honoured — true buys a startup warning, not encryption. See below.
remote.untrusted-modefalseAdmit an inbound envelope only when trusted-selection-paths lists its target. Off, any /user actor is addressable by name — which is what makes an ActorRef work across nodes. /system is refused either way. See below.
remote.trusted-selection-paths[]Paths a peer may address by name while untrusted-mode is on. Empty means: nothing beyond the framework endpoints this node registered.
remote.handshake-timeout5sHow long a connection may sit without its half of the handshake before it is torn down. One value for both directions — see below.
remote.connect-timeout(unset)How long a dial may take to open — the TCP connect and, over TLS, the TLS handshake — before it is aborted and logged as one that could not connect. Unset, it is remote.handshake-timeout, which it may not exceed. Comment-only in reference.conf, so “unset” stays expressible — see below.
remote.outbound-queue-size1000How many frames are held for a peer that cannot take them right now, oldest dropped first.
remote.max-inbound-connections1024How many inbound connections this node accepts before it refuses sockets outright, newest refused rather than oldest evicted.
remote.incomplete-frame-idle30sHow long a connection may hold a half-received frame with no further byte arriving. A stall bound, re-armed on every chunk.

host/port are the bind pair and advertised-host/advertised-port the identity pair: the first says where the listener opens, the second says what goes into every gossip frame for peers to dial back. They are the same values until a deployment remaps one, which is why naming one routable host and one port still does both jobs and nothing configured today moves.

Both entry points read the bind pair from config — Cluster.join and Cluster.bootstrap alike — so a deployment can move it out of code entirely:

actor-ts.remote.tcp {
host = "0.0.0.0"
port = ${?ACTOR_TS_PORT} # env-var substitution
}

On the Cluster.bootstrap path the environment sits beneath this block — the order actor-ts.discovery already uses:

explicit options > actor-ts.remote.tcp.* > CLUSTER_HOST / POD_IP / HOSTNAME, CLUSTER_PORT > 0.0.0.0, 2552

A port in the file therefore wins over CLUSTER_PORT, and the variable still answers on a node whose file names none — with ACTOR_TS_PORT unset above, port drops out and CLUSTER_PORT decides. That is why neither leaf ships in reference.conf: a published value would be the config layer on every node. Cluster.join consults no variable for the bind pair; it takes its options, then this block, then the built-in pair.

A published container port is the case that needs all four. The process listens on 2552 inside the container, docker run -p 3000:2552 puts it on 3000 outside, and 3000 is the number that belongs in every other node’s seed list:

actor-ts.remote.tcp {
host = "0.0.0.0" # bind every interface — the container
port = 2552 # does not know its published address
advertised-host = ${?HOST_IP} # what peers dial …
advertised-port = 3000 # … and on which port
}

Under Kubernetes only the host half moves: pod-to-pod gossip dials the container port directly, so advertised-host = ${?POD_IP} on its own is the whole configuration.

remote.max-frame-bytes applies to the transport the cluster builds for itself. If you construct a TcpTransport yourself and pass it via withTransport(…), set its cap there — the framework will not re-cap a transport it did not create.

An inbound envelope frame carries the target path the sender chose, and the node resolves it against its own actor tree. That is the one thing on the cluster wire a remote party picks freely, and the two keys above are the scope around it.

/system is not part of that scope. The framework’s own actors — shard coordinators and regions, singleton managers, the pub-sub mediator, the DistributedData replica, both DevTools lanes — are reachable only through the per-path handler each of them registers, in both modes. That door attaches the connection’s identity to the frame; resolving a path by name never did, which is why a body arriving that way had no sender at all. This is a change in behaviour: before it, anyone who completed a hello could address them (issue #964).

untrusted-mode narrows the other half. Off — the default — a peer may name any /user actor, which is what a RemoteActorRef rebuilt from a wire ref does and what makes an ActorRef usable across nodes at all. On, only the paths you list:

actor-ts.remote {
untrusted-mode = true
trusted-selection-paths = ["/user/orders/*", "/user/reporting/intake"]
}

An entry is one exact path unless it ends in /*, in which case it is that path and everything below it. The suffix is segment-anchored, so /user/orders/* admits /user/orders/7 and refuses /user/orders-archive; nothing else here is a pattern, and a * anywhere but as the whole final segment is rejected at startup rather than matched literally. Paths are written guardian-rooted, the way the tree renders them; the leading / is optional.

Turn the mode on where the cluster network crosses a boundary you do not control — the same networks remote.max-frame-bytes is worth lowering on. What it costs is that any actor a peer addresses by name has to be listed, including the ones reached through a ref that travelled over the wire, so start by watching cluster_envelope_refusals_total{reason="not-allow-listed"} on a node with the mode on and an allow-list you expect to be complete.

Refusals are counted rather than logged one by one: an envelope is its own frame, so a line per refusal would let a peer write this node’s log at message rate. The first refusal of each reason is logged at WARN and further ones are folded into at most one line every 30 seconds, naming the connection’s peer and never the requested path.

The same rule applies to ClusterClientReceptionist, and it is the more exposed of the two seams: a ClusterClient never joined the membership ring. A refused path is answered with the identical path not found the client gets for a path that does not exist, so the endpoint cannot be used to map the actor tree.

Four of the last five keys bound what a party that can open a TCP connection to the cluster port is able to make this node hold. All four have been enforced since the transport was hardened; what changed is that they are settable (issue #846). The fifth, connect-timeout, bounds this node’s own dials instead and is described below:

actor-ts.remote {
handshake-timeout = 5s
outbound-queue-size = 1000
max-inbound-connections = 1024
incomplete-frame-idle = 30s
}

handshake-timeout covers a connection that never speaks its half of the handshake — a dial that never gets its hello-ack, and an accepted socket that never sends a hello. It is one key for both directions on purpose. The dialling side’s clock starts before the TCP connect and the TLS handshake, the accepting side’s after the accept, so with one number the peer that is still trying has always given up first and the acceptor can never be the deadline that punishes a slow-but-legitimate dial. A split dial/accept pair would let an accept deadline set below the dial deadline make a healthy peer permanently unjoinable, with nothing in either node’s log saying why.

connect-timeout is not that split: it bounds only how long this node’s own dial may take to open — the TCP connect and, on a TLS dial, the TLS handshake — under the handshake deadline that still bounds the whole dial (issue #1475). A dial that has not opened by then is aborted and logged as could not connect to … within N ms; one that opened is handshake-timeout’s to end, and its line says connected to …, but no hello-ack came. Set it lower than handshake-timeout to learn sooner that a peer is not there, while a slow one still gets the whole handshake deadline to answer:

actor-ts.remote {
handshake-timeout = 5s
connect-timeout = 2s
}

It ships comment-only, the tcp.advertised-host shape: unset means “the same as handshake-timeout”, the one deadline a dial had before the key. It may not exceed handshake-timeout — both validators refuse that, a lone connect-timeout = 10s against the 5 s default — and a shipped value of its own would have refused every handshake-timeout set below it, so lowering the one key an operator already knows can never trip a rule about one they never wrote.

incomplete-frame-idle covers the other half: a connection that spoke and then went silent mid-frame. It is a stall bound rather than a budget for the frame — it is re-armed on every chunk, so a peer pushing a large frame over a congested link is never punished for being slow, only for stopping. Keep it above handshake-timeout; both validators refuse a value at or below it, because a socket that sends nothing at all never reaches this deadline and the handshake timer is what covers that one. What they compare is the resolved pair, not the pair you wrote: writing one of the two keys on its own is checked against the other’s built-in default, so a lone incomplete-frame-idle = 1s is refused for sitting under the 5 s handshake-timeout it would run against.

max-inbound-connections is what stops either cost from being multiplied by opening sockets in a loop, and it is the half of the inbound-memory bound worth tightening: that bound is this count times what one connection may buffer. Set it from the real peer count where you know it — one inbound connection per peer in a full mesh, plus whatever ClusterClients dial in — and leave headroom, because refusing a legitimate peer is a partition. The newest connection is refused rather than the oldest evicted; eviction would let an attacker push established peers off the node.

outbound-queue-size is the one key here that bounds what this node holds rather than what a peer holds against it: frames written for a peer that cannot take them right now, with the oldest dropped first, because the newest membership and heartbeat state is the state worth keeping. Today that is the buffer in front of the handshake, so a tell racing the handshake is held rather than lost. The key is named for the category and not for that one buffer: the post-handshake backpressure queue (issue #931) is the same quantity with the same policy and the same warning, and will land under this key rather than a second one.

None of the five has an “off” spelling. 0 is refused for each, because it is a distinct way of breaking the node rather than a way of removing a cap: no handshake window, no time for a dial to open, no room to buffer, no inbound connection admitted, no connection allowed to end off a frame boundary.

These reach the transport the cluster builds for itself. A TcpTransport you construct and pass via withTransport(…) carries its own — set them in its TcpTransportOptions.

KeyDefaultPurpose
http.backend"fastify"One of fastify / express / hono.
http.shutdown-grace-period0msHow long unbind() lets in-flight requests drain before connections are forced. 0 forces immediately.
http.server(see below)Connection-level bounds for the listening socket itself.
http.cors(see below)Per-route defaults for the cors() directive.
http.hsts(see below)The policy the hsts() middleware sends.
http.request-timeout(see below)The handler deadline of the requestTimeout() middleware — not http.server.request-timeout.
http.client(see below)Outbound HttpClient defaults.
http.websocket(see below)Server-side WebSocket defaults for websocket() routes.

http.backend only decides what newServerAt(...).bind() uses when the builder was given no backend of its own — useBackend(new HonoBackend()) always wins, and is still the only way to pass a backend you configured or wrote yourself. An unrecognised name fails the bind() with a ConfigError rather than silently falling back to Fastify. Express and Hono are optional peer dependencies, imported only if you name them.

The grace period defaults to 0 — force as soon as the server closes — because that is what unbind() has always done in practice. Raise it if you want in-flight requests to finish.

It is usually an upper bound rather than a delay: unbind() returns as soon as the server has actually closed. Where a backend’s close() cannot settle — Express holding a live WebSocket, for one — the window becomes a deadline that is always reached, so a large value there is time you always pay. A caller that passes its own value — binding.unbind(1_000) — overrides the config.

The bounds on a connection — as against a route on it — come from actor-ts.http.server:

KeyDefaultPurpose
http.server.idle-timeout(backend’s own)How long an idle connection is held before it is closed — a keep-alive HTTP/1.1 connection between requests, and an HTTP/2 session with nothing moving on it. Ships no leaf — see below. 0 disables it — on the Hono backend under Bun, where it is the only bound on a request whose body stops arriving, that leaves such a connection open until the client closes it (§ below). At most 2147482647 ms — on the Hono backend under Bun, where it is a wider bound, at most 255s (§ below).
http.server.header-timeout60sHow long a connection may take to deliver its complete header block before it is answered 408 and destroyed. The slow-loris guard, held by actor-ts itself — see below. A shorter request-timeout is the header deadline too: the guard runs on the smaller of the two. 0 disables it. At most 2147483647 ms.
http.server.request-timeout300sHow long a connection may take to deliver a request in full, headers and body. Bounds receiving, never answering — a handler’s deadline is http.request-timeout. Shorter than header-timeout, it bounds the header phase as well, since the headers are part of the request. At most 4294967295 ms.
http.server.max-connections(unlimited)Concurrent connections the listening socket accepts before it starts closing new ones. Ships no leaf — see below.
http.server.max-content-length(the backend’s own)The largest request body accepted, in bytes; a larger one is answered 413 before the handler runs. Read as a size (8MiB). Ships no leaf — see below.
http.server.max-header-bytes(the runtime’s own)The largest request header block accepted, in bytes; a larger one never reaches a handler. Read as a size (16KiB). Ships no leaf — see below.

The usual order applies per field: newServerAt(...).withServerOptions(...) wins, then this block, then the built-in default. They are resolved once at bind(), before the backend is built. The timeouts and max-connections are installed on the server at listen(), so they reach a backend you constructed and passed to useBackend(...) exactly as they reach the one the framework builds. The two size caps — like tls and http2 — are fixed when the server is built, so the framework builds its backend with them, and a backend you built yourself has to carry them: a hand-built FastifyBackend adopts them only through new FastifyBackend(fastifyFactoryOptions(serverOptions)), and bind() refuses a backend whose own cap differs from a set key — Fastify’s bodyLimit or its server’s header cap, withMaxBodyBytes on Express or Hono — rather than serve under either number. An equal cap binds, and an unset key refuses nothing.

The three durations are refused at bind() above what the runtime can hold where each one ends up, because past that a deadline meant as “effectively never” comes out short. header-timeout and idle-timeout end up in a timer, which arms anything over 2147483647 ms as 1 ms; idle-timeout stops a second under that, at 2147482647 ms, because both runtimes add a second to it. request-timeout ends up in Node’s connection sweep, which reads it as a 32-bit number, so its ceiling is 4294967295 ms. HOCON reaches both in one line: 30d is 2 592 000 000 ms, past the timer’s ceiling, and 60d is past the sweep’s.

actor-ts.http.server {
idle-timeout = 5s
request-timeout = 30s
max-connections = 10000
max-content-length = 8MiB
}

Four leaves ship no value and are listed above only so the names are discoverable, for the same reason four of the CORS leaves do: a published literal would be a number nobody chose.

idle-timeout unset keeps whatever the backend picked, and the backends disagree on purpose — 72 s on Fastify against node:http’s 5 s on Express and on Hono-over-Node. Fastify’s is high so the server outlives a load balancer’s idle window and the balancer never posts a request onto a socket that is already closing; five seconds is the platform’s. Neither is wrong, so the block picks no winner. Set it to make them agree. Hono under Bun is the one backend that does not keep its runtime’s own: Bun’s 10 s cut slow handlers with no response, so there an unset idle-timeout is derived from the request deadline instead — 36 s by default (§ above).

It bounds an idle HTTP/2 session too, and request-timeout an HTTP/2 stream’s receive. keepAliveTimeout and requestTimeout, which carry them to an HTTP/1.1 connection, are properties no HTTP/2 session or stream reads, so on a listener with http2 on actor-ts runs timers of its own: a session that has had no stream open for idle-timeout is closed with a GOAWAY — the same value on both runtimes, and a PING frame resets nothing — and a stream whose request is still arriving at request-timeout is answered 408 and reset. A stream in flight holds its session, so a slow handler, a long poll and an SSE stream outlive the idle bound as they do on HTTP/1.1, and a request received in full is never cut by the receive deadline. Unset, an idle HTTP/2 session is left to Fastify’s own session timer — 72 s on Node, 144 s on Bun, which fires it at twice the value and lets a PING reset it — and on Hono over Node to nothing at all. On Bun the HTTP/2 listener bounds a connection that negotiates HTTP/1.1 on the same port by neither key, so there both are reported held for HTTP/2 only and bind() warns. None of this is the Hono backend under Bun, whose sessions Bun.serve’s own whole-connection bound holds (§ above), set or derived: an idle session there was closed within one sweep of a 4s value (bun 1.4.2), and a silent stream does not outlive it.

max-connections unset is unlimited, which is what every release before this key did. It is server-wide, unlike the http.websocket.max-connections below, which is per route: it counts every connection the process accepts on this binding — WebSocket upgrades included, and an attached DevTools server too, since DevTools binds through the same system.http(...) path.

max-content-length unset keeps each backend’s own body cap — the 1 MiB every shipped backend applies, or what withMaxBodyBytes (Express, Hono) or bodyLimit (a Fastify you built) set. Set, it is the cap on every backend and every runtime: each backend counts a body’s bytes in code of its own, so a declared Content-Length over it is refused before a byte is read, and a chunked body is abandoned once it crosses it — 413 either way, before the handler runs. A backend built with a different cap of its own is refused at bind(), naming both; there is no rule for which of two numbers wins, because either answer leaves one of them silently not held.

max-header-bytes unset keeps the runtime’s own: 16 KiB on node:http, and on Bun the process-wide --max-http-header-size, 16 KiB too unless the process was started with another. Set, a request whose header block is larger never reaches a handler — node:http answers 431, though a client still writing when the server gives up may see a reset instead. It is an option a server takes when it is built, so it reaches one only where actor-ts builds it: Fastify’s factory options, the node:http server Express is served from, and @hono/node-server’s serverOptions — the table above says where that leaves a gap.

request-timeout is enforced by a periodic sweep whose interval is http.createServer’s connectionsCheckingInterval — 30 s by default, and a factory option actor-ts does not set — so a connection is closed no earlier than the value set here and no later than one sweep after it: measured on bun 1.4.0, a 2s request-timeout closed a stalled body at 30.0 s. What the peer is told depends on the backend. A bare node:http server answers 408 before closing; the default Fastify backend under Bun closes with no status line at all, because Fastify’s clientError handler writes its 408 and then destroys the socket, and on bun 1.4.2 a handler of that shape delivers nothing. header-timeout is not swept, because it is not the runtime that enforces it: it fires at the value set here.

Both ship the number http.createServer already uses, so publishing them changed no bound that was already being held — but Fastify sets requestTimeout to 0, no bound at all, so on the default backend the published 300s is a deadline where there previously was none. At the 1 MiB body cap that is a client sending under 3.5 KB/s; raise it if you accept legitimately slower uploads, or set 0 to opt out.

Setting header-timeout = 0 opts out of the slow-loris guard entirely: no deadline is armed and the property is cleared. A runtime may still hang up on its own — bun 1.4.0 drops a connection carrying no complete request after about 12 s whatever this says — so 0 buys an unbounded header phase only where the runtime grants one. The TLS handshake was inside the guard’s window too, so a handshake that never completes is then the runtime’s to end as well: Bun’s HTTPS listener closes one after about 12 s, but an HTTP/2 listener waits for the TLS handshake timeout, 120 s on bun 1.4.2 and node v26.10.0 alike.

request-timeout bounds receiving only — the clock stops once the request has arrived — so a slow handler, a long poll and an SSE stream are unaffected. The route-level requestTimeout() middleware is the other half and is deliberately a different surface, with a key of its own, http.request-timeout below: it bounds how long a handler takes to answer, this bounds how long a peer takes to ask.

The cors() route directive reads its per-field defaults from actor-ts.http.cors:

KeyDefaultPurpose
http.cors.origins(unset)Exact-match origin allowlist, e.g. ["https://app.example"]. Ships no leaf — see below. A "*" entry is refused.
http.cors.methods(unset)Access-Control-Allow-Methods. Ships no leaf — unset follows the methods registered at each pattern.
http.cors.allowed-headers(unset)Access-Control-Allow-Headers. Ships no leaf — unset echoes the sanitised request headers.
http.cors.exposed-headers[]Access-Control-Expose-Headers. [] sends none.
http.cors.credentialsfalseAccess-Control-Allow-Credentials: true. Forbidden with "*" origins.
http.cors.max-age(unset)Preflight cache lifetime in seconds, a bare integer. Ships no leaf — unset sends no Access-Control-Max-Age at all.

The usual order applies per field: what cors(options, routes) names in code wins, then this block, then the built-in default. So a deployment can move the allowlist out of code entirely and keep withCredentials() where it is.

Two of the option arms are code-only and have no key here. The "*" wildcard is one: withAnyOrigin() is documented as the explicit opt-in, and a config file that could write origins = ["*"] would widen every cors() route in the process to any origin with one line — so a "*" in this list is refused with a ConfigError naming the key. The other is withOriginPredicate(...), which is a function and has no HOCON spelling at all.

Four leaves ship no value and are listed above only so the names are discoverable — a published literal would be worse than no key. methods and allowed-headers have defaults computed per pattern and per request, which a fleet-wide list would override; max-age unset means the header is not sent; and a shipped origins would satisfy the required-origins check for every route in the process, turning a cors() that names no allowlist anywhere from a loud error into a silent deny-all. Set any of them in your own application.conf and it is read normally:

actor-ts.http.cors {
origins = ["https://app.example", "https://admin.example"]
max-age = 600 # seconds — not a duration string
exposed-headers = ["x-request-id"]
}

Values are validated on the merged result, so a bad one throws OptionsError naming the field rather than reaching a browser as a header it will reject.

This block is resolved when the route tree is compiled — inside bind(), the first moment the tree and the ActorSystem are both in scope. That is also where a cors() with no origins in code and none in config now fails, rather than at the cors(...) call itself.

The hsts() middleware — strictTransportSecurity() by its long name — reads its policy from actor-ts.http.hsts:

KeyDefaultPurpose
http.hsts.max-age15552000How long a browser keeps the pin, in seconds (180 days) — a bare integer, not a duration string. 0 and anything below 86400 (a day) are refused here; code may set any value.
http.hsts.include-sub-domainstrueEmit includeSubDomains.
http.hsts.preloadfalseEmit preload. Needs a max-age of at least a year and include-sub-domains.

The usual order applies per field: what hsts(options) names in code wins, then this block, then the built-in default. The merged policy is validated once, when the route tree is compiled inside bind() — so withPreload() in code over a year of max-age from this block is a valid policy, and one that cannot back its preload fails bind() with an OptionsError rather than sending a header the preload list will refuse.

actor-ts.http.hsts {
max-age = 63072000 # seconds — two years, not a duration string
preload = on
}

A max-age below 86400 — one day — is refused with a ConfigError naming the key and the floor. 0 tells every browser to forget the pin, and a shorter pin than a day has lapsed before a visitor comes back the next day, so one line in a configuration file would un-pin every client of every hsts() route in the process. Code may still set any value with withMaxAge(...) — the five-minute first stage of hstspreload.org’s ramp-up, withMaxAge(300), and withMaxAge(0), which switches HSTS off, included.

The block governs the hsts() middleware only. The hsts field of the securityHeaders() bundle and of withSecurityHeaders(...) is code-only, and where both paths emit the header, the route-level hsts() wins — see Security headers.

A middleware is built before any ActorSystem exists, so hsts() carries a hook that compile() resolves against this block. Wrapped in a function of your own — (request, next) => hsts()(request, next) — it is out of compile()’s sight and sends the code options over the built-in defaults. Hand it to withMiddleware(...) as it is.

A wrapper hides the middleware, not the result: when this block differs from what reference.conf ships and no hsts() in the route tree read it — wrapped, absent, or HSTS sent through the bundle only — bind() logs a warning naming the block and the address it bound. What it cannot see is a wrapped hsts() beside another one that did read the block.

The requestTimeout() middleware reads its deadline from actor-ts.http.request-timeout:

KeyDefaultPurpose
http.request-timeout.deadline30sHow long a handler may take to answer before the middleware answers 503 for it. On the Hono backend under Bun it also sets the default http.server.idle-timeout, so the 503 is written before the connection is cut (see the http.server section).

This is the handler’s deadline, and deliberately not http.server.request-timeout above: that one bounds how long a peer takes to send a request and never a response, this one starts once the request has arrived. What requestTimeout(...) names in code wins, then this block, then the built-in default, so requestTimeout() with no argument takes its deadline from here:

actor-ts.http.request-timeout {
deadline = 10s
}

The leaf is the kebab-case of the deadlineMs field with the unit suffix dropped, read as a duration. The response sent on timeout, withOnTimeout(...), is a function and code-only. The merged deadline is validated once, when the route tree is compiled inside bind(): one that is not positive, or longer than a timer can hold (2147483647 ms, about 24.9 days), fails bind() with an OptionsError — a runtime would arm such a timer as 1 ms and answer every request 503 at once.

It reaches requestTimeout() the way the HSTS block reaches hsts(), through the hook compile() resolves, and the same warning names it at bind() when it is configured and nothing in the tree read it.

The system’s shared HttpClient — and any newClient(...) that leaves a field unset — reads its bounds from actor-ts.http.client:

KeyDefaultPurpose
http.client.max-response-bytes8MLargest response body buffered before the request is aborted.
http.client.default-timeout30sDeadline for a call that names no timeoutMs of its own.
http.client.redirect"follow"What to do with a 3xx carrying a Location — follow / error / manual.
http.client.max-redirects5Hops a followed chain may take before the call is refused. 0 refuses the first.

These are a floor, not a policy: an integration passes its own bounds to newClient(...), and a single call overrides them with maxResponseBytes / timeoutMs / redirect / maxRedirects. What the block buys is the ability to move the fleet-wide numbers without a code change — an endpoint that turns out to need 60 s, or a deployment on a link where 8 MiB is the wrong ceiling, used to force every caller off the shared client.

Every leaf is the kebab-case of its HttpClientOptions field with any unit suffix dropped — the value carries the unit, so default-timeout = 30s. The camelCase spellings this block used before are rejected at the first HttpExtension access, not at ActorSystem.create, with a ConfigError naming both, rather than ignored: max-response-bytes is a ceiling a deployment lowers deliberately, and quietly restoring the built-in default would be the one failure mode a rename must not have.

Values are validated on read, on the merged settings, so a bad one throws OptionsError naming the field rather than failing later inside a request. max-response-bytes and default-timeout must both be positive here — unlike a request’s timeoutMs, where 0 is the documented way to opt one call out of any deadline. A 0 in this block would disarm every call that named no deadline of its own, which is the state the defaults exist to prevent.

Server-side WebSocket routes (websocket(path, actorRef)) read their defaults from actor-ts.http.websocket:

KeyDefaultPurpose
http.websocket.max-frame-bytes1MLargest inbound frame accepted (bytes).
http.websocket.on-oversize-frame"close"What to do when a frame exceeds the limit — close / drop.
http.websocket.on-invalid-message"close"What to do when a message fails to decode — close / drop / hook.
http.websocket.max-buffered-bytes4MOutbound backpressure threshold (bytes).
http.websocket.on-backpressure"drop"What to do when the buffer is exceeded — drop / close.
http.websocket.max-connections(unlimited)Max concurrent connections per route; a new upgrade beyond it is closed with 1013.
http.websocket.max-pre-attach-frames256Inbound frames held while the connection actor starts.
http.websocket.max-pre-attach-bytes4MBytes held while the connection actor starts; past either cap the socket is closed with 1013.
http.websocket.accept-timeout10sHow long an admitted upgrade waits for its connection actor before the socket is closed and its max-connections slot released. Infinity switches the watchdog off and is code-only, because HOCON has no Infinity literal — withAcceptTimeoutMs(Infinity) and a withConfig overrides object both reach it.
http.websocket.connection-mailbox-capacity(unset)Queued outbound messages each connection actor may hold — the queue connection.tell, sendRaw and close go into — before the overflow policy sheds frames; close() is never shed. Unset, a connection falls through like any other application actor: to the deployment entry matching its path, then to mailbox.default.capacity. A positive integer; 0 is refused rather than read as “off”.
http.websocket.connection-mailbox-overflow(unset)drop-head / drop-new / reject for a full connection mailbox. Needs a capacity from the route or the leaf above — a configured one, global or per path, does not count — and is refused at bind() without one. Unset, it falls through to the matching deployment entry’s mailbox-overflow, then to mailbox.default.overflow.

The same leaf rule applies here: kebab-case, unit suffix dropped, and a retired camelCase spelling is a ConfigError rather than a cap that silently reverted to the default. This block is read, and so checked, at the bind() of a server with a WebSocket route — not when the HttpExtension is first fetched.

KeyDefaultPurpose
reliable-delivery.producer.resend-timeout500msHow long the producer waits for an acknowledgment before retransmitting the same seq. One fixed interval, re-armed unchanged on every miss — there is no backoff.
reliable-delivery.producer.window-size16Flow-control window: at most this many un-acked messages in flight. Further sends queue in memory until an acknowledgment opens a slot.
reliable-delivery.consumer.max-producers1024Most producers the consumer keeps deduplication state for at once. At the cap the least-recently-used entry is evicted. 0 = unbounded.
reliable-delivery.consumer.producer-idle-time-to-live5mHow long a producer’s deduplication entry survives with no delivery from it; the sweep runs on this same interval. 0 turns the sweep off.
reliable-delivery.consumer.max-out-of-order1024Most sequences the consumer retains for one producer above an open gap. At the cap a delivery is refused — no handler call, no acknowledgment — and that producer stalls until the gap closes. Keep it above every producer’s window-size. 0 = unbounded.

Both blocks layer under whatever ReliableDelivery.producer(...) / ReliableDelivery.consumer(...) was passed, so an explicit withWindowSize(…) still wins. They are read there and nowhere else. Neither controller can read configuration in its constructor — Actor.system is a getter over a context the cell injects afterwards — so a controller you construct yourself and hand to system.spawn keeps its built-in defaults and never sees this block.

0 is how all three consumer bounds spell the Infinity their option fields document, because Infinity cannot be written in HOCON at all: the number reader takes a numeric literal and the duration parser refuses a non-finite value. It is the same spelling cluster.max-members and sharding.max-entities already use. What it costs is worth stating plainly. The deduplication map is keyed by a producerId the sender chooses, so 0 on max-producers hands a peer the decision about how much this consumer retains — one entry per distinct id, never released. 0 on max-out-of-order does the same inside one entry: a sender that withholds one sequence and keeps sending the ones after it grows that producer’s set for as long as it keeps going.

max-out-of-order is a floor as well as a bound. A producer has window-size sends in flight when a gap opens, so a cap below the largest window of any producer talking to this consumer stalls that producer on its very first gap, with nothing queued behind it. The shipped 1024 leaves room for any window a caller would plausibly configure.

KeyDefaultPurpose
serialization.read-constraints.max-nesting-depth256Container levels a decoder will descend before refusing the payload. Never raised past the encoder’s own ceiling.
serialization.read-constraints.max-document-bytes0Ceiling on one document before it is parsed — checked in JsonSerializer / CborSerializer, and on the cluster wire against the frame’s length prefix. 0 = no ceiling of our own.
serialization.read-constraints.max-string-length20MCeiling on one CBOR byte string, text string or map key, checked against the length prefix before the bytes are allocated. 0 removes it.

These bound what this node reads, never what it writes. A peer that completes the handshake, or any client whose body reaches a serializer, chooses the bytes; these decide how much work this process will do on them before giving up. Lowering one therefore makes this node stricter than its own encoder — it does not change the wire format.

max-nesting-depth is the one that matters, because until it existed there was nothing at all on the JSON side: JSON.parse is iterative in every runtime actor-ts supports and accepts a million levels without complaint, so the recursion that overflows is the framework’s own tagged-tree walker, reached straight off the cluster wire. It may be lowered freely and cannot be raised past 256: that number is also the encoder’s hard cap, and a node that read deeper than it writes would accept a payload it is unable to produce. Raising it is an OptionsError at startup.

max-document-bytes ships as 0 because every path the framework owns is already bounded in bytes — remote.max-frame-bytes on the cluster wire, the server’s body cap over HTTP. Set it where a serializer is reached some other way (a broker payload, a queue message) and nothing upstream has an opinion, or where the byte bound upstream is looser than the document you are willing to parse. On the cluster wire it is enforced against the frame’s 4-byte length prefix, so the frame is refused before its payload is buffered, let alone parsed; that is the earliest point in the framework at which it can act, and it is earlier than the serializers manage, because they are handed bytes that already exist.

Being bounded in bytes is not the same as being bounded in work, and the gap is worth stating: at the shipped defaults a frame nested past max-nesting-depth is refused only after JSON.parse has materialised it. Measured on Bun 1.4, one 16 MiB frame of balanced [ costs about 1.0 s of CPU and 260 MiB of heap before the depth ceiling reports it — roughly four times what a legitimate frame of the same size costs, and repeatable by any peer that completed the handshake. remote.max-frame-bytes and max-document-bytes are the two knobs that bound it. A pre-parse scan of the raw buffer would close it with neither set, and was measured and not shipped: it costs 18–28 % of every frame decode to remove a fourfold amplification.

max-string-length binds on CBOR only, and its default sits deliberately above remote.max-frame-bytes, so on the cluster wire the frame cap is the effective ceiling and this one never fires. The asymmetry is the point: a CBOR item announces its length, so refusing it costs nothing and prevents the allocation, while by the time the JSON walker sees a string JSON.parse has already materialised it.

Two edges are deliberately outside this block. The persistence PayloadCodec decodes bytes the framework itself wrote, so a tightened ceiling there would turn recoverable history into unreadable history. And the HTTP body edge builds its serializers with no ActorSystem handle to read config through — that seam is issue #967.

KeyDefaultPurpose
management.enable-leave-endpointfalseServe POST /cluster/leave (HTTP endpoints).
management.enable-down-endpointfalseServe POST /cluster/down — operator-initiated force-down of a peer.
management.enable-metrics-endpointfalseServe GET /metrics in Prometheus text format.
management.auth-protect-healthfalseExtend the auth middleware over /health and /ready as well as /cluster/*.
management.liveness-path"health"Single path segment the liveness probe answers on.
management.readiness-path"ready"Single path segment the readiness probe answers on.
management.health-checks.check-timeout1sDeadline for one health check; past it that check reports status: false and its siblings still report normally.

These are the settings managementRoutes(system, cluster, options) layers under its explicit options — the usual three layers, so a value set in code wins, a file fills what the code left unset, and the built-in defaults are the floor. The port and host are not here: they belong to system.http(port, { host }), not to the route tree.

auth and ipAllowlist have no key, and cannot get one. Both are Middleware functions, which HOCON has no way to express, so this block decides which endpoints exist and where the probes answer — never who may reach them. A config file therefore cannot loosen the management server’s access control, which is why the two mutating endpoints are safe to expose as config at all.

The two probe paths are single segments, and a value containing / is refused with an OptionsError when the routes are built. That rule is not cosmetic: path(segment, …) strips surrounding slashes only, so readiness-path = "k8s/ready" would be stored as one segment holding a slash, match no URL, and take the endpoint out of existence with nothing logged. A startup error is the visible version of the same outcome.

check-timeout bounds a single check rather than the whole probe. A probe aggregates every registered check into one response, so without it the slowest check is the response time and a check that never settles is a probe that never answers — which Kubernetes reads as a failure carrying no clue as to which dependency hung. Past the deadline the registry answers for that check with { name: 'unknown', status: false, detail: … }; the name is unknown because the name lives inside the result the check never returned.

KeyDefaultPurpose
metrics.max-series-per-family10000Distinct label tuples one metric family may mint; every tuple past it is folded into a single __overflow__ series (the cardinality cap). Covers the in-process registry and the prom-client bridge alike. 0 disables the cap.
metrics.name-prefix""Prefix the prom-client bridge puts in front of every metric name it registers, e.g. "actor_ts_". The bridge only.

These are read when MetricsExtension builds a registry, under the options of the call that builds it — the usual three layers, so a value set in code wins, a file fills what the code left unset, and the built-in defaults are the floor. enable(options) takes the cap for the in-process registry; enablePromClient(options) takes both leaves for the bridge. The free promClientRegistry(options) reads neither: it takes no ActorSystem, so the bridge it returns, installed with useRegistry, behaves exactly as its options say.

The cap reaches registries nobody enables in code. DevTools switches the registry on with no options while it is attached, and the relay of a worker mesh does the same inside every worker — whose system is built from the main thread’s effective config. So a cap set here holds on every thread, while one passed to the main thread’s own enable(options) stays on the main thread.

name-prefix reaches the bridge and nothing else. The in-process registry has no prefix: the management GET /metrics route renders the stock metrics under the names that page lists.

Two metrics switches stay in the blocks of the code that serves them: management.enable-metrics-endpoint turns the scrape route on, and worker-mesh.metrics-relay-interval paces the relay that brings the workers’ registries into it.

KeyDefaultPurpose
tracing.tracer-name"actor-ts"Name the OpenTelemetry adapter asks getTracer for — the instrumentation scope your tracing backend files every framework span under.
tracing.tracer-version(unset)Version passed to getTracer beside the name. Comment-only in reference.conf: unset passes no version. Quote it — an unquoted 1.0 is a number to HOCON and arrives as "1".
tracing.logger-name"actor-ts"Name the OpenTelemetry logger of the otelLogs slot asks getLogger for — the instrumentation scope your backend files every framework log record under. Not logger.sinks.otlp.scope-name; see below.
tracing.logger-version(unset)Version passed to getLogger beside the name. Comment-only in reference.conf: unset passes no version. Quote it, as tracer-version above.

The two tracer-* leaves are read when TracingExtension.enableOtel(options) builds the tracer, under the options of that call — the usual three layers, so a value set in code wins, a file fills what the code left unset, and the built-in default is the floor. Per field: a name set in code keeps a configured version. The free otelTracer(options) reads neither: it takes no ActorSystem, so the tracer it returns, installed with enable(...), behaves exactly as its options say.

Neither leaf reaches a tracer you built yourself. A pre-built tracer in the options is used as it is. The @opentelemetry/api namespace and a pre-built tracer have no key at all: both are objects a config file cannot hold.

The two logger-* leaves are read when the system builds its logger from the otelLogs slot — ActorSystemOptions.withOtelLogs(options), at ActorSystem.create — under the slot’s options: the same three layers, field by field. The logger’s level is not here: it is the slot’s own level, else logLevel, else logger.level. The free otelLogger(options) reads neither leaf, so a logger built with it and handed over with withLogger behaves exactly as its options say, and a pre-built logger in the slot’s options is used as it is.

logger.sinks.otlp.scope-name is a different knob. It names the records the OTLP HTTP sink sends on its own — a separate route to a collector, one that needs no OpenTelemetry SDK — while tracing.logger-name names the logger of the slot. The two never meet: the slot wins over every sink, so a system that sets it builds no OTLP sink at all.

KeyDefaultPurpose
persistence.max-concurrent-recoveries50Journal replays allowed to run at once, system-wide. 0 is uncapped. sharding.entity-recovery paces entity starts one layer up; this bounds how many of their replays are in flight.
persistence.recovery-timeout30sCeiling on one actor’s whole recovery — snapshot load, journal read, fold, and the highestSeq probe a fully compacted stream needs; for a ReplicatedEventSourcedActor, its snapshot load and journal read. Past it the replay fails with a RecoveryTimeoutError — through onRecoveryFailure on a PersistentActor, as a failed preStart on a ReplicatedEventSourcedActor, which has no such hook. 0 is no deadline.
persistence.snapshot-is-optionalfalseFall back to a full journal replay when the snapshot store cannot answer. Never applies to an actor that set integrity() or encryption() — see below.
persistence.journal-breaker"persistence-journal"Circuit-breaker id the journal is called through; "" disables it. Its numbers live under actor-ts.circuit-breaker.persistence-journal.
persistence.snapshot-breaker"persistence-snapshot"As above, for the snapshot store.
persistence.auto-startonOpen the selected journal, snapshot store and durable-state store in the startup’s persistence-start phase, so a plug-in nothing registered or a store that cannot open fails the startup instead of the first persisted message. off opens them on their first operation. withPersistence({ behavior }) wins over it, and a WorkerMesh worker always runs with it off — see opening the stores at startup.
persistence.journal.plugin"...in-memory"Fully-qualified key to the journal’s config.
persistence.snapshot-store.plugin"...in-memory"Fully-qualified key to the snapshot store’s config.
persistence.durable-state.plugin"...in-memory"Fully-qualified key to the durable-state store’s config.
persistence.snapshot-store.in-memory.keep-n0Snapshots the built-in in-memory store keeps per persistenceId. 0 keeps every one — the opposite polarity from the persistent stores’ 3, because this is the store an unconfigured application gets and a bound here would silently discard snapshots.
persistence.journal.sqlite.path""Database file, or ":memory:" for an in-memory database. Empty is not set, with no default behind it: a selected journal with no path, here or in code, is refused at registration.
persistence.journal.sqlite.events-table"events"Event table. The tags (_tags) and metadata (_meta) tables follow this name.
persistence.journal.sqlite.waloffOpen the database with journal_mode = WAL — concurrent readers during a write.
persistence.journal.sqlite.busy-timeout1sHow long a blocked writer waits for the lock before SQLITE_BUSY; 0 fails fast.
persistence.snapshot-store.sqlite.path""As above: empty is not set, a selected store with no path is refused at registration, and ":memory:" is the explicit in-memory database.
persistence.snapshot-store.sqlite.snapshots-table"snapshots"Snapshot table.
persistence.snapshot-store.sqlite.keep-n3Snapshots kept per persistenceId; 0 disables pruning.
persistence.snapshot-store.sqlite.busy-timeout1sAs above.
persistence.durable-state.sqlite.path""As above, except that a database handed over in code stands in for the path: a selected store with neither is refused at registration.
persistence.durable-state.sqlite.table"durable_state"Durable-state table.
persistence.durable-state.sqlite.auto-create-tablesonRun CREATE TABLE IF NOT EXISTS when the store opens — at startup, unless persistence.auto-start is off. Off when a schema tool owns the DDL.
persistence.durable-state.sqlite.busy-timeout1sAs above.
persistence.snapshot-store.object-storage.backend""Which backend the object-storage plugin builds — filesystem, s3, or empty to leave it to code.
persistence.snapshot-store.object-storage.prefix""Prepended to every object key — e.g. env-prod/.
persistence.snapshot-store.object-storage.keep-n3Snapshots kept per persistenceId; 0 disables pruning.
persistence.snapshot-store.object-storage.max-decompressed-bytes512MDecompression-bomb guard on read. Infinity opts out and is code-only, because HOCON has no Infinity literal — withMaxDecompressedBytes(Infinity) and a withConfig overrides object both reach it.
persistence.snapshot-store.object-storage.compression.algorithm"gzip"At-rest compression — none / gzip / zstd.
persistence.snapshot-store.object-storage.encryption.mode"none"Server-side encryption — none / sse-s3 / sse-kms. client-aes256-gcm is refused here.
persistence.snapshot-store.object-storage.encryption.kms-key-id""KMS key ARN, required when the mode is sse-kms. A key name, never key material.
persistence.snapshot-store.object-storage.s3.bucket""Bucket name. Required when backend = s3.
persistence.snapshot-store.object-storage.s3.region""AWS region; auto for Cloudflare R2. Required when backend = s3.
persistence.snapshot-store.object-storage.s3.endpoint""MinIO / R2 / B2 / Spaces / Wasabi endpoint; empty means AWS S3.
persistence.snapshot-store.object-storage.s3.force-path-styleoffPath-style URLs instead of virtual-host style — required for MinIO.
persistence.snapshot-store.object-storage.filesystem.dir""Root directory, created recursively. Required when backend = filesystem.
persistence.snapshot-store.object-storage.filesystem.lock-timeout5sWait for a per-key write lock before failing.
persistence.snapshot-store.object-storage.filesystem.stale-lock30sLock files older than this are force-removed.

The two breaker leaves are ids, not blocks of numbers. A breaker’s settings live under actor-ts.circuit-breaker.<id>, layered over actor-ts.circuit-breaker.default — that is the one home for them, and publishing max-failures a second time under actor-ts.persistence would be two places to change one thing. What ships by default is the failure count (10 in a row, then 15 s of fast-fail) and no call-timeout, because omitting it is what means “no deadline”. To put a ceiling on a single append — the fix for a backend that accepts the connection and then stalls — name it:

actor-ts.circuit-breaker.persistence-journal.call-timeout = 10s

A JournalConcurrencyError never counts as a breaker failure: it is the ownership verdict of a conditional append, not an outage, and ten unlucky entities losing a race must not fast-fail every healthy one on the node. The same holds for JournalIntegrityError and SnapshotIntegrityError — a durable fact about the stored bytes that waiting cannot change.

snapshot-is-optional deliberately does not cover a snapshot that failed to verify. Stores that check integrity reject a tampered body the same way they report being unreachable, so an actor whose persistenceOptions carry integrity or encryption gets no fallback at all — tolerating the outage would tolerate the tampering, and turn an integrity control into a retry.

The five behaviour leaves cover every PersistentActor, and a ReplicatedEventSourcedActor’s own persist, its recovery and its snapshot saves; its append of an event a peer sent is not behind the journal breaker until #958. DurableStateActor is outside all of this: none of these leaves reaches a durable-state store, whether its DurableStateOptions name one or it uses the system-wide store persistence.durable-state.plugin selects.

The object-storage block configures both stores registerObjectStoragePlugins(persistence) returns: the snapshot store and the durable-state store share one backend, so it is declared once rather than twice. With the block filled in, the plug-in needs no options at all — (persistence) => registerObjectStoragePlugins(persistence) in the plugins slot of ActorSystemOptions.withPersistence. Explicit ObjectStoragePluginOptions still win, field by field, and a field left unset in code falls through to the block instead of shadowing it. Values are validated once, on the merged settings, so backend = s3 without a bucket is refused with an OptionsError naming backend.bucket when the plug-in runs, and the startup fails rather than the first snapshot.

No key material has a path in that block, and that is structural rather than a convention. There is no leaf for S3 credentials, for a client-side master key or for an integrity key, so a config file cannot express one. Omitting S3 credentials falls through to the SDK’s default chain — AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY, an EC2 instance profile, or IAM Roles for Service Accounts. encryption.mode = client-aes256-gcm is refused with an OptionsError rather than quietly ignored, because a deployment that asked for client-side encryption and silently got plaintext is the worse outcome; configure that mode in code with ObjectStoragePluginOptions.withEncryption(…). kms-key-id is fine — an ARN is a name, and the key itself never leaves KMS.

durable-state.plugin is the third axis, and it is new. Durable state used to be the one persistence contract with no registry: every registerXxxPlugins helper built its store eagerly and handed it back, so a DurableStateActor had to be given that instance in code. It is now selected exactly like the journal and the snapshot store, and DurableStateOptions.store is optional — an actor that names no store uses whichever this key selects.

SQLite is registered through the plugins slot with registerSqlitePlugins, and needs no options at all when the three blocks above are filled in:

const systemOptions = ActorSystemOptions.create().withPersistence({
plugins: [(persistence) => registerSqlitePlugins(persistence)], // path, tables, retention … from HOCON
});

Precedence is the usual three layers — explicit RegisterSqlitePluginsOptions outrank the block, the block outranks the built-in defaults, per field, and a field left unset in code falls through instead of shadowing. A path given in code is shared by all three stores as a default, so a leaf that names its own keeps it; a pre-opened database overrides the durable-state leaf’s own and reaches that store only, because the journal and the snapshot store open their own file. There is no leaf for a driver, a database or a serializer — those are live objects, and a config file cannot express one.

A store the configuration selects has to name its database. One whose block and code options leave path unset, or set it empty or to a remote URL, is refused when registerSqlitePlugins runs, so ActorSystem.create throws with an error that names the key; path = ":memory:" is the explicit in-memory database. A store that is registered but not selected is never built, so it needs nothing.

The five relational backends read their own blocks too (#872). Postgres, MariaDB, SQL Server, libSQL and Cloudflare D1 share one journal, one snapshot store and one durable-state store between them, so the table half of every block is the same three or four leaves and only the connection half differs. registerPostgresPlugins(persistence) — and each of its four siblings — therefore needs no options at all when the blocks below are filled in:

const systemOptions = ActorSystemOptions.create().withPersistence({
plugins: [(persistence) => registerPostgresPlugins(persistence)], // url, tables, retention ... from HOCON
});

The connection is repeated under each of the three plugin roots rather than hoisted to a per-backend one, because a plugin id is its config section and the three axes are selected independently — they may legitimately name different databases. A deployment that shares one connection writes it once and substitutes: url = ${actor-ts.persistence.journal.postgres.url}.

Three things deliberately have no leaf. A pre-built pool or client and a serializer are live objects, so a config file cannot express one. poolConfig is the driver’s whole option surface, free-form and unvalidated, so it stays code-only — the long tail. For SQL Server that means a purely config-driven store is reached through url, in the Server=...;Database=... form. An mssql:// url passes the read like any other string and is refused with an OptionsError when the store is built: node-mssql has parsed none since its 8.0, and reads one as a single unknown key with no server behind it.

What an operator does tune on the three SQL drivers has typed leaves instead (#1490): max-pool-size, idle-timeout, connect-timeout and ca-file under every Postgres, MariaDB and SQL Server block, plus MariaDB’s acquire-timeout and SQL Server’s request-timeout. Every one is comment-only — unset leaves the driver’s own default, the only value that keeps tracking it — and reaches the driver under the driver’s own name only when set. Each is read when the store is built. A value of the wrong kind — a word where a number goes, a fraction where a count goes, a duration that does not parse — fails that read, with a ConfigError naming the leaf, or for the duration an error naming only the value. One of the right kind is then checked by the store: a size below 1, a timeout that is not a positive whole number of milliseconds, a timeout the driver could not arm as a timer (above about 24.8 days), and a MariaDB idle-timeout that is not a whole number of seconds — the connector counts it in seconds — are refused with an OptionsError. So is a setting made twice: a leaf beside the same key in poolConfig or in the url (connectionLimit in a MariaDB url, Max Pool Size in a SQL Server connection string) is refused naming both, rather than one quietly winning. ca-file is a path the framework reads when the pool opens, never the certificate itself; it is how a server behind a private CA is reached from configuration, and the only way for MariaDB and SQL Server, whose urls cannot carry a CA. It is refused beside anything that says otherwise about TLS: a url ssl parameter for Postgres, which node-postgres would put in its place; an ssl the MariaDB connector reads as false; an Encrypt or TrustServerCertificate that leaves the CA unused on SQL Server; or a poolConfig that names another CA.

And tags-table is a comment in the reference configuration rather than a key, because its default is derived from events-table (<events-table>_tags): absence is what keeps the two in step. It is read all the same, so an application.conf can still pin it.

The two credentials that do have a leaf — libSQL’s auth-token and D1’s api-token — are strings the operator supplies from somewhere, and the documented route is a substitution (api-token = ${?CLOUDFLARE_API_TOKEN}). Both ship empty, and empty reads as not set, so the placeholder never becomes a bearer token.

A url that switches TLS verification off is refused for Postgres, SQL Server and MongoDB (#1490). Their drivers read a verification switch out of the connection string itself — sslmode=no-verify or ssl=no-verify, and under uselibpqcompat=true also sslmode=prefer, require or verify-ca; TrustServerCertificate set to anything but false, no, 0 or empty; and tlsInsecure, tlsAllowInvalidCertificates or tlsAllowInvalidHostnames set to anything but false — so their readers inspect the leaf and throw a ConfigError naming it and the switch, in any letter case of the key and for a ${?…} substitution alike. Only HOCON is inspected: the same string passed to withUrl(...) is the code’s decision. About the file the refusal is strict, refusing a block’s url even when code supplies its own connection. Plaintext is a different decision and stays allowed (sslmode=disable, Encrypt=false, tls=false), and MariaDB is not inspected at all: its connector reads the url’s ssl as a boolean, and ssl=true verifies. TLS everywhere has the reasoning and the config-only routes to a private CA.

KeyDefaultPurpose
persistence.journal.postgres.url""Connection string. Empty is not set — the store falls through to the connection the register helper was given.
persistence.journal.postgres.events-table"events"Event table. The tags join table is derived as <events-table>_tags.
persistence.journal.postgres.auto-create-tablesonRun CREATE TABLE IF NOT EXISTS when the store opens — at startup, unless persistence.auto-start is off. Off when a schema tool owns the DDL.
persistence.journal.postgres.max-pool-size(unset)Connections the pool holds — pg-pool’s max, which defaults to 10. Comment-only, as are the three below.
persistence.journal.postgres.idle-timeout(unset)How long an idle connection stays open — pg-pool’s idleTimeoutMillis, default 10s.
persistence.journal.postgres.connect-timeout(unset)How long opening a connection may take — pg’s connectionTimeoutMillis; unset, it waits indefinitely.
persistence.journal.postgres.ca-file(unset)PEM file of the CA that signed the server certificate, read when the pool opens and handed to pg as ssl.ca. Refused beside a url ssl parameter.
persistence.snapshot-store.postgres.url""As above.
persistence.snapshot-store.postgres.snapshots-table"snapshots"Snapshot table.
persistence.snapshot-store.postgres.keep-n3Snapshots kept per persistenceId; 0 disables pruning.
persistence.snapshot-store.postgres.auto-create-tablesonAs above.
persistence.snapshot-store.postgres.max-pool-size, idle-timeout, connect-timeout, ca-file(unset)As above.
persistence.durable-state.postgres.url""As above.
persistence.durable-state.postgres.table"durable_state"Durable-state table.
persistence.durable-state.postgres.auto-create-tablesonAs above.
persistence.durable-state.postgres.max-pool-size, idle-timeout, connect-timeout, ca-file(unset)As above.
KeyDefaultPurpose
persistence.journal.mariadb.url""Connection string. Empty is not set — the store falls through to the connection the register helper was given.
persistence.journal.mariadb.events-table"events"Event table. The tags join table is derived as <events-table>_tags.
persistence.journal.mariadb.auto-create-tablesonRun CREATE TABLE IF NOT EXISTS when the store opens — at startup, unless persistence.auto-start is off. Off when a schema tool owns the DDL.
persistence.journal.mariadb.max-pool-size(unset)Connections the pool holds — the connector’s connectionLimit, which defaults to 10. Comment-only, as are the four below.
persistence.journal.mariadb.acquire-timeout(unset)How long a caller waits for a free connection — acquireTimeout, default 10s.
persistence.journal.mariadb.idle-timeout(unset)How long an idle connection stays open — idleTimeout, default 1800s. Whole seconds only: the connector counts in seconds.
persistence.journal.mariadb.connect-timeout(unset)How long opening a connection may take — connectTimeout, default 1s, capped at the acquire timeout.
persistence.journal.mariadb.ca-file(unset)PEM file of the CA that signed the server certificate, read when the pool opens and handed to the connector as ssl.ca. Refused beside a url ssl that switches TLS off.
persistence.snapshot-store.mariadb.url""As above.
persistence.snapshot-store.mariadb.snapshots-table"snapshots"Snapshot table.
persistence.snapshot-store.mariadb.keep-n3Snapshots kept per persistenceId; 0 disables pruning.
persistence.snapshot-store.mariadb.auto-create-tablesonAs above.
persistence.snapshot-store.mariadb.max-pool-size, acquire-timeout, idle-timeout, connect-timeout, ca-file(unset)As above.
persistence.durable-state.mariadb.url""As above.
persistence.durable-state.mariadb.table"durable_state"Durable-state table.
persistence.durable-state.mariadb.auto-create-tablesonAs above.
persistence.durable-state.mariadb.max-pool-size, acquire-timeout, idle-timeout, connect-timeout, ca-file(unset)As above.
KeyDefaultPurpose
persistence.journal.mssql.url""Connection string. Empty is not set — the store falls through to the connection the register helper was given.
persistence.journal.mssql.events-table"events"Event table. The tags join table is derived as <events-table>_tags.
persistence.journal.mssql.auto-create-tablesonRun CREATE TABLE IF NOT EXISTS when the store opens — at startup, unless persistence.auto-start is off. Off when a schema tool owns the DDL.
persistence.journal.mssql.max-pool-size(unset)Connections the pool holds — node-mssql’s pool.max, which defaults to 10. Comment-only, as are the four below.
persistence.journal.mssql.idle-timeout(unset)How long an idle connection stays open — pool.idleTimeoutMillis, default 30s.
persistence.journal.mssql.connect-timeout(unset)How long opening a connection may take — connectionTimeout, default 15s.
persistence.journal.mssql.request-timeout(unset)How long one request may run — requestTimeout, default 15s.
persistence.journal.mssql.ca-file(unset)PEM file of the CA that signed the server certificate, read when the pool opens and handed to tedious to verify against — a connection string has no key for one. Refused beside an Encrypt or TrustServerCertificate in the url that leaves it unused.
persistence.snapshot-store.mssql.url""As above.
persistence.snapshot-store.mssql.snapshots-table"snapshots"Snapshot table.
persistence.snapshot-store.mssql.keep-n3Snapshots kept per persistenceId; 0 disables pruning.
persistence.snapshot-store.mssql.auto-create-tablesonAs above.
persistence.snapshot-store.mssql.max-pool-size, idle-timeout, connect-timeout, request-timeout, ca-file(unset)As above.
persistence.durable-state.mssql.url""As above.
persistence.durable-state.mssql.table"durable_state"Durable-state table.
persistence.durable-state.mssql.auto-create-tablesonAs above.
persistence.durable-state.mssql.max-pool-size, idle-timeout, connect-timeout, request-timeout, ca-file(unset)As above.
KeyDefaultPurpose
persistence.journal.libsql.url""Connection string. Empty is not set — the store falls through to the connection the register helper was given.
persistence.journal.libsql.auth-token""Turso auth token. Empty is not set; prefer ${?TURSO_AUTH_TOKEN}.
persistence.journal.libsql.events-table"events"Event table. The tags join table is derived as <events-table>_tags.
persistence.journal.libsql.auto-create-tablesonRun CREATE TABLE IF NOT EXISTS when the store opens — at startup, unless persistence.auto-start is off. Off when a schema tool owns the DDL.
persistence.snapshot-store.libsql.url""As above.
persistence.snapshot-store.libsql.auth-token""As above.
persistence.snapshot-store.libsql.snapshots-table"snapshots"Snapshot table.
persistence.snapshot-store.libsql.keep-n3Snapshots kept per persistenceId; 0 disables pruning.
persistence.snapshot-store.libsql.auto-create-tablesonAs above.
persistence.durable-state.libsql.url""As above.
persistence.durable-state.libsql.auth-token""As above.
persistence.durable-state.libsql.table"durable_state"Durable-state table.
persistence.durable-state.libsql.auto-create-tablesonAs above.
KeyDefaultPurpose
persistence.journal.cloudflare-d1.account-id""Cloudflare account id. Empty is not set.
persistence.journal.cloudflare-d1.database-id""D1 database id — the UUID, not the database name.
persistence.journal.cloudflare-d1.api-token""API token with D1:Edit. Empty is not set; prefer ${?CLOUDFLARE_API_TOKEN}.
persistence.journal.cloudflare-d1.base-url"https://api.cloudflare.com/client/v4"D1 REST endpoint. Override only for a proxy or a test double.
persistence.journal.cloudflare-d1.timeout30sDeadline on one D1 request. A replay reads an actor’s whole history in one statement, which is one request, so this bounds a whole recovery.
persistence.journal.cloudflare-d1.max-response-bytes64MCeiling on one D1 response body. The whole replay arrives as one response; raise it when a long history stops recovering.
persistence.journal.cloudflare-d1.events-table"events"Event table. The tags join table is derived as <events-table>_tags.
persistence.journal.cloudflare-d1.auto-create-tablesonRun CREATE TABLE IF NOT EXISTS when the store opens — at startup, unless persistence.auto-start is off. Off when a schema tool owns the DDL.
persistence.snapshot-store.cloudflare-d1.account-id""As above.
persistence.snapshot-store.cloudflare-d1.database-id""As above.
persistence.snapshot-store.cloudflare-d1.api-token""As above.
persistence.snapshot-store.cloudflare-d1.base-url"https://api.cloudflare.com/client/v4"As above.
persistence.snapshot-store.cloudflare-d1.timeout30sAs above.
persistence.snapshot-store.cloudflare-d1.max-response-bytes64MAs above.
persistence.snapshot-store.cloudflare-d1.snapshots-table"snapshots"Snapshot table.
persistence.snapshot-store.cloudflare-d1.keep-n3Snapshots kept per persistenceId; 0 disables pruning.
persistence.snapshot-store.cloudflare-d1.auto-create-tablesonAs above.
persistence.durable-state.cloudflare-d1.account-id""As above.
persistence.durable-state.cloudflare-d1.database-id""As above.
persistence.durable-state.cloudflare-d1.api-token""As above.
persistence.durable-state.cloudflare-d1.base-url"https://api.cloudflare.com/client/v4"As above.
persistence.durable-state.cloudflare-d1.timeout30sAs above.
persistence.durable-state.cloudflare-d1.max-response-bytes64MAs above.
persistence.durable-state.cloudflare-d1.table"durable_state"Durable-state table.
persistence.durable-state.cloudflare-d1.auto-create-tablesonAs above.

The three non-relational backends read their own blocks too (#872). They do not share an implementation with each other or with the SQL family, so each block speaks its own backend’s vocabulary — Mongo has collections and creates indexes, DynamoDB has account-global table names and a region rather than a URL, and Cassandra is reached by a seed list and lays out four tables. registerMongoPlugins(persistence), registerDynamoDbPlugins(persistence) and registerCassandraPlugins(persistence) therefore need no options at all once the blocks below are filled in.

Cassandra has no durable-state block, and that is not an omission: the framework ships no Cassandra durable-state store, so that backend has two plugin axes where the other two have three.

KeyDefaultPurpose
persistence.journal.mongodb.url""Connection string — mongodb://… or mongodb+srv://…. Empty is not set.
persistence.journal.mongodb.database-name"actor_ts"Database the collections live in.
persistence.journal.mongodb.events-collection"events"Events collection. Its meta collection is <it>_meta.
persistence.journal.mongodb.auto-create-indexesonCreate the indexes when the store opens — at startup, unless persistence.auto-start is off. The unique index is what refuses a duplicate append, so off means I created them myself.
persistence.journal.mongodb.max-pool-size(unset)Connections the client holds open to one server — the driver’s maxPoolSize, which defaults to 100. Comment-only, as are the four below.
persistence.journal.mongodb.min-pool-size(unset)Connections kept open ahead of use — minPoolSize, default 0. At most max-pool-size.
persistence.journal.mongodb.server-selection-timeout(unset)How long an operation waits for a server it can use — serverSelectionTimeoutMS, default 30s.
persistence.journal.mongodb.connect-timeout(unset)How long opening a connection may take — connectTimeoutMS, default 30s.
persistence.journal.mongodb.ca-file(unset)PEM file of the CA that signed the server certificate, read when the client opens and handed to the driver as ca, with TLS on. Refused beside a url tlsCAFile, and beside a tls or ssl set to false.
persistence.snapshot-store.mongodb.url""As above.
persistence.snapshot-store.mongodb.database-name"actor_ts"As above.
persistence.snapshot-store.mongodb.snapshots-collection"snapshots"Snapshots collection.
persistence.snapshot-store.mongodb.keep-n3Snapshots kept per persistenceId; 0 disables pruning.
persistence.snapshot-store.mongodb.auto-create-indexesonAs above.
persistence.snapshot-store.mongodb.max-pool-size, min-pool-size, server-selection-timeout, connect-timeout, ca-file(unset)As above.
persistence.durable-state.mongodb.url""As above.
persistence.durable-state.mongodb.database-name"actor_ts"As above.
persistence.durable-state.mongodb.collection"durable_state"Durable-state collection.
persistence.durable-state.mongodb.max-pool-size, min-pool-size, server-selection-timeout, connect-timeout, ca-file(unset)As above.

clientOptions has no leaf — the driver’s whole option surface, which stays code-only — and neither does a pre-built client or a serializer. What an operator tunes on the client has the typed leaves above instead (#1490), each comment-only so that unset keeps the driver’s own default, mongodb 6 and 7 alike. The store checks them when it is built, as it checks the SQL ones, and a leaf beside the same option in clientOptions or in the url’s query is refused naming both: the driver reads all three case-insensitively, keeps the object’s value and drops the url’s without a word.

The url is inspected like the relational ones above: tlsInsecure, tlsAllowInvalidCertificates or tlsAllowInvalidHostnames set to anything but false is refused. A private CA goes into the url as tlsCAFile or beside it as ca-file — one or the other, since the driver reads tlsCAFile only when it was handed no CA.

KeyDefaultPurpose
persistence.journal.dynamodb.region""AWS region, e.g. eu-central-1. Empty is not set.
persistence.journal.dynamodb.endpoint""Endpoint override for dynamodb-local or LocalStack; empty means the real service.
persistence.journal.dynamodb.events-table"actor_ts_events"Events table. Prefixed because a DynamoDB table name is account- and region-global.
persistence.journal.dynamodb.billing-mode"pay-per-request"How a table the store creates is billed: pay-per-request (on-demand) or provisioned. AWS’s own spelling is refused.
persistence.journal.dynamodb.provisioned-throughput.read-capacity-units(unset)Deliberately a comment, as is the write half below. The read capacity a provisioned table is created with; refused under pay-per-request.
persistence.journal.dynamodb.provisioned-throughput.write-capacity-units(unset)The write half. Set both or neither: with neither, a provisioned table gets 5 read and 5 write units.
persistence.journal.dynamodb.table-ready-timeout30sHow long a table the store just created may take to become ACTIVE.
persistence.journal.dynamodb.auto-create-tablesonCreateTable when the store opens — at startup, unless persistence.auto-start is off; an existing table is the expected case. Off when the tables are provisioned elsewhere.
persistence.journal.dynamodb.max-attempts(unset)Attempts per request, the first included — the SDK’s maxAttempts. Comment-only, as are the three below: unset leaves the SDK’s own resolution (AWS_MAX_ATTEMPTS, the shared config file, then 3).
persistence.journal.dynamodb.retry-mode(unset)standard or adaptive — the SDK’s retryMode; any other word is refused. Unset: AWS_RETRY_MODE, the shared config file, then standard.
persistence.journal.dynamodb.request-timeout(unset)How long one attempt may take before it fails — the request handler’s requestTimeout, with throwOnRequestTimeout on. Unset: no limit.
persistence.journal.dynamodb.connection-timeout(unset)How long opening the connection may take — the request handler’s connectionTimeout. Unset: no limit.
persistence.snapshot-store.dynamodb.region""As above.
persistence.snapshot-store.dynamodb.endpoint""As above.
persistence.snapshot-store.dynamodb.snapshots-table"actor_ts_snapshots"Snapshots table.
persistence.snapshot-store.dynamodb.keep-n3Snapshots kept per persistenceId; 0 disables pruning.
persistence.snapshot-store.dynamodb.billing-mode"pay-per-request"As above.
persistence.snapshot-store.dynamodb.provisioned-throughput.read-capacity-units(unset)As above.
persistence.snapshot-store.dynamodb.provisioned-throughput.write-capacity-units(unset)As above.
persistence.snapshot-store.dynamodb.table-ready-timeout30sAs above.
persistence.snapshot-store.dynamodb.auto-create-tablesonAs above.
persistence.snapshot-store.dynamodb.max-attempts, retry-mode, request-timeout, connection-timeout(unset)As above.
persistence.durable-state.dynamodb.region""As above.
persistence.durable-state.dynamodb.endpoint""As above.
persistence.durable-state.dynamodb.table"actor_ts_durable_state"Durable-state table.
persistence.durable-state.dynamodb.billing-mode"pay-per-request"As above.
persistence.durable-state.dynamodb.provisioned-throughput.read-capacity-units(unset)As above.
persistence.durable-state.dynamodb.provisioned-throughput.write-capacity-units(unset)As above.
persistence.durable-state.dynamodb.table-ready-timeout30sAs above.
persistence.durable-state.dynamodb.auto-create-tablesonAs above.
persistence.durable-state.dynamodb.max-attempts, retry-mode, request-timeout, connection-timeout(unset)As above.

Credentials have no leaf: omitted, the SDK’s own default chain supplies them. clientConfig has none either — the SDK’s whole option surface, which stays code-only — but what an operator tunes on the client does: the four typed leaves above (#1490), comment-only so that unset keeps the SDK’s own resolution, which a shipped value would overrule. The store checks them when it is built, and a leaf beside what it replaces in clientConfig — maxAttempts, retryMode, a retryStrategy that makes both moot, or a requestHandler — is refused naming both. request-timeout sets throwOnRequestTimeout beside the handler’s requestTimeout, without which the handler only logs that a request ran long. Table provisioning has leaves too (#1490): the billing mode’s values are kebab-case like every HOCON value, and the reader maps them to AWS’s PAY_PER_REQUEST and PROVISIONED. The capacity pair ships as a comment because, published, it would be refused under the default pay-per-request, where AWS ignores capacity; a provisioned table with no pair is created at 5 read and 5 write capacity units, so name the pair when you provision on purpose.

KeyDefaultPurpose
persistence.journal.cassandra.contact-points[]Seed nodes the cluster topology is discovered from. [] is not set — the list shape of the "" idiom.
persistence.journal.cassandra.keyspace""Keyspace every statement names (keyspace.table); the client is never bound to it with USE. Empty is not set; required at the point of use.
persistence.journal.cassandra.local-data-center"datacenter1"Local DC for DCAwareRoundRobinPolicy.
persistence.journal.cassandra.port9042CQL native-transport port.
persistence.journal.cassandra.auto-create-keyspaceoffCREATE KEYSPACE on start, with the replication below — a development convenience.
persistence.journal.cassandra.replication.class"simple-strategy"The keyspace’s replication strategy: simple-strategy or network-topology-strategy. CQL’s own class names are refused. Read only by auto-create-keyspace.
persistence.journal.cassandra.replication.replication-factor1Copies of every row under simple-strategy.
persistence.journal.cassandra.replication.data-centers(unset)Deliberately a comment. Copies per data center under network-topology-strategy, as a list of { name, replication-factor } entries; refused under simple-strategy.
persistence.journal.cassandra.consistency(unset)Deliberately a comment in reference.conf. Unset, the driver picks the CQL level; set the numeric value from types.consistencies (6 = LOCAL_QUORUM) to pin it.
persistence.journal.cassandra.events-table"events"Events table.
persistence.journal.cassandra.metadata-table"metadata"Highest sequence number per persistenceId.
persistence.journal.cassandra.all-ids-table"all_persistence_ids"The lookup behind persistenceIds().
persistence.journal.cassandra.tag-index-table"events_by_tag"Side table, written only when use-tag-index is on.
persistence.journal.cassandra.partition-size500000Rows per partition before rolling over to a new one.
persistence.journal.cassandra.auto-create-tablesonCreate the four tables when the store connects — at startup, unless persistence.auto-start is off.
persistence.journal.cassandra.use-tag-indexoffDual-write an events_by_tag side table so tag queries walk one partition.
persistence.journal.cassandra.lightweight-transactionsonClaim the sequence range with Paxos before writing. Off risks a silently lost append, because a Cassandra INSERT is an upsert.
persistence.journal.cassandra.serial-consistency(unset)Deliberately a comment. Ignored unless the LWT above is on; unset the driver picks cluster-wide SERIAL. 9 is localSerial.
persistence.snapshot-store.cassandra.contact-points[]As above.
persistence.snapshot-store.cassandra.keyspace""As above.
persistence.snapshot-store.cassandra.local-data-center"datacenter1"As above.
persistence.snapshot-store.cassandra.port9042As above.
persistence.snapshot-store.cassandra.auto-create-keyspaceoffAs above.
persistence.snapshot-store.cassandra.replication.class"simple-strategy"As above.
persistence.snapshot-store.cassandra.replication.replication-factor1As above.
persistence.snapshot-store.cassandra.replication.data-centers(unset)As above.
persistence.snapshot-store.cassandra.consistency(unset)As above.
persistence.snapshot-store.cassandra.snapshots-table"snapshots"Snapshots table.
persistence.snapshot-store.cassandra.keep-n3Snapshots kept per persistenceId; 0 disables pruning.
persistence.snapshot-store.cassandra.auto-create-tablesonAs above.

credentials has no leaf at all — it is key material, and key material is never expressible in a config file. replication is not free-form (#1490): it is the typed shape the keyspace DDL is built from, so its leaves are read one by one, and a verbatim object never reaches the DDL. Its data centers are a list rather than a map because a data center’s name is data, not a key — as a key, an unquoted eu.west would nest instead of naming one.

The plugin keys point to another config section that holds that plugin’s settings. actor-ts.persistence.journal.sqlite above is the worked example: it is both the id the journal is registered under and the block that journal reads. See each journal page in Persistence for the per-plugin keys.

KeyDefaultPurpose
circuit-breaker.default.max-failures10Consecutive failures before a breaker opens (circuit breaker).
circuit-breaker.default.reset-timeout15sHow long it stays open before letting a probe through.
circuit-breaker.default.max-reset-timeout60sCeiling the grown window is clamped to. Must be at least reset-timeout — a breaker whose merged settings say otherwise refuses to start.
circuit-breaker.default.backoff-factor1.0Multiplier per consecutive open. 1.0 = the flat window every earlier release had.
circuit-breaker.default.random-factor0.0Jitter fraction in [0, 1] spread over that window. 0.0 = no jitter.
circuit-breaker.default.ignored-error-names[]Error.name values that never count as a failure.
circuit-breaker.default.call-timeout(unset)Deliberately a comment in reference.conf — see below. Unset, there is no per-call deadline.
circuit-breaker.<id>.*(the block above)The same leaves, for the single breaker breaker('<id>') resolves — overrides the default block leaf by leaf.

These are read by the CircuitBreakerExtension, the door that resolves a breaker by id:

import { CircuitBreakerExtensionId } from 'actor-ts';
const payments = system.extension(CircuitBreakerExtensionId).breaker('payment-api');
await payments.call(() => fetch('https://payments.example/charge'));

new CircuitBreaker({ … }) reads none of this and is unchanged — it is the door for a breaker whose settings live in code. Explicit options passed as breaker(id, options) still outrank both blocks, which is what carries the two things HOCON cannot express: the isFailure predicate and the random seam.

default is reserved, and the two readings of it coincide: it is the block every breaker inherits from and the id breaker() resolves with no argument, so a breaker named default reads exactly the block that configures it. That is the reason the defaults sit in a named sub-block rather than at actor-ts.circuit-breaker.* directly — there, ids and leaves would share one namespace, and breaker('random-factor') would go looking for its settings inside a number.

call-timeout is a comment rather than a leaf because omitting callTimeoutMs is what disables the per-call timeout, and 0 is refused by the validator — so “no deadline” is a state only a missing key can express. Writing it works normally; the block simply does not publish a default that would hand every config-resolved breaker a deadline a hand-built one lacks.

backoff-factor and random-factor ship neutral on purpose. 1.0 and 0.0 reproduce the flat, unjittered reopen window exactly, so the block is additive and turning either on is a change a deployment makes deliberately. With both set, the window is reset-timeout × backoff-factor^(consecutive opens − 1), clamped to max-reset-timeout and then spread by ± random-factor; it returns to reset-timeout as soon as a probe succeeds and the breaker closes.

ignored-error-names is checked before isFailure, not after. The list is the operator’s half of the classifier and arrives from a config file, while the predicate is compiled in — if the predicate could overrule the list, the leaf would go inert for exactly the deployments that set it.

These <id> paths take the id your code asks breaker(id) for, so they cannot be enumerated in reference.conf.

KeyDefaultPurpose
projection.recovery-strategy"retry-and-fail"What a projection does when its handler throws — fail, skip, retry-and-fail or retry-and-skip (when the handler throws).
projection.max-retries3Retry budget for the two retry-* strategies — attempts after the first.
projection.retry-backoff1sDelay before the first retry; doubles on each further attempt.
projection.max-retry-backoff60sCeiling on that doubling delay. Must be at least retry-backoff — a projection whose merged settings say otherwise refuses to start.
projection.poll-interval1sHow often a projection asks the journal for new events.
projection.group-after-envelopes20Most events per handleGroup call (grouped handlers). Grouped projections only — a handle projection is delivered one event per call and ignores it.

These are the process-wide defaults for every projection. ProjectionOptions on a single projection outranks them, and they outrank the built-in defaults — the usual three layers. A projection that passes an empty liveOptions still gets poll-interval from here; only a value actually set in code overrides it. group-after-envelopes is checked only where it applies: a size the validator refuses, such as 0, stops the grouped projections and leaves a handle projection alone, which refuses only a groupAfterEnvelopes set in its own code.

Top-level rather than under actor-ts.persistence, because that block holds plugin ids and nothing else, so a tuning leaf inside it would read as the name of a plugin.

KeyDefaultPurpose
backoff-supervisor.min-backoff200msFloor of the respawn delay, and the window after-min-stable measures a child’s stability against (backoff supervisor).
backoff-supervisor.max-backoff10sCeiling the doubling delay clamps to. Must be at least min-backoff — a supervisor whose merged settings say otherwise refuses to start.
backoff-supervisor.random-factor0.2Jitter fraction in [0, 1], so a herd of supervisors does not respawn in lockstep. Inert for a supervisor that supplies its own policy — that policy computes the whole delay.
backoff-supervisor.max-stash-size1000Messages held per supervisor while its child is dead; the oldest becomes a dead letter when the buffer is full.
backoff-supervisor.reset-counter"after-min-stable"When the consecutive-restart counter resets — never, after-min-stable, or a duration naming the stable window explicitly.
backoff-supervisor.forward"stash"What happens to messages arriving during a backoff window — stash buffers them for the next child, drop discards them.
backoff-supervisor.trigger-on"any"Which terminations respawn the child — any, failure (crashes only) or stop (clean stops only).
backoff-supervisor.drain-grace"auto"How long a respawned child has to survive before the stash drains into it, so a child that crashes in preStart does not take the stash with it. auto is one fixed wait of min(50ms, min-backoff), resolved per supervisor against its merged min-backoff; a duration fixes it, and 0 drains at once.
backoff-supervisor.forward-during-gracetrueWhether messages arriving inside that grace go straight to the respawned child (true) or wait in the stash until it has survived the grace (false) — up to one grace of latency after each respawn, in exchange for nothing dead-lettered while a child keeps crashing in preStart.

These are the fleet-wide defaults for every BackoffSupervisor in the process. The options passed to one supervisor outrank them, and they outrank the built-in defaults — the usual three layers, per field. A supervisor built as BackoffSupervisor.factory({ child: Flaky }) takes the whole block; one that names minBackoff in code takes the rest of it.

The merge happens in the supervisor’s preStart, which is the first point where system.config is reachable — so a value a config file puts out of range fails the supervisor’s start rather than the call that built it. The rule is the same one that rejects the value written in code.

child-name is deliberately absent: a child’s name is per-call-site identity, where one fleet-wide value would be actively wrong. It is still settable in code.

KeyDefaultPurpose
cache.in-memory.max-entries10000Max entries before LRU eviction (in-memory cache).
cache.in-memory.cleanup-interval60sInterval of the background sweep for expired entries; 0 disables it.
cache.in-memory.prefix-quotas(unset)Per-prefix caps that split one instance between its consumers; must sum to at most max-entries.
cache.in-memory.time-to-live0Lifetime stamped on a set / mset that names no ttlMs. 0 = no expiry, which is the historical behaviour.
cache.in-memory.time-to-idle0A read pushes such an entry’s expiry out again, never past its time-to-live. 0 = a read extends nothing.
cache.<name>.in-memory.*(the block above)The same leaves, for the single instance cache('<name>') resolves — overrides the global block leaf by leaf, and rejects a retired spelling the same way.
cache.<name>.plugin"...in-memory"Which backend cache('<name>') resolves to.
cache.redis.url""redis://host:port (or rediss://). Mutually exclusive with host / port. "" = unset.
cache.redis.host / .port(unset)Deliberately comments in reference.conf — see below. Unset, ioredis uses its own 127.0.0.1:6379.
cache.redis.db0Logical database. Ignored when url is set; put it in the URL path instead.
cache.redis.key-prefix""Prepended to every key — isolates systems or environments sharing one server.
cache.redis.password""AUTH password. Prefer a substitution: password = ${?REDIS_PASSWORD}.
cache.memcached.servers"localhost:11211"Comma-separated host:port list — a string, not a list, because that is what memjs takes.
cache.memcached.username / .password""SASL credentials. Prefer ${?MEMCACHED_PASSWORD}.
cache.memcached.key-prefix""Applied server-side to every operation.
cache.<name>.redis.* / cache.<name>.memcached.*(the blocks above)The same leaves for one instance, so cache('rate-limit') and cache('idempotency') can hold different databases on one server.

Redis and Memcached caches read their connection settings from actor-ts.cache.redis / actor-ts.cache.memcached, and the framework registers both factories itself — so actor-ts.cache.sessions.plugin = "actor-ts.cache.redis" is all a cache needs to come up on Redis, with no registerCache call in your code. Both drivers are lazy optional peers, so a block nobody resolves costs nothing: ioredis and memjs are imported on the first cache operation, not at startup.

An empty string means unset everywhere in those two blocks. The "" values above are the shape of the key, published so you can see the name and the nesting; the reader drops them rather than handing them on. That is also why host and port are comments rather than leaves: url is mutually exclusive with them, and a shipped host = "localhost" would be set for every deployment and would make every url an OptionsError. Write both on purpose and you still get that error, which is the point.

These <name> paths take the name your code asks cache(name) for, so they cannot be enumerated in reference.conf. Sizing one consumer for its own key space is what the one cache per consumer advice needs.

KeyDefaultPurpose
sharding.number-of-shards64How many shards the entity space is divided into. Every node that starts or proxies a type must agree on it — the coordinator refuses a region that does not, see numShards is a cluster-wide agreement.
sharding.role""Only members carrying this role host shards. "" = unrestricted. It names a role, it does not grant one — see a role names, it does not grant below.
sharding.rebalance-interval2sGap between coordinator-driven rebalance passes.
sharding.hand-off-timeout10sHow long to wait for HandOffComplete before force-reallocating.
sharding.persist-coordinator-stateoffKeep each coordinator’s allocation map in the persistence journal, so a new leader starts from the map the previous one last wrote. The journal must be shared by the cluster; a node-local one on a node expecting remote peers is refused (#1188).
sharding.coordinator-state-load-timeout10sHow long a new leader waits for that map to load before it places shards without it.
sharding.rebalance-absolute-limit0Flat ceiling on shards a rebalance may have in flight. 0 = no absolute ceiling. See bounding rebalance churn below.
sharding.rebalance-relative-limit0.1The same ceiling as a fraction of number-of-shards, so it scales with the entity space — 0.1 of the shipped 64 is 6. 0 = no relative ceiling; 0 for both leaves the rebalance uncapped. Where both are set the lower wins, and a ceiling never floors below one shard.
sharding.acquire-retry-interval5sHow long the coordinator waits before re-acquiring a lease it failed to take. Observable only where the coordinator has a lease — passed in code, or built by use-lease.
sharding.use-leaseoffGive every sharded type’s coordinator a lease built from actor-ts.coordination.lease, so only the holder allocates shards under a partition. Refused when the type starts while coordination.lease.backend = none; a withLease(…) in code wins, and withUseLease(false) opts one type out.
sharding.remember-entitiesfalsePersist the set of active entity IDs.
sharding.passivation-idle5mAuto-passivate an entity after this idle window. 0 = disabled. An entity that keeps state in memory and does not rebuild it in preStart loses that state — see passivation.
sharding.shard-passivation-idle(unset)Auto-passivate a shard after it has stood empty this long. Unset it follows passivation-idle; 0 keeps empty shards resident. Deliberately absent from reference.conf, because a shipped value is what “unset” would have to be distinguishable from.
sharding.max-entities0Entity cap per sharded type on this node; the entity the replacement policy names is passivated on overflow. 0 = no cap. Two started types each get the whole cap — see choosing what a full node gives up below.
sharding.passivation.replacementleast-recently-usedWhich resident entity the cap gives up. Also segmented-least-recently-used and least-frequently-used. Inert while max-entities = 0.
sharding.passivation.segmented-protected-proportion0.8Share of the cap held by the protected segment under segmented-least-recently-used; the rest is probation. Ignored under every other policy.
sharding.passivation.admission-window-proportion0.0Share of the cap held as a probationary window in front of the policy. 0 = no window. Required by admission-filter.
sharding.passivation.admission-filterofffrequency-sketch makes a candidate leaving the window out-rank the entity it would displace. Rejected at sharding.start(...) unless admission-window-proportion > 0.
sharding.passivation.stop-timeout0msHow long an entity may take to act on the stop-message a Passivate handed it before the shard stops it outright. 0 waits forever, which is the shipped behaviour.
sharding.buffer-size100000How many messages one region may hold across all its shards while their homes are unknown or handing off, or while their shard backs off after a failure (shard-failure-backoff below). The same cap bounds, per shard, what a shard holds for its entities backing off after a stop nobody asked for (entity-restart-backoff below). Past the cap the newest message is dropped to dead letters with its sender, so what is already queued keeps the order the caller sent it in. Mind the polarity against max-entities above: here 0 means never buffer — dead-letter immediately, not “no cap”.
sharding.register-retry-interval500msHow often a region re-sends an unacknowledged registration to the coordinator. Everything routed for the type buffers until the coordinator answers, so this is also how long a lost Register stalls it.
sharding.shard-region-query-timeout5sDefault wait for sharding.shards() and sharding.shardRefFor(). An explicit timeoutMs argument still wins over it. Not how long the region remembers a caller it has not answered yet — a query like these, or a cross-node ask — which is a minute, or actor.ask-timeout or this key where either is longer. Raising this key never cuts a query’s answer off; lowering it never cuts off an ask’s.
sharding.entity-recovery.strategyallHow remembered entities come back after a region is handed a shard. all starts every one at once — today’s behaviour, and the reason the default did not move. constant-rate paces them, see pacing a remembered-entity restore below.
sharding.entity-recovery.constant-rate.frequency100msGap between two paced recovery batches. Ignored under strategy = all.
sharding.entity-recovery.constant-rate.number-of-entities5Entities one paced batch starts. A region-wide budget, not a per-shard one — the queue is fed by every shard the region owns, so this is entity starts per window per sharded type on this node; two paced types each get the whole budget. Ignored under strategy = all.
sharding.stale-region-detection.enabledoffMake each region beat to the coordinator and let the coordinator evict one that goes silent. Off by default — eviction is destructive. See detecting a region that went silent below.
sharding.stale-region-detection.heartbeat-interval5sGap between two region → coordinator beats. Per sharded type, not per node. Inert while enabled = off.
sharding.stale-region-detection.stale-after20sSilence after which a region is declared gone and its shards re-homed. Must be greater than heartbeat-interval, and by more than one beat. Inert while enabled = off.
sharding.shard-failure-backoff.min200msFirst wait before a shard that stopped unexpectedly — outside a hand-off, a passivation or a release — is re-created; each death in a row doubles it, up to max. The region keeps the shard meanwhile and buffers its messages. Must be greater than 0. See when shards and entities keep failing.
sharding.shard-failure-backoff.max10sThe ceiling the doubling wait stops at. Must not be below min.
sharding.shard-failure-backoff.random-factor0.2Each wait is spread by up to this fraction either way, so shards that died together do not come back in step. In 0..1; 0 makes every wait exact.
sharding.shard-failure-backoff.reset-after60sA shard that went this long without failing, counted from when it came back, starts again at min when it next dies. A passivation in between is not a failure.
sharding.entity-restart-backoff.min200msFirst wait before a shard re-creates an entity that stopped without being passivated — past its restart budget, after a recovery failure it swallowed, a lost lease or a plain stopSelf; each such stop in a row doubles it, up to max. The shard holds the entity’s messages meanwhile, against buffer-size per shard, and the restarts inside the budget are not delayed. Must be greater than 0. See an entity that keeps stopping.
sharding.entity-restart-backoff.max10sThe ceiling the doubling wait stops at. Must not be below min.
sharding.entity-restart-backoff.random-factor0.2Each wait is spread by up to this fraction either way, so entities that stopped together do not come back in step. In 0..1; 0 makes every wait exact.
sharding.entity-restart-backoff.reset-after60sAn entity that went this long without stopping unasked, counted from when it came back, starts again at min when it next stops. A passivation in between is not a failure.
sharding.healthcheck.names[]Sharded types this node is not ready without. Cluster.join installs one readiness check per name, shard-region:<name>, which fails until this node’s region for the type is registered with the coordinator — never started or stopped, refused over number-of-shards, or not acknowledged yet. Read once per join, not per sharding.start(...); [] gates on nothing. See the built-in checks.

These apply to every sharded type started on the node, healthcheck.names aside. They are read once per sharding.start(...) and layered under whatever that call passes explicitly, so the usual order holds per field:

// actor-ts.sharding.passivation-idle = 2 minutes
const shardingOptions = StartShardingOptions.create<CartCommand>()
.withTypeName('cart')
.withEntityActor(CartEntity)
.withExtractEntityId((command) => command.entityId)
.withNumShards(256);
cluster.sharding.start(shardingOptions);
// numShards 256 (explicit), passivationIdleMs 120_000 (config file)

sharding.role says which role hosts a type. It does not give the node that role. A node’s own roles are a separate setting, assigned in code or through actor-ts.cluster.roles:

// On every node that should host the shards:
const clusterOptions = ClusterOptions.create()
.withHost('10.0.0.7')
.withPort(2551)
.withRoles(['backend']);
# In the config file every node shares:
actor-ts.sharding.role = "backend"

Set only the first half and nothing changes; set only the second and no shard is ever allocated — the coordinator finds no candidate member, every message for the type accumulates in the region’s routing buffer, and the only sign of it is one warning naming the role and the number of regions it excluded. A role that no member carries is the same silent failure a typo in withRole produces, except that from a shared config file it applies to every sharded type on every node at once.

That asymmetry is also why the key exists: which role hosts a type is uniform across a deployment, and which roles a node carries is not.

A configured role reaches sharded daemon processes too, because they are started through the same sharding.start(...). That is intended — a deployment that places its entities on backend nodes usually means its daemons as well — and ShardedDaemonProcessOptions.withRole(...) still wins over it per process.

proxy deliberately has no leaf. It is per-node topology, not a deployment-wide fact: a second start disagreeing about it throws, and a proxy = on everyone shared would leave nothing hosting anything.

Under remember-entities a region that is handed a shard is shipped that shard’s whole registry and, by default, spawns every entity in it at once — for every shard it is given. A node restart or a rebalance therefore opens one journal replay per remembered entity, all in the same tick. constant-rate spreads those starts:

actor-ts.sharding.entity-recovery {
strategy = constant-rate
constant-rate.frequency = 100ms
constant-rate.number-of-entities = 5
}

Two things about that budget are worth stating plainly, because both are easy to read the other way:

  • It is region-wide, per sharded type. Five entities per 100 ms is five for this sharded type on this node, no matter how many shards the node holds — the scope max-entities has. Each started type runs its own region and its own queue, so a node recovering two paced types starts up to ten per window. Read per shard the same numbers would mean 5 × the shard count, which on a 64-shard cluster is not a bound at all — the same conflation max-entities is kept region-wide to avoid.
  • It paces starts, not replays. A replay is asynchronous, so one that outlasts the window still overlaps the next batch. What this key smooths is the arrival rate; how many recoveries may be in flight is persistence.max-concurrent-recoveries, one layer down — the two compose.

Nothing is shed: the backlog drains until every remembered entity is back, and a message routed to an entity still in the queue creates it immediately — only the recovery burst waits. The default stays all because pacing changes when an entity comes back, and how fast a journal can take the replays is a fact about that journal rather than about sharding.

The default allocation strategy places a shard by shardId % candidates.length, so a node joining changes the answer for most shards at once. At the shipped number-of-shards = 64 that is 32 shards on a 1 → 2 node join, 42 on a 2 → 3 join and 46 on a 3 → 4 — each one a shard stopped, every entity under it stopped, then re-allocated, re-created and, if it persists, replayed. Nothing announces it either: the coordinator does not react to a MemberUp, and it rebalances only once the set of up members has held still for its settle window — failure-detector.down-after, or the larger of that and split-brain-resolver.stable-after with a split-brain strategy — so the whole burst arrives on the first periodic tick after that window (see members that are not up).

The two limits bound how many of those may be in flight at once:

actor-ts.sharding {
rebalance-absolute-limit = 0 # 0 = no absolute ceiling
rebalance-relative-limit = 0.1 # fraction of number-of-shards
}

Three things about that bound are worth stating plainly:

  • It counts shards in flight, not shards per tick. A tick fires every rebalance-interval while a hand-off may stand for a whole hand-off-timeout, so a per-tick six would admit roughly thirty at once. What the coordinator budgets each tick is the ceiling minus what is already moving.
  • Only voluntary moves are capped. A region that dies leaves its shards with no owner at all; those are re-homed immediately, ceiling or not. Throttling that path would leave shards unreachable rather than merely slow to settle.
  • Nothing is dropped, and no node is drained first. What the budget leaves behind is proposed again on the next tick until the map is balanced, and the shards that go first are picked round-robin across their current owners — a ceiling that empties one node before touching the next is worse than no ceiling.

Set rebalance-relative-limit = 0 (with the absolute limit already 0) to restore the unbounded behaviour.

Read the scope before reaching for this: it is a backstop for one narrow case, and the case most people mean is already covered without it.

A node that stops gossiping is not this backstop’s case. By default — no split-brain strategy, actor-ts.cluster.failure-detector.auto-down = on — the failure detector removes it after actor-ts.cluster.failure-detector.down-after (5 s); with a split-brain strategy, at that strategy’s verdict, no sooner than split-brain-resolver.stable-after (20 s by default). With failure-detector.auto-down = off it is parked at unreachable, and its shards stay homed there until an operator downs it (Cluster.down) or a strategy decides. Either way the coordinator re-homes the node’s shards from the resulting MemberRemoved, and the backstop below never does: it leaves a parked node’s regions to that decision, because the node may still be running their shards. No new shard is placed on a parked node in the meantime (see members that are not up). A region stopped cleanly tells the coordinator on its way down. What none of these covers is a region that is gone or wedged on a node that is still up and gossiping, where that notification never arrived: it is single-shot, unacknowledged, and a transport failure on the way down is logged and swallowed. Then the shards stay allocated to an actor that does not exist, and nothing self-heals — the candidate set is derived from the registry and checks only that a region’s node is up, never that the region itself is alive.

actor-ts.sharding.stale-region-detection {
enabled = on
heartbeat-interval = 5s
stale-after = 20s
}

Five things worth knowing before turning it on:

  • The switch drives both halves. Off, no region beats and no coordinator sweeps, so the mechanism costs nothing at all. On, every region of every sharded type sends one small frame per heartbeat-interval.
  • An evicted region that is still alive is told, and comes back. The coordinator cannot tell a region that is gone from one whose beats were lost, so an eviction is a decision it can get wrong — and a region that is still alive would otherwise learn nothing, keep its shards and keep serving their entities, leaving one shard with two live homes for as long as the node stayed up. It is therefore sent a notice: one that is really gone or wedged never processes it, and one that was merely silent gives up every shard it holds — the entities stop, so a persistent one flushes — and registers again at once. That region has then beaten to the coordinator zero times, so it is not a sweep candidate again until a beat of its own arrives, which is what stops a permanently muted region cycling every stale-after.
  • The beat is per sharded type, not per node. Ten types on a node is ten frames per interval, on top of the cluster’s own heartbeats.
  • A region that never beats is never swept. That is what makes turning the key on safe mid-deployment: for as long as the leader runs with it on and some regions do not, those regions are simply not armed yet, rather than evicted on a timer and re-registering in a loop.
  • stale-after must exceed heartbeat-interval, and the shipped four intervals is deliberate: at one, a single dropped frame evicts a healthy region and stops every entity under every shard it held. A pair that crosses is rejected at sharding.start(...), against the resolved values, so overriding one cannot silently cross the other’s default.

There is deliberately no check-interval. The sweep rides the rebalance-interval tick, which is already the dial for how often the coordinator looks at the shard map, so the detection latency is stale-after plus at most one tick.

max-entities says how many entities a node keeps; the passivation block says which one leaves when a new one arrives. Every key in it is inert while max-entities = 0, which is the shipped default, so a deployment that sets no cap is unaffected by all of it.

Read the cap’s scope before tuning any of this: it is per sharded type on this node, not node-wide and not per shard. A node running a cart type and a session type with max-entities = 50000 holds up to a hundred thousand entities, fifty thousand of each. Per shard the bound would divide across a set that changes on every rebalance; node-wide it would need a budget shared between regions that know nothing about each other.

The default, least-recently-used, has one blind spot, and it is the reason the block exists. Recency cannot tell touched once, ever from touched constantly until a moment ago, so a pass over a large cold key space — a nightly export, a crawler, a backfill — evicts the working set one entity at a time and leaves the cache full of ids nothing will ask for again:

actor-ts.sharding {
max-entities = 50000
passivation {
replacement = segmented-least-recently-used
segmented-protected-proportion = 0.8
admission-window-proportion = 0.01
admission-filter = frequency-sketch
}
}
  • segmented-least-recently-used splits the cap in two. An entity that has been used once sits on probation; using it again moves it to the protected segment, and eviction takes from probation first. A scan entity is never touched twice, so it can only ever displace another scan entity.
  • admission-window-proportion reserves a small slice of the cap for brand-new arrivals. It is what makes a filter possible at all: a region cannot refuse the entity a message has just arrived for — it is being created to receive that message — so the candidate judged against the incumbent is whatever falls out of the window’s far end instead.
  • admission-filter = frequency-sketch is that judgement. A compact count-min sketch of how often each id has been seen decides which of the two stays, and it remembers ids the node no longer holds — which is exactly the history needed to recognise an entity that used to be hot. It is rejected without a window rather than silently doing nothing.

least-frequently-used is the third policy: fewest accesses loses, with every count halved periodically so the ranking follows recent traffic rather than a lifetime total. It suits a working set that is stable but not recent — a fleet of devices reporting on a slow cycle — where recency says almost nothing.

stop-timeout is unrelated to the choice above, and unrelated to max-entities too: a positive value arms it with or without a cap. When an entity passivates itself with Passivate, the stop-message is a request: the entity decides when to act on it. If it never does, the entity never terminates and its slot is held against max-entities for the lifetime of the node. After stop-timeout the shard stops it outright.

It ships off (0, the unbounded wait), so nothing changes for a deployment that does not name it. That is deliberate rather than cautious: an entity mid-drain — a long flush, a slow final write — is entitled to take as long as the drain takes, and a forced stop there abandons the flush. The operator who knows how long the drain can legitimately run is the one who can pick the bound, so it is opt-in.

A per-type setting therefore belongs in the builder; the config file is for the node-wide baseline you want to move between staging and production without a rebuild. The polymorphic options — the entity actor, the extractors, the allocation strategy, a lease, the stores — have no HOCON form and stay in code.

KeyDefaultPurpose
coordinated-startup.default-phase-timeout30sBudget of every startup phase that names none of its own. A task that outlives it fails the startup, so it is what bounds an open that never answers.
coordinated-startup.phases.<name>.timeout—Per-phase budget, overriding default-phase-timeout for that phase alone.
coordinated-startup.phases.<name>.recover—true makes a failing task in that phase a WARN the startup steps over, instead of a failed startup.
coordinated-startup.phases.<name>.depends-on—Phases that must run first. Added to a seeded phase’s existing edge; required when the name declares a new phase.

The block tunes the startup graph the system runs as the last step of create: how long each phase may take, and whether it recovers. The tasks are code, passed through withCoordinatedStartup. Like the shutdown block below, phases ships no values of its own:

actor-ts.coordinated-startup {
default-phase-timeout = 45s
phases {
persistence-start { timeout = 2m } # a database that is slow to accept a pool
warm-caches { # …and a phase a task passed in code runs in
timeout = 10s
recover = true
depends-on = ["persistence-start"]
}
}
}

A child naming persistence-start or before-system-ready merges into it: fields it leaves out keep what the phase was seeded with. Any other name declares a phase, which a task passed in code may then name, and there depends-on is required — a phase with no edges would run before persistence-start. depends-on names a seeded phase or another child of the block, and on a seeded phase it is added to the edge it already has, so a config file cannot run before-system-ready ahead of persistence-start. A declared phase does not recover unless it says so, like the two seeded ones. An unknown setting under a phase, a declared phase without depends-on, a name that resolves to no phase, a cycle or a zero budget is a ConfigError at ActorSystem.create.

Code wins, setting by setting: withDefaultPhaseTimeoutMs over default-phase-timeout, and a phase withPhases names is that entry’s as a whole — the block’s child for it is not applied, while the children for the other phases still are.

KeyDefaultPurpose
coordinated-shutdown.default-phase-timeout5sDefault per-phase timeout. A phase that overruns it is abandoned so the next one still runs.
coordinated-shutdown.terminate-actor-systemtrueWhether the built-in terminator task tears the actor system down in the final phase.
coordinated-shutdown.exit-processfalseWhether to call process.exit(exit-code) once a run ends. A run that a phase with recover = false halts exits at the halt, in place of the teardown it would otherwise get, and with 1 where exit-code is 0.
coordinated-shutdown.exit-code0Status that exit carries. 0–255; anything else is a ConfigError at startup. A run for a failed startup, a run for a node that could not join (ClusterJoinUnsuccessfulReason: the join give-up, a failed Cluster.bootstrap readiness wait or refusal), and a run that a phase with recover = false halts, exit 1 where this is 0, so none of them reads as a clean stop.
coordinated-shutdown.auto-register-taskstrueWhether framework components register their own teardown — the HTTP unbind, broker closes, the cluster leave, the DevTools detach.
coordinated-shutdown.run-by-process-signalstrueWhether runUntilTerminated() and the cluster bootstrap arm SIGTERM/SIGINT when the caller named no signals.
coordinated-shutdown.run-by-actor-system-terminatefalseWhether a system.terminate() that names no runCoordinatedShutdown runs the pipeline first, with ActorSystemTerminateReason. false keeps it the bare teardown; a call that chooses gets what it chose, either way.
coordinated-shutdown.phases.<name>.timeout—Per-phase budget, overriding default-phase-timeout for that phase alone.
coordinated-shutdown.phases.<name>.recover—false makes a failing task in that phase halt the pipeline instead of being logged and stepped over.
coordinated-shutdown.phases.<name>.depends-on—Phases that must run first. Added to a canonical phase’s existing edge; required when the name declares a new phase.

Setting terminate-actor-system = false removes only the built-in terminator — user tasks registered in ActorSystemTerminate still run. Use it when a host process owns the system’s lifetime and a signal handler must not kill it.

The phases block is the config front-end to the phase DAG, and it ships no values of its own — its children are named after your phases, so there is nothing to publish a default for:

actor-ts.coordinated-shutdown.phases {
service-requests-done { timeout = 30s } # retime one canonical phase
flush-metrics { # …and add one of your own
timeout = 3s
recover = false
depends-on = ["before-actor-system-terminate"]
}
actor-system-terminate { depends-on = ["flush-metrics"] }
}

A child naming one of the twelve canonical phases merges into it: fields it leaves out keep what the phase was seeded with. Any other name declares a phase, and there depends-on is required — a phase with no edges sorts into the first ready batch and would run before before-service-unbind, which is never what adding a phase meant. depends-on on a canonical phase is added to the edge it already has rather than replacing it, so a config file cannot re-parent cluster-leave ahead of service-unbind; the topological sort catches cycles, not a pipeline quietly running in the wrong order. Declaration order in the file does not matter — two phases may name each other and are registered dependency-first. An unresolvable name, a cycle, or an unknown setting under a phase is a ConfigError at startup, not at shutdown.

run-by-process-signals switches the default, not the capability. Naming signals explicitly — runUntilTerminated(['SIGTERM']), or shutdownOnSignals in the bootstrap options — still installs them, because explicit options outrank config. Turning it off is for a host process that owns SIGTERM itself: runUntilTerminated() still waits and still holds the event loop open, it simply arms nothing.

exit-process is for the opposite case: a lingering handle (an open socket, a pooled connection a driver never released) keeps the process alive after the pipeline is done, and from the outside that is indistinguishable from a hang. Off by default, because forcing an exit hides exactly the leaks you would rather find. exit-code is the status it hands over — 0, because a pipeline that ran to the end is the success case; set it where a supervisor should tell a planned drain apart from a crash. A run that halts — a phase with recover = false whose task failed — exits too, and never with 0: with exit-code where that is not 0 and with 1 where it is, as a run for a failed startup does. It exits at the halt, so the teardown the halt would otherwise get — the one a signal’s run or an opted-in terminate() performs — never starts; the halt is logged at error, naming the phase, just before. What that teardown would have flushed is flushed before the exit instead — the dead-letter queue’s writes, then the log sinks, each within logger.close-timeout — so that line reaches a buffering sink too; the same goes for a completed run with terminate-actor-system = false.

KeyDefaultPurpose
sharded-daemon-process.liveness-interval30sPeriod of the safety-net ping that re-wakes every daemon index whether or not a cluster event fired. 0 disables it; the event-driven re-wake on LeaderChanged / MemberRemoved runs either way. See the liveness heartbeat.
sharded-daemon-process.role""Only members carrying this role host daemons. "" is not “unrestricted” here — see an unset daemon role inherits the sharding one below. Like sharding.role it names a role and does not grant one.

A daemon set is a module built on sharding rather than a sharding tunable, which is why these live in their own block: actor-ts.sharding.* configures every sharded type on the node, these two only the daemons. They are read once per ShardedDaemonProcess.init(...) and layered under whatever that call passes explicitly, the usual order per field:

// actor-ts.sharded-daemon-process.liveness-interval = 10s
const daemonOptions = ShardedDaemonProcessOptions.create<Tick>()
.withName('reconciler')
.withNumDaemons(8)
.withActorFor((index) => () => new Reconciler(index));
ShardedDaemonProcess.init(system, cluster, daemonOptions);
// livenessIntervalMs 10_000 (config file) — nothing explicit overrides it

name, numDaemons and the per-index actor have no leaf. They describe one daemon set rather than a deployment, and a factory has no HOCON form at all.

An unset daemon role inherits the sharding one

Section titled “An unset daemon role inherits the sharding one”

sharded-daemon-process.role left at "" means no daemon-specific opinion, not unrestricted. The daemon set is started as an ordinary sharded type, so with nothing set here it picks up actor-ts.sharding.role exactly like every other type:

actor-ts.sharding.role = "backend" # every sharded type
# sharded-daemon-process.role left at "" # daemons follow along

Naming a role here narrows only the daemons, and leaves the rest of the sharded types to the global key:

actor-ts.sharding.role = "backend" # entities on the backend nodes
actor-ts.sharded-daemon-process.role = "batch" # daemons on the batch nodes

The same caveat as sharding.role applies, and it bites harder here because nothing sends a daemon a first message: a role that no up member carries allocates nothing, so the daemons simply never start. The coordinator logs one line naming the role when a region did register and the role filtered it out.

KeyDefaultPurpose
devtools.host"127.0.0.1"Interface attach binds. Anything routable is refused unless something gates it — see below.
devtools.port9333Port to bind; 0 lets the operating system pick one, and the returned binding reports which.
devtools.allow-remotefalseAcknowledge an ungated bind on a routable interface.
devtools.serve-uitruefalse leaves the tap without the bundled UI.
devtools.allowed-origins[]Extra origins allowed to open the tap’s WebSocket. Same-origin is always accepted; this only widens it.
devtools.panels.actorstrueActor tree, mailbox depths and cell states.
devtools.panels.clustertrueCluster topology, shard maps, membership timeline.
devtools.panels.tracingtrueSpan flame graph and waterfall — its Payload column carries every actor message that passed while DevTools was attached, serialised.
devtools.panels.explaintruePer-actor explain plan.
devtools.panels.time-traveltrueJournal browsing and state reconstruction — the panel that shows raw persisted events.
devtools.panels.profilertrueActor profiler.
devtools.panels.dead-letterstrueUndelivered messages, payloads included.
devtools.panels.event-streamtrueLive tail of the event bus and the cluster PubSub topics, payloads included.
devtools.panels.configtrueResolved configuration with the source of each key (values whose key names a secret are redacted).
devtools.panels.sendtrueThe send-message view. The capability behind it is a separate, code-only switch.
devtools.mailbox-sample-interval1sHow often the actor tree, mailbox depths and cell states are resampled.
devtools.mailbox-sample-limit50How many mailboxes one sample carries.
devtools.stats-interval1sHow often the dashboard figures are sampled.
devtools.span-buffer-capacity10000Ceiling on retained spans, in messages.
devtools.span-flush-interval250msHow often buffered spans are flushed to the panel.
devtools.capture-payloadstruefalse leaves the tracing panel running — spans, timings, flame graph — and empties only its Payload column, where panels.tracing = false takes the whole panel. A capture the application set for itself is untouched either way.
devtools.event-buffer-capacity500Events the bus tail buffers between flushes; past it the oldest are dropped and the panel is told how many.
devtools.event-flush-interval250msHow often buffered events are flushed to the panel.
devtools.replay-auto-capturetrueBorrow a fold from a running PersistentActor to reconstruct state.

This block does not start DevTools. Nothing in ActorSystem constructs the extension — DevTools.attach(system) is always a code call — so these keys change how an attachment behaves, never whether one happens. There is deliberately no enabled key: reading one would mean importing the DevTools subsystem, embedded UI bundle and all, into every system that never opens it.

A configured host faces the same rule a code-set one does. Options are validated once, on the merged settings, so devtools.host = "0.0.0.0" throws an OptionsError naming host exactly as .withHost('0.0.0.0') in code does. auth and ipAllowlist are middleware and have no HOCON form, which is what makes allow-remote the only answer a file can give to that rule.

Seven fields have no key. auth, ipAllowlist, backend, cluster and replayFolds are functions and live objects HOCON cannot express, and uiDevelopmentRoot is a panel-development escape hatch whose own documentation says never to set it in an application. The last two are a decision rather than an impossibility: allow-ungated-mount states a fact about the code that binds mount()’s routes rather than about a deployment, and allow-message-sending is the one DevTools capability that writes into the running system from a browser. Both stay beside the call they qualify.

A panels object passed in code overrides the configured switches one switch at a time, not wholesale: .withPanels({ timeTravel: false }) on top of a file that says panels { send = false } leaves send off. That is the usual precedence applied one level deeper — otherwise naming one panel in code would switch every panel an operator disabled back on.

actor-ts.offload-pool (pure functions on worker threads)

Section titled “actor-ts.offload-pool (pure functions on worker threads)”
KeyDefaultPurpose
offload-pool.size"auto"Workers at most — "auto" is the available parallelism minus the main thread. Spawned as tasks need them.
offload-pool.min-size0Workers kept alive through idleness.
offload-pool.max-queue10000Tasks waiting for a worker before overflow decides what happens to the next one.
offload-pool.overflow"reject"reject fails the run with OffloadQueueFullError; wait keeps it pending until a slot frees.
offload-pool.idle-timeout60sA worker beyond min-size with nothing to do is retired after this.
offload-pool.task-timeout0s0 = no deadline unless run() names one. A deadline terminates the worker.
offload-pool.max-restarts10Worker terminations — crash or deadline — the pool replaces inside restart-window; -1 = forever. Past the budget every run fails.
offload-pool.restart-window60sThe window the restart budget counts over.
offload-pool.warm-upoffSpawn every worker at start instead of on the first task that needs it.

The task — a named export of a module — and the worker bootstrap are code, never keys, for the reason worker-cluster.bootstrap has none. See Blocking and CPU-bound work.

actor-ts.parallelism (actors on worker threads from config alone)

Section titled “actor-ts.parallelism (actors on worker threads from config alone)”
KeyDefaultPurpose
parallelism.workers00 is off — the single-threaded system, bit for bit. A number or "auto" (available parallelism minus the main thread) starts a worker mesh in the background and turns system.spawn into a placement decision.
parallelism.offload["/user/*"]Path patterns of the top-level actors that move to a worker. * is one segment, ** one or more. A pattern that could reach /system is refused.
parallelism.placement"consistent-hash"Which worker an actor lands on: a hash of its name, or "round-robin".
parallelism.leader"main""worker" moves the cluster leader — and the shard coordinator — onto a worker by giving the workers a hostname that sorts before main.
parallelism.spawn-timeout10sHow long a spawn waits for its worker’s acknowledgment before the ref fails.
parallelism.buffer-size100000Messages held across every spawn still awaiting its worker; past it, dead letters.

The actor module — the file exporting the classes a worker may spawn — is code, never a key: by convention actors.js next to the entry module, otherwise ParallelismOptions.withModule(...). The threads’ hostnames, ports, roles and restart pacing are the worker-mesh.* and worker-cluster.* keys below. See Parallelism.

actor-ts.worker-cluster (multi-runtime workers)

Section titled “actor-ts.worker-cluster (multi-runtime workers)”
KeyDefaultPurpose
worker-cluster.workers"auto"Number of workers — "auto" is the machine’s available parallelism (os.availableParallelism(), which respects a container’s CPU quota; navigator.hardwareConcurrency as the fallback).
worker-cluster.system-name"worker-cluster"ActorSystem name each worker hosts.
worker-cluster.hostname"worker"Host component of each worker’s NodeAddress.
worker-cluster.base-port1Port of the first worker; each subsequent slot increments.
worker-cluster.ready-timeout10sPer-worker hello/init/ready handshake deadline.
worker-cluster.restart-policy"on-failure"always / on-failure / never.
worker-cluster.restart-min-backoff200msDelay before the first respawn of a crashed slot.
worker-cluster.restart-max-backoff10sCeiling for the respawn delay, which doubles per attempt.
worker-cluster.restart-random-factor0.2± jitter fraction on each respawn delay, in [0, 1].
worker-cluster.max-restarts10Restarts granted per slot inside the window before it is retired; -1 restarts forever.
worker-cluster.restart-window60sSliding window the restart budget counts over; 0 never resets the tally.

The four duration keys drop the Ms suffix their options-object fields carry (ready-timeout sets readyTimeoutMs) and take a HOCON duration literal, the same way logger.close-timeout feeds closeTimeoutMs. restart-random-factor is a plain fraction, not a duration.

Four fields have no key on purpose: initData is per-call identity, backend and onWorkerPermanentlyDown are live objects a config file cannot express, and bootstrap names a module the runtime will execute — ACTOR_TS_CONFIG and a dropped-in application.conf are a wider surface than the call site, so it stays a code-only field.

actor-ts.worker-mesh (the main thread as a mesh member)

Section titled “actor-ts.worker-mesh (the main thread as a mesh member)”
KeyDefaultPurpose
worker-mesh.workers"auto"Worker count — "auto" is the available parallelism minus one, because the main thread is a working member; at least 1.
worker-mesh.main-hostname"main"Host component of the main thread’s address. Sorts before the workers’ by default, so main leads and hosts the shard coordinator.
worker-mesh.main-port1Port component of the main thread’s address — synthetic, nothing binds it.
worker-mesh.worker-hostname"worker"Host component of every worker’s address. One that sorts before main-hostname moves the leader onto a worker.
worker-mesh.base-port2Port of the first worker; each slot increments.
worker-mesh.main-roles[]Cluster roles the main thread joins with.
worker-mesh.worker-roles[]Cluster roles every worker joins with — what role-restricted singletons, shards and routers select on.
worker-mesh.metrics-relay-interval10sHow often the main thread pulls every worker’s metrics registry into its own /metrics. While the relay runs, every series carries thread="main" or thread="worker-<slot>"; a worker’s figures are at most one interval old. 0 switches the relay off and exports the main thread alone — see the scope of a scrape.

The mesh’s workers are a worker cluster, so the ready timeout and the restart pacing are the worker-cluster.* keys above. The actor module (withModule) and the bootstrap have no key, for the reason bootstrap has none.

Validation runs on the merged settings, so every one of these is rejected with an OptionsError when it comes from a file exactly as it would from code: an empty system-name or hostname, a base-port outside [1, 65535], a restart-random-factor outside [0, 1], a negative backoff or window, a max-restarts below -1, and a restart-max-backoff under restart-min-backoff.

These fill in WorkerCluster.spawn(options) for fields it leaves unset. spawn is a static with no ActorSystem in scope, so it loads the config chain itself — the same one ActorSystem.create uses, honouring ACTOR_TS_CONFIG and ./application.conf. An unknown restart-policy is rejected with an OptionsError instead of silently meaning “never”.

Each broker actor reads from its own subtree. See the per-protocol pages for each protocol’s own keys:

SubtreePage
io.broker.kafkaKafka
io.broker.mqttMQTT
io.broker.amqpAMQP
io.broker.natsNATS
io.broker.jetstreamNATS JetStream
io.broker.jetstream-key-valueJetStream KV + Object Store
io.broker.jetstream-object-storeJetStream KV + Object Store
io.broker.redis-streamsRedis Streams
io.broker.grpc.{client,server}gRPC
io.broker.websocketWebSocket client
io.broker.sseSSE
io.broker.tcpTCP
io.broker.tcp-serverTCP
io.broker.udpUDP
io.broker.email-bridgeEmail bridge

Every one of these subtrees but grpc.server also takes the leaves BrokerActor reads for all of them: reconnect (initial-delay, max-delay, factor, max-attempts, random-factor), circuit-breaker (a breaker id, whose numbers live under actor-ts.circuit-breaker.<id> — see Circuit breaker) and outbound-buffer. The gRPC server is a plain actor, not a BrokerActor, and reads none of them, so a reconnect block under it configures nothing. So actor-ts.io.broker.kafka.outbound-buffer = 0 makes the Kafka actor drop what it is sent while disconnected rather than buffer it. They are described once, on the BrokerActor base page, and their old camelCase spellings are refused when the broker actor starts.

Not every field of those types has a key. An ActorRef (target, bindings, subscriptions) names a live actor in this process, a codec or a handler is a function, and TLS material is a private key — none of the three has a config-file spelling, and each says so in its own JSDoc rather than being silently absent.

gossip-interval = 1s # 1000 ms
unreachable-after = 2.5s # 2500 ms
down-after = 5000ms # explicit ms
gc-cadence = 10m # minutes
ttl = 24h # hours

Recognized units, case-insensitive, with or without a space before them:

AmountSpellings
nanosecondsns nano nanos nanosecond nanoseconds
microsecondsus μs micro micros microsecond microseconds
millisecondsms milli millis millisecond milliseconds
secondss sec secs second seconds
minutesm min mins minute minutes
hoursh hr hrs hour hours
daysd day days

A bare number is milliseconds. A leading sign and a fraction are both accepted — -500ms and 1.5s are valid. All three spellings of the micro sign reach the same unit, so text copied from elsewhere parses: μs (U+03BC, what the table is keyed on), µs (U+00B5, what a keyboard produces) and Μs (U+039C).

Two things are refused at parse time rather than quietly becoming a number nobody can use:

  • An unrecognized unit — Unknown duration unit "..." in .... The lookup reads the unit table’s own keys only, the same way reads see own keys only guards the key path, so constructor is refused like any other unknown unit instead of resolving through the prototype chain.
  • Anything that is not a finite number of milliseconds — Invalid duration: .... That covers a literal long enough to overflow a double, and any spelling the pattern does not match, exponent notation (1e3) included.
max-frame-bytes = 16M # 16 777 216 bytes — binary
upload-limit = 16MB # 16 000 000 bytes — decimal
buffer = 64K
heap = 2G

Recognized units, case-insensitive, with or without a space before them:

AmountBinary (1024)Decimal (1000)
bytesB byte bytes—
kiloK KiB kibibyte kibibytesKB kilobyte kilobytes
megaM MiB mebibyte mebibytesMB megabyte megabytes
gigaG GiB gibibyte gibibytesGB gigabyte gigabytes
teraT TiB tebibyte tebibytesTB terabyte terabytes
petaP PiB pebibyte pebibytesPB petabyte petabytes

The single letter is binary, as HOCON specifies, and so is the iB form; only the bare B suffix is decimal. The two diverge as they scale — 16MB is 4.63 % smaller than 16M, and at T the decimal value is 9.05 % smaller — so a cap written in the unintended one is a cap in the wrong place.

Unlike a duration, a size takes no sign — -1K is Invalid size — and it has to come to a whole number of bytes. A fraction with a unit is fine when it does, so 1.5K is 1536, and refused when it does not: 1.1K is 1126.4 bytes, and fails as Invalid size: 1.1K is not a whole number of bytes. A bare number has to be whole itself, whether it is written as a string or as a number: "1.5" is Invalid size, and 1.5 is refused naming the key it is set at, as Config at "..." is not a whole number of bytes (got 1.5).

The same two refusals apply, with the messages spelled for sizes: Unknown size unit "..." in ... for a unit that is not in the table — constructor included, for the reason above — and Invalid size: ... for anything that does not come out a finite, whole byte count.

port = ${?ACTOR_TS_PORT} # use env if set, else fall through
log-level = ${?LOG_LEVEL} # same
api-key = ${API_KEY} # required — error if env is unset
fallback-port = 2552 # the default …
fallback-port = ${?ENV_PORT} # … replaced only when ENV_PORT is set

Use ${?ENV} for optional, ${ENV} for required.

A variable that is set but empty counts as not set — PORT= in a shell, environment: [PORT] in a compose file and an empty line of an env file all mean “unset”. ${?PORT} then resolves to nothing and the default shows through, and ${PORT} fails with an error saying the variable is set but empty. To set a key to an empty string, write "" in the file.

There is no default-if-unset form. Everything between the braces is the path, so ${ENV_PORT:-2552} is looked up as a key named ENV_PORT:-2552 and fails as an unresolved substitution, and ${?ENV_PORT:-2552} is optional and silently resolves to nothing. Declare the default first and the optional override after it, as the last two lines do: an optional substitution that resolves to nothing leaves the earlier value in place, and a later plain assignment replaces it as usual.

The same holds across layers. With the default in reference.conf or in a file merged underneath, an unset ${?ENV} in application.conf removes the key from that layer and the one below shows through, which is what the first line above relies on. A key reference.conf carries only as a comment — remote.tcp.host and port, the advertised-* pair, discovery.config.seeds and others — has no layer below it, so an unset ${?ENV} leaves it unset and the reader’s own fallback applies.

A substitution may name a key whose value is itself a substitution. The chain resolves whatever order its lines come in, and a key the file defines wins over the environment at every link, so api.url = ${db.url} with db.url = ${db.host} reads the file’s host even when a DB_URL variable is set. A chain that leads back to where it started is refused as a Substitution cycle: a -> b -> a, the optional form included. A key that names itself — pod.ip = ${?pod.ip} — is no cycle: it reads the environment and then the value it replaced.

host = # nothing after it — no assignment, host keeps its value
host = ${?DB_HOST} # DB_HOST unset or empty — host keeps its value
host = ${DB_HOST} # DB_HOST unset or empty — the start fails
host = "" # an explicitly empty string
roles = [] # an explicitly empty list

An assignment with nothing after its = or : is no assignment: the key keeps what an earlier line of the same file gave it, and across files the layer below shows through. That holds before a comma, before the closing }, before a comment and at the end of the file. To set a key to empty, write "" or [].

A value may still go on the line after its key, as JSON lays it out ("timeout": then 10s), as long as that line does not itself start a field: a line that reads name = …, name: …, name { … or include "…" is the next field, and the assignment above it has no value. So an unquoted value that looks like a field — localhost:2552 — belongs on the same line as its key.

url = "redis://:"${REDIS_PASSWORD}"@cache:6379" # one string
address = ${HOST}":"${PORT} # "db:5432"
name = app-${STAGE} # "app-prod"
seeds = [ ${?SEED_HOST}":"${?SEED_PORT} ] # one element

Quoted strings, substitutions and unquoted text written next to each other on one line make one string. The spaces between the pieces are kept, so ${A} ${B} is the two values with a space between them, and a field that follows after a space still starts a new field (a = "x" b = 1). A single piece keeps its type: port = ${PORT} is a number when PORT holds one.

Inside a string, a variable joins in as the text it holds. On its own, ${X} reads a variable as JSON first, so PORT=2552 gives a number and FLAGS=[1,2] a list; inside a string that would turn a password of digits into a number in exponent notation, so it does not. A key of the file joins in as HOCON writes it — 30, true — and a key that holds an object or a list cannot be joined into a string.

An unset ${?X} inside a string adds nothing. A string made of optional substitutions only, none of them set, is no value at all, so the earlier value or the layer below shows through — as for a single ${?X}.

${ inside quotes is text, not a substitution: "${X}" is the five characters it shows. And because // starts a comment, a URL goes in quotes — url = http://host is refused, where it used to read as http:.

Not supported, and refused with an error that says so: joining objects or lists ({ a = 1 } { b = 2 }, [1] [2], ${base} { … }), +=, and triple-quoted strings (#537).

include "shared-cluster.conf" # error: `include` is not supported

A config source cannot name another file or URL to pull in. That is a decision, not a gap: resolving an include would let whoever writes the config choose which paths the process reads, relative to a root the parser has no way to know. Merging in code leaves that choice with the caller.

import { Config } from 'actor-ts';
const shared = Config.parseFile('shared-cluster.conf');
const application = Config.parseFile('application.conf');
const config = shared.merge(application);

merge layers its argument on top, so the local file wins — the same order the include above was reaching for. Pasting the shared content into one file works too.

One caveat: substitutions are resolved when each file is parsed, not once over the merged tree. A ${my.port} in shared-cluster.conf whose my.port only application.conf defines fails at the first parseFile with Unresolved substitution — where a real include would have produced one document and resolved it. A value the base file refers to has to live in the base file or in the environment. Shared defaults are what the project reference.conf is for: Config.load resolves it before application.conf, and application.conf may refer to its keys.

The parser says all of this when it meets an include, quoting the line and the target, so a config ported from Akka or Pekko fails with an answer rather than a puzzle.

Three keys are refused anywhere in a config source — as a key, as any segment of a path expression, and inside a substitution:

__proto__.anything = 1 # error: refused
constructor.x = 1 # error: refused
prototype = 1 # error: refused
value = ${__proto__} # error: refused

A key path is expanded onto a plain object, and assigning __proto__ writes through to the object prototype rather than creating a normal key — so allowing it would let a config file change the behaviour of every object in the process. The parser rejects these with the usual line and column instead.

The check is exact-match, so keys that merely resemble them are fine: _proto_, constructorName and prototypes all work normally.

Refusing three names guards the write side. The read side is guarded the other way round — positively — because Object.prototype has a dozen more members and a list could never keep up with them:

name = ${toString} # error: unresolved substitution — not a native function
port = ${?valueOf} # optional: falls through to the environment, then away

Every lookup — a substitution, hasPath, and each typed getter — reads own keys only, in the config tree and in the environment alike. A name that happens to match an inherited member therefore misses instead of resolving to whatever lives on the prototype, and hasPath('toString') is false on any config that does not declare a toString key itself. Declaring one is still allowed and still works: an own key shadows the inherited member, so toString = "mine" reads back as "mine".

const actorSystemOptions = ActorSystemOptions.create().withConfig({
'actor-ts': { cluster: { 'gossip-interval': '500ms' } },
});
const system = ActorSystem.create(
'my-app',
actorSystemOptions,
);
// Inside an actor / extension:
const config = system.config;
const interval = config.getDuration('actor-ts.cluster.gossip-interval');
// → 500 (in ms)

The object nests the way the HOCON blocks do. Its keys are taken literally, so a dotted key such as 'actor-ts.cluster.gossip-interval' is a single key with dots in its name, not a path to the setting.

The Config interface has typed getters: getString, getNumber, getBoolean, getDuration, getBytes, getStringList, etc. Missing keys throw unless you check first with hasPath.

1. REFERENCE_CONF ← bundled defaults
2. the project's reference.conf — the first of these that is set:
`referenceConfigFile` setting › ACTOR_TS_REFERENCE_CONFIG env var › ./reference.conf (CWD)
3. that file's profiles.<profile> block ← when a profile is active
4. one application file — the first of these that is set:
`configFile` setting › ACTOR_TS_CONFIG env var › ./application.conf (CWD)
5. that file's profiles.<profile> block ← when a profile is active
6. one secrets file — the first of these that is set:
`secretsFile` setting › ACTOR_TS_SECRETS_CONF env var › ./secrets.conf (CWD)
7. that file's profiles.<profile> block ← when a profile is active
8. constructor `config: { ... }` ← code-level override
9. constructor field overrides ← explicit fields beat config
(logLevel, dispatcher, scheduler, …)
beside them, not a layer — a .env file: `environmentFile` setting › ACTOR_TS_ENV_FILE › ./.env (CWD)

Each layer overlays on top of the previous, key by key. Layer 9 (constructor fields) always wins for the fields it covers; everything else flows through the HOCON merge. The profile is withProfile(name), then the ACTOR_TS_PROFILE environment variable, then none — see Profiles. Layers 2, 4 and 6 are optional files: for each, the first of its candidates that is set decides, a path with no file behind it is an empty layer, and false for a path option reads no such file at all. The settings, on ActorSystemOptions, are withReferenceConfigFile, withConfigFile and withSecretsFile, and withEnvironmentFile for the .env; Config.load callers pass referenceConfPath, appConfPath, secretsConfPath and environmentFilePath instead — see The project reference.conf and Secrets file.

A file’s substitutions read its own keys, then the layers already resolved beneath it, then the real environment, then the variables of the .env file. So application.conf may build on a key the project reference.conf sets, while a lower file never sees a higher one — there is no late binding.

Each of layers 2, 4 and 6 is a single file. The option, the variable and the CWD lookup are three ways of naming it, tried in that order, and the first one that is set decides — an option or a variable that points at a file which does not exist loads nothing, rather than moving on to the next candidate (issue #996 is about saying so at startup). A variable that is set but empty counts as not set. The variables hold a path, never inline HOCON; a value that is not the path of an existing file is treated the same way. To layer further files, compose them in code as Includes are not supported shows.

# reference.conf — the project's defaults, committed with the code
my-app {
pool-size = 4
db.host = "localhost"
db.url = "postgres://"${my-app.db.host}"/app"
}

The bundled reference.conf holds the framework’s defaults; a project keeps its own in a reference.conf of its own, next to the code, and lets application.conf override single keys of it per deployment. It may set framework keys too — a project-wide actor-ts.dispatcher, say — and carries profiles like the other files. It is read from the working directory unless referenceConfPath, withReferenceConfigFile or ACTOR_TS_REFERENCE_CONFIG names another file.

# .env — git-ignored, beside the application
DB_PASSWORD=s3cret
REDIS_URL="redis://:s3cret@cache:6379"

A .env file supplies variables to the substitutions of every file the loader reads — ${DB_PASSWORD} in application.conf or in the secrets file. It is read from the working directory unless environmentFilePath, withEnvironmentFile or the real ACTOR_TS_ENV_FILE names another one, and false reads none. The real environment always wins over it, an empty value in it counts as unset, and it never writes process.env, so child processes do not inherit it. It may itself name the other files and the profile (ACTOR_TS_CONFIG=…, ACTOR_TS_PROFILE=…), as the real environment can.

The grammar is Node’s --env-file one: KEY=value, an optional export, quoted values in ', " or ` that may span lines (a PEM key fits), \n read as a line break inside double quotes only, and # starting a comment — a value with a # in it goes in quotes. $VAR is kept as written, never expanded. A directory called .env — a Python virtual environment often is one — is no file.

Layer 1 is reference.conf, but not every setting has a key there — and even those that do need a value in code for the case where nothing is configured. That value has a fixed home, so you can always find what a setting falls back to:

  • Options defaults sit next to the field they back, in the matching XOptions.ts. DEFAULT_MAX_ENTRIES is in InMemoryCacheOptions.ts, DEFAULT_NUM_SHARDS in ShardingOptions.ts.
  • Everything else — caps, bounds and timeouts with no option behind them — is in a Constants.ts: src/<subsystem>/Constants.ts for one subsystem, src/util/Constants.ts for values several share.

So a reference.conf leaf and its code-level fallback are always exactly two files, and the second one is named after the first.

One application.conf can carry several environments. A root profiles block holds one block per environment, each written as a delta to the root of the same file:

my-app {
host = "localhost"
primary-host = ${my-app.host}
pool-size = 4
}
profiles {
production.my-app {
host = "db.internal"
pool-size = 32
}
staging = ${profiles.production}
}

The active profile’s block is laid over the root of its file, and every other profile is dropped. Select it in code with withProfile, or with the ACTOR_TS_PROFILE environment variable:

import { ActorSystem, ActorSystemOptions } from 'actor-ts';
const actorSystemOptions = ActorSystemOptions.create().withProfile('production');
const system = ActorSystem.create('my-app', actorSystemOptions);
  • Code beats the environment. withProfile — profile when you call Config.load yourself — outranks ACTOR_TS_PROFILE, and no profile is the default. An empty name selects none, which is how code opts out of one the environment selected.
  • An unknown profile fails closed. A name neither the application file nor the secrets file defines is refused at startup, naming the profiles they do define — read as “no overlay”, a misspelled ACTOR_TS_PROFILE=prodution would start production on the root’s development values. Every profile is checked to be a block when the file is read, active or not.
  • profiles is reserved at the root. The block is stripped before the tree is used, so an inactive profile never reaches system.config, the config dump or the DevTools panel. A root profiles key in the config object you pass in code is refused rather than ignored. my-app.profiles, below the root, is an ordinary key.
  • The profile is laid over first, then substitutions resolve. An alias in the root follows the profile: above, primary-host reads db.internal under production and localhost without a profile. An inactive profile is never resolved, so a variable only production needs may be unset on a laptop.
  • A profile reads the root of its own file, the layers beneath it and the environment — never a layer above. A profile of application.conf can read a key the bundled or the project reference.conf sets, but not one only the secrets file sets, and a substitution that reads the profiles block is refused by name.
  • staging = ${profiles.production} copies a whole profile, verbatim. A later delta does not merge into the copy: a profiles.staging.my-app.pool-size = 8 after it replaces the copied block, and host is gone. The ${profiles.production} { … } form that would merge is not supported yet (#537) — write a profile out in full when it differs from the one it would copy.

withProfile reaches the configuration of the system it builds, system.config. A few components read the configuration themselves when no system or Config is handed to them: ClusterClient, InMemoryLease, KubernetesLease and WorkerCluster.spawn, and the exported read…OptionsFromConfig helpers called without a Config, readMessageBoundaryOptionsFromConfig, readLeaseOptionsFromConfig, readKubernetesLeaseOptionsFromConfig and readOffloadPoolOptionsFromConfig among them. They call Config.load() and see a profile only through ACTOR_TS_PROFILE — set the variable when you use them, or hand them system.config. A WorkerMesh hands its worker pool the main system’s system.config, and its workers select no profile of their own: they run with the values the main system’s profile produced.

Credentials do not belong in application.conf. An optional second file holds them, read after the application file and merged above it:

my-app.db {
user = "app"
password = "s3cr3t"
}
profiles.production.my-app.db.password = ${?PRODUCTION_DB_PASSWORD}

It is the first of these that is set: withSecretsFile(path) on ActorSystemOptions, the ACTOR_TS_SECRETS_CONF environment variable, then secrets.conf in the working directory — secretsConfPath takes the setting’s place when you call Config.load yourself, and false reads no secrets file.

import { ActorSystem, ActorSystemOptions } from 'actor-ts';
const actorSystemOptions = ActorSystemOptions.create().withSecretsFile('/run/secrets/orders.conf');
const system = ActorSystem.create('orders', actorSystemOptions);

A file that is not there is an empty layer, not an error, so a deployment without one needs nothing. A file that is there is read on every start, so a secrets.conf in the working directory that belongs to another tool stops startup: the ConfigError names the file and why it was read — move such a file, or name the right one with withSecretsFile or ACTOR_TS_SECRETS_CONF. It splits into a root and profiles exactly as the application file does, and the same profile is laid over its root.

Every value it sets is withheld from the config dump and the DevTools panel, whatever its key is called — my-app.db.user above included — and that holds when a higher layer overrides the key and in a WorkerMesh worker, which receives its whole tree as one overrides object. The dump’s header names the file it looked for, and says when it was not there.

Keep the file out of version control — secrets.conf in .gitignore — and in production mount it from your platform’s secret store: see the Kubernetes and Docker Compose recipes.

Option values are validated once, at consume time, on the merged settings — after the layers above are resolved. Because it runs on the merged result, the same rules apply no matter how a value arrived: the fluent builder, a plain settings object, or a HOCON key. Cross-field rules (e.g. “downThreshold must exceed unreachableThreshold”) see the final values.

An invalid value throws an OptionsError (exported from the package root), naming the offending field and what it expected:

MqttOptions: protocolVersion must be one of 4, 5 (got 6)
  • For broker actors (MQTT, Kafka, WebSocket client, …) the error is raised when the actor starts (preStart), after the required-field check — so a missing required setting still surfaces as BrokerOptionsError, and only present-but-invalid values become OptionsError.
  • For non-broker consumers (caches, leases, sharding, …) the error is raised from the constructor.

OptionsError is distinct from ConfigError (malformed HOCON — wrong type, missing path) and BrokerOptionsError (a required broker setting absent from every layer). Unset optional fields never trigger it; they fall through to their defaults.

import { CircuitBreaker, CircuitBreakerOptions, OptionsError } from 'actor-ts';
// Non-broker consumers validate in their constructor, so the error is
// thrown synchronously and a plain try/catch works:
try {
const options = CircuitBreakerOptions.create()
.withMaxFailures(0); // invalid — must be a positive integer
new CircuitBreaker(options); // validates in the constructor
} catch (e) {
if (e instanceof OptionsError) {
console.error(`bad option ${e.field}: ${e.message}`);
}
}
// For a broker actor the OptionsError is thrown later in preStart and
// re-wrapped as ActorInitializationError, so it surfaces via supervision
// (not the spawning call's try/catch).