Networking and Conductor Configuration (0.7)

Everything here is read from holochain_conductor_api 0.7.0 (src/config/conductor.rs), holochain_p2p 0.7.0 (Cargo.toml) and kitsune2_bootstrap_srv 0.5.0. If a field is not listed here, check those sources rather than guessing: ConductorConfig is #[serde(deny_unknown_fields)], so an invented key is a startup error, not a silent no-op.

What changed in 0.7

The whole transport layer was replaced.

Kitsune2 is at 0.5.0 for the whole 0.7.0 line: kitsune2_api, kitsune2_core and kitsune2_transport_iroh all pin 0.5.0.

Client-side, the per-connection is_webrtc flag became is_direct. See client.md.

Minimal conductor config

This is the example from the holochain_conductor_api module documentation, unedited:

---
## Configure the keystore to be used.
keystore:
  ## Use an in-process keystore with default database location.
  type: lair_server_in_proc

## Configure an admin WebSocket interface at a specific port.
admin_interfaces:
  - driver:
      type: websocket
      port: 1234
      allowed_origins: "*"

## Configure the network.
network:
  ## Use the Holochain-provided dev-test bootstrap server.
  bootstrap_url: https://dev-test-bootstrap2.holochain.org

  ## Use the iroh relay server.
  relay_url: https://use1-1.relay.n0.iroh-canary.iroh.link./

allowed_origins is not optional and not defaulted. A browser UI that gets no response from the admin or app port is usually being rejected on origin, not on port.

NetworkConfig, field by field

Serialized under network: in conductor-config.yaml, snake_case, unknown fields rejected.

“Default” here means the Rust Default impl, not a serde default

bootstrap_url and relay_url are the two fields in the table with no #[serde(default)]. The distinction matters when you hand-write conductor-config.yaml:

• Omit the whole network: block and you get every value in the table, because ConductorConfig marks the field #[serde(default)] and falls back to NetworkConfig::default().
• Write a partial network: block that sets, say, only request_timeout_s, and startup fails with missing field bootstrap_url. Once the key is present, both URLs are required.

So a network: block is all-or-nothing on those two. Every other field in the table is individually optional.

The two defaults you should not ship with

dev-test-bootstrap2.holochain.org is named “dev-test” for a reason, and the default relay is an iroh canary host. Both are fine for development and neither is a production commitment by anyone. A hApp you distribute should point at infrastructure you or your community controls. See “Running your own bootstrap server” below.

request_timeout_s sets three timeouts, not one

Setting it derives two more values, per the field’s own documentation:

request_timeout_s              = 60   (what you set)
single transport message       = 30   floor(1/2 of request_timeout_s)
direct-connection attempt      = 22   floor(3/8 of request_timeout_s), before falling back to relay

So halving the request timeout also halves how long a peer waits before giving up on a direct connection and paying the relay’s latency. Tune it as one number with three consequences.

The 0.7 source still calls the third value the “webrtc connection” timeout in its doc comment. That is leftover wording from the tx5 era. The mechanism is iroh’s direct-path attempt before relay fallback.

target_arc_factor and leecher nodes

1 is normal operation: honour Kitsune2’s arc-size hints as given. Set it to 0 for a node that should not contribute to gossip at all, which the field documentation calls a “leecher node”.

A zero-arc node still reads from the DHT, but it stores nothing on behalf of the network. That is a legitimate configuration for a mobile or ephemeral client, and a bad one for the majority of a network’s nodes: if everyone leeches, nobody holds the data.

report

network:
  report:
    type: json_lines
    days_retained: 7
    fetched_op_interval_s: 60

Two variants only: None (the default, no reporting) and JsonLines { days_retained, fetched_op_interval_s }. Useful when diagnosing gossip behaviour over hours rather than seconds.

advanced

Direct Kitsune2 module configuration, as raw JSON. The named fields above are merged into it at startup: bootstrap_url becomes the serverUrl key of the core_bootstrap module, and so on. Anything you set directly in advanced for the same key is what the named field overwrites, so do not set both.

Use it only when you know which Kitsune2 module you are configuring. Module names seen in the 0.7 sources include k2Gossip (with keys like initiateIntervalMs) and the bootstrap module’s serverUrl.

Test-only network switches

disable_bootstrap, disable_publish and disable_gossip exist on NetworkConfig but are gated behind the test-utils cargo feature. They are how Sweettest builds isolated networks. They are not available on a stock conductor binary, and a config file naming them will fail to parse.

Running your own bootstrap server

The server is a standalone binary, kitsune2-bootstrap-srv, shipped by the kitsune2_bootstrap_srv crate (0.5.0 for the 0.7 line).

cargo install kitsune2_bootstrap_srv --version 0.5.0 --locked
kitsune2-bootstrap-srv --production --listen 0.0.0.0:443 --tls-cert cert.pem --tls-key key.pem

It runs in a testing configuration by default, with deliberately light resource settings, and switches to production settings only with --production:

--tls-cert and --tls-key require each other, both PEM encoded. --allowed-origins defaults to allowing any origin. --json switches tracing output to JSON.

A bootstrap server holds nothing but agent info: it is how peers find each other, not where data lives. Losing it partitions new joiners, not existing peers who already know each other.

The relay is a separate concern. Holochain uses iroh’s relay protocol, so any iroh relay will do, including one you run yourself.

Other conductor config fields worth knowing

From ConductorConfig in the same file:

Related

• debugging.md for reading what the network is actually doing at runtime
• client.md for dumpNetworkStats and dumpNetworkMetrics from TypeScript
• deployment.md for wiring these values into a Kangaroo build