---
agentTools:
  projectIndex: https://docs.rainway.com/llms.txt
---

# Rainway Network

# Rainway Network

The **Rainway Network** is how apps using Rainway find each other.

Each entity connected to the network is a **Peer**, identified by its Rainway **<<glossary:Peer ID>>**.

Peers on the Rainway Network exchange connection requests and session information in order to establish a peer-to-peer connection. Once a connection between Peers has been established, they no longer use the Rainway Network to communicate.

## First steps

Connecting to the Rainway Network happens automatically when you initialize `RainwayRuntime`.

`RainwayRuntime` is your way into the Rainway SDK. To initialize it, you must provide some configuration values and handlers through which Rainway and your app will communicate. This is done using the `initialize` static method on `Rainway::Runtime`.

You can leave all the handlers empty for now. Just make sure you provide your `apiKey`.

[block:callout]
{
  "type": "info",
  "body": "By the way, `externalId` is a string identifying a user or entity within your app. This way you can easily tie an incoming connection back to a user in your app."
}
[/block]

[block:code]
{
  "codes": [
    {
      "code": "#include \"rainwaysdk.h\"\n\nRainway::Config config {\n    \"your-organization's-api-key\", // apiKey\n    \"alice123\" // externalId\n};\n\nconfig.logSink = [](auto level, const auto &target, const auto &message) {};\n\nconfig.onRuntimeConnectionLost = [this](const auto error);\nconfig.onConnectionRequest = [this](const auto &request) {};\nconfig.onPeerStateChange = [this](auto &peer, const auto &state) {};\nconfig.onPeerMessage = [this](auto &peer, const auto &channel, const auto *data, const auto len) {};\nconfig.onPeerDataChannel = [this](auto &peer, auto &channel, auto mode) {};\nconfig.onPeerError = [this](auto &peer, const auto error) {};\nconfig.onStreamRequest = [this](const auto &request) {};\nconfig.onStreamAnnouncement = [this](auto &peer, auto stream) {};\nconfig.onStreamStop = [this](auto &peer, auto stream) {};\n\nauto runtimePromise = Rainway::Runtime::initialize(config);\nruntimePromise.wait();\nif (auto resolved = runtimePromise.get())\n{\n    runtime = std::move(*resolved);\n    // use the runtime\n}\nelse\n{\n    printf(\"Runtime failed to load\\n\");\n}",
      "language": "cplusplus"
    }
  ]
}
[/block]

Afterwards, `runtime` is ready to use. It's time to get connected peer-to-peer!

## Peer IDs

The first time RainwayRuntime is initialized on a device, it generates and stores a **Peer ID**. This is a 63-bit number that uniquely identifies the device on the Rainway Network.

To connect your device to another over Rainway, you must know the other's Peer ID. A device's Peer ID is exposed through the `peerId` property on RainwayRuntime.

[block:code]
{
  "codes": [
    {
      "code": "auto peerId = runtime->peerId();",
      "language": "cplusplus"
    }
  ]
}
[/block]

How you store Peer IDs will vary depending on how your application uses Rainway. For example, you could store them in your application database to let Peers know about each other.

## Connecting to a Peer

Once you have a Peer's ID, you can call `connect` to establish the connection:

[block:code]
{
  "codes": [
    {
      "code": "auto connectPromise = runtime->connect(remotePeerId);\nconnectPromise.wait();\nif (auto resolved = connectPromise.wait())\n{\n    auto peer = *resolved;\n}",
      "language": "cplusplus"
    }
  ]
}
[/block]

This promise will resolve once the Peer has *accepted* your connection request.

To test against the [example web app](https://github.com/RainwayApp/rainway-sdk-web-demo), try running it on another device, and connecting from your web app to its Peer ID.

## Multiple Peers

Rainway lets you connect to multiple Peers at a time. The `Peers` property on `RainwayRuntime` tracks every currently connected `RainwayPeer`, mapped by their Peer IDs.