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.