Bootstrapping Actor Swarm

For quick development and simple distributed actor setups, Kameo provides convenient bootstrap functions that automatically configure and start a libp2p swarm with sensible defaults. This approach gets you up and running with distributed actors in just one line of code.

Quick Bootstrap

The simplest way to get started with distributed actors is using the bootstrap() function:

use kameo::remote;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Bootstrap with automatic configuration
    let peer_id = remote::bootstrap()?;
    
    println!("Node started with peer ID: {}", peer_id);
    
    // Your actors can now be registered and discovered across the network
    Ok(())
}

This automatically:

• Creates a libp2p swarm with TCP and QUIC transports
• Enables mDNS for local peer discovery
• Starts listening on an OS-assigned port (0.0.0.0:0)
• Initializes the global actor registry
• Returns your node's PeerId for reference

Bootstrap on Specific Address

If you need to listen on a specific address (useful for known deployments or port requirements), use bootstrap_on():

use kameo::remote;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Bootstrap listening on a specific port
    let peer_id = remote::bootstrap_on("/ip4/0.0.0.0/tcp/8020")?;
    
    println!("Node listening on port 8020 with peer ID: {}", peer_id);
    Ok(())
}

You can use various multiaddress formats:

• /ip4/0.0.0.0/tcp/8020 - TCP on port 8020
• /ip4/127.0.0.1/tcp/8020 - TCP on localhost only
• /ip4/0.0.0.0/udp/8020/quic-v1 - QUIC on port 8020

Complete Example

Here's a full example showing how to bootstrap and immediately start using distributed actors:

use kameo::prelude::*;
use kameo::remote;

#[derive(Actor, RemoteActor)]
struct GreeterActor;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Bootstrap the distributed actor system
    let peer_id = remote::bootstrap()?;
    println!("Node started: {}", peer_id);
    
    // Spawn and register a local actor
    let greeter = GreeterActor::spawn_default();
    greeter.register("greeter").await?;
    println!("Greeter actor registered");
    
    // Look up all greeter actors in the network
    let mut greeters = RemoteActorRef::<GreeterActor>::lookup_all("greeter");
    while let Some(remote_greeter) = greeters.try_next().await? {
        println!("Found greeter on peer: {:?}", remote_greeter.id().peer_id());
    }
    
    // Keep the application running
    tokio::signal::ctrl_c().await?;
    Ok(())
}

What Bootstrap Includes

The bootstrap functions automatically configure:

• Transports: Both TCP and QUIC for maximum compatibility
• Security: Noise protocol for encrypted connections
• Multiplexing: Yamux for efficient connection usage
• Discovery: mDNS for automatic local peer discovery
• Timeouts: 60-second idle connection timeout
• Actor System: Full Kameo remote actor capabilities

When to Use Bootstrap

Bootstrap is perfect for:

• Development and testing - Get started quickly without configuration
• Simple deployments - When default settings meet your needs
• Prototyping - Rapid iteration on distributed actor logic
• Local networks - Leverages mDNS for automatic peer discovery

When You Need Custom Configuration

For production deployments or specific requirements, you may need a custom swarm setup instead of bootstrap:

• Custom transports (WebSocket, memory, etc.)
• Different discovery mechanisms (no mDNS, custom bootstrap peers)
• Integration with existing libp2p applications
• Custom security or authentication
• Specific connection management policies

In these cases, see Custom Swarm Configuration for full control over your network setup.

Bootstrap Limitations

Keep in mind that bootstrap:

• Uses mDNS (local network discovery only)
• Has fixed transport and security configuration
• Cannot be combined with other libp2p behaviors
• May not be suitable for production deployments

For more advanced networking needs, the custom swarm approach provides complete flexibility.

What's Next?

Now that your node is part of the distributed network, you can start registering actors and discovering peers. The bootstrap approach automatically handles peer discovery through mDNS, so nodes on the same local network will find each other automatically.

Continue to Registering and Lookup to learn how to make your actors discoverable across the network.