Struct AgentBuilder 

pub struct AgentBuilder { /* private fields */ }

Builder for configuring an Agent before connecting to the network.

The builder allows customization of the agent’s identity:

• Machine key path: Where to store/load the machine keypair
• Agent keypair: Import a portable agent identity from another machine
• User keypair: Bind a human identity to this agent

Example

use x0x::Agent;

// Default: auto-generates both keypairs
let agent = Agent::builder()
    .build()
    .await?;

// Custom machine key path
let agent = Agent::builder()
    .with_machine_key("/custom/path/machine.key")
    .build()
    .await?;

// Import agent keypair
let agent_kp = load_agent_keypair()?;
let agent = Agent::builder()
    .with_agent_key(agent_kp)
    .build()
    .await?;

// With user identity (three-layer)
let agent = Agent::builder()
    .with_user_key_path("~/.x0x/user.key")
    .build()
    .await?;

Implementations

impl AgentBuilder

pub fn with_machine_key<P: AsRef<Path>>(self, path: P) -> Self

Set a custom path for the machine keypair.

If not set, the machine keypair is stored in ~/.x0x/machine.key.

Arguments

• path - The path to store the machine keypair.

Returns

Self for chaining.

pub fn with_agent_key(self, keypair: AgentKeypair) -> Self

Import an agent keypair.

If not set, the agent keypair is loaded from storage (or generated fresh if no stored key exists).

This enables running the same agent on multiple machines by importing the same agent keypair (but with different machine keypairs).

Note: When an explicit keypair is provided via this method, it takes precedence over with_agent_key_path().

Arguments

• keypair - The agent keypair to import.

Returns

Self for chaining.

pub fn with_agent_key_path<P: AsRef<Path>>(self, path: P) -> Self

Set a custom path for the agent keypair.

If not set, the agent keypair is stored in ~/.x0x/agent.key. If no stored key is found at the path, a fresh one is generated and saved.

This is ignored when with_agent_key() provides an explicit keypair.

Arguments

• path - The path to store/load the agent keypair.

Returns

Self for chaining.

pub fn with_agent_cert_path<P: AsRef<Path>>(self, path: P) -> Self

Set a custom path for the agent certificate (agent.cert).

Required for multi-daemon setups that share a host — the default path (~/.x0x/agent.cert) is shared across daemons, causing last-writer-wins trampling that makes peers reject identity announcements as agent certificate agent_id mismatch.

Arguments

• path - The path to use for the agent certificate file.

Returns

Self for chaining.

pub fn with_network_config(self, config: NetworkConfig) -> Self

Set network configuration for P2P communication.

If not set, the agent is built without a network node or gossip runtime. Use NetworkConfig::default() to connect through the default bootstrap nodes.

Arguments

• config - The network configuration to use.

Returns

Self for chaining.

pub fn with_gossip_config(self, config: GossipConfig) -> Self

Set gossip overlay configuration.

This is primarily used by x0xd to expose operational knobs such as gossip.dispatch_workers. If the agent is built without a network configuration, the value is retained by the builder but has no runtime effect.

pub fn with_peer_cache_dir<P: AsRef<Path>>(self, path: P) -> Self

Set the directory for the bootstrap peer cache.

The cache persists peer quality metrics across restarts, enabling cache-first join strategy. Defaults to ~/.x0x/peers/ if not set. Falls back to ./.x0x/peers/ (relative to CWD) if $HOME is unset.

pub fn with_peer_cache_disabled(self) -> Self

Disable the bootstrap peer cache entirely.

When set, the agent will not open or load any cached peers on startup. This ensures complete network isolation from previously seen peers for embedders and dedicated test harnesses.

Note: the x0xd daemon’s --no-hard-coded-bootstrap flag does not call this; it only clears configured seed peers.

pub fn with_user_key(self, keypair: UserKeypair) -> Self

Import a user keypair for three-layer identity.

This binds a human identity to this agent. When provided, an identity::AgentCertificate is automatically issued (if one doesn’t already exist in storage) to cryptographically attest that this agent belongs to the user.

Note: When an explicit keypair is provided via this method, it takes precedence over with_user_key_path().

Arguments

• keypair - The user keypair to import.

Returns

Self for chaining.

pub fn with_user_key_path<P: AsRef<Path>>(self, path: P) -> Self

Set a custom path for the user keypair.

Unlike machine and agent keys, user keys are not auto-generated. If the file at this path doesn’t exist, no user identity is set (the agent operates with two-layer identity).

This is ignored when with_user_key() provides an explicit keypair.

Arguments

• path - The path to load the user keypair from.

Returns

Self for chaining.

pub fn with_heartbeat_interval(self, secs: u64) -> Self

Set the identity heartbeat re-announcement interval.

Defaults to IDENTITY_HEARTBEAT_INTERVAL_SECS (300 seconds).

Arguments

• secs - Interval in seconds between identity re-announcements.

pub fn with_identity_ttl(self, secs: u64) -> Self

Set the identity cache TTL.

Cache entries with last_seen older than this threshold are filtered from Agent::presence and Agent::discovered_agents.

Defaults to IDENTITY_TTL_SECS (900 seconds).

Arguments

• secs - Time-to-live in seconds for discovered agent entries.

pub fn with_presence_beacon_interval(self, secs: u64) -> Self

Override the presence beacon broadcast interval in seconds.

pub fn with_presence_event_poll_interval(self, secs: u64) -> Self

Override the presence event poll interval in seconds.

pub fn with_presence_offline_timeout(self, secs: u64) -> Self

Override the fallback offline timeout used by presence events.

pub fn with_contact_store_path<P: AsRef<Path>>(self, path: P) -> Self

Set a custom path for the contacts file.

The contacts file persists trust levels and machine records for known agents. Defaults to ~/.x0x/contacts.json if not set.

Arguments

• path - The path for the contacts file.

pub async fn build(self) -> Result<Agent>

Build and initialise the agent.

This performs the following:

1. Loads or generates the machine keypair (stored in ~/.x0x/machine.key by default)
2. Uses provided agent keypair or generates a fresh one
3. Combines both into a unified Identity

The machine keypair is automatically persisted to storage.

Errors

Returns an error if:

• Machine keypair generation fails
• Storage I/O fails
• Keypair deserialization fails

Trait Implementations

impl Debug for AgentBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.