Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 100 additions & 8 deletions snippets/relay-preset-config.mdx
Original file line number Diff line number Diff line change
@@ -1,17 +1,20 @@
Your dedicated relays require authentication by default. Your endpoint
authenticates to them with your project's API key. The `iroh_services::preset()` builder handles
this for you: it mints a short-lived access token scoped to your endpoint's key
and configures the endpoint to use your relays.
Your dedicated relays require authentication. Your endpoint authenticates to
them with your project's API key: the iroh-services preset mints a short-lived
access token scoped to your endpoint's key and to relay use only, then
configures the endpoint to use your relays.

Add the `iroh-services` crate to your project:
In Rust, add the `iroh-services` crate to your project:

```bash
cargo add iroh-services
```

Then build a preset and bind your endpoint with it:
The Python, Swift, Kotlin, and JavaScript bindings ship the preset as part of
`iroh-ffi`, with no extra dependency needed.

```rust
<CodeGroup>

```rust Rust
use iroh::Endpoint;

#[tokio::main]
Expand All @@ -36,6 +39,95 @@ async fn main() -> anyhow::Result<()> {
}
```

```python Python
import asyncio
import iroh

async def main():
# Build a preset pointing at your dedicated relays, authenticated with
# your project's API key. In production, load the key from a config file
# or environment variable instead of hardcoding it.
preset = iroh.preset_iroh_services(
iroh.ServicesPresetOptions(
relays=["YOUR_RELAY_URL_US", "YOUR_RELAY_URL_EU"],
api_secret="YOUR_API_KEY",
)
)

# Bind the endpoint with the preset, then wait until it's online to
# confirm it has an authorized connection to a relay.
ep = await iroh.Endpoint.bind(iroh.EndpointOptions(preset=preset))
await ep.online()

asyncio.run(main())
```

```swift Swift
import IrohLib

// Build a preset pointing at your dedicated relays, authenticated with your
// project's API key. In production, load the key from a config file or
// environment variable instead of hardcoding it.
let preset = try presetIrohServices(options: ServicesPresetOptions(
relays: ["YOUR_RELAY_URL_US", "YOUR_RELAY_URL_EU"],
apiSecret: "YOUR_API_KEY"
))

// Bind the endpoint with the preset, then wait until it's online to confirm
// it has an authorized connection to a relay.
let ep = try await Endpoint.bind(options: EndpointOptions(preset: preset))
await ep.online()
```

```kotlin Kotlin
import computer.iroh.*
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
// Build a preset pointing at your dedicated relays, authenticated with
// your project's API key. In production, load the key from a config file
// or environment variable instead of hardcoding it.
val preset = presetIrohServices(
ServicesPresetOptions(
relays = listOf("YOUR_RELAY_URL_US", "YOUR_RELAY_URL_EU"),
apiSecret = "YOUR_API_KEY",
),
)

// Bind the endpoint with the preset, then wait until it's online to
// confirm it has an authorized connection to a relay.
val ep = Endpoint.bind(EndpointOptions(preset = preset))
ep.online()
ep.shutdown()
}
```

```javascript JavaScript
import { Endpoint, presetIrohServices } from '@number0/iroh'

// Apply a preset pointing at your dedicated relays, authenticated with your
// project's API key. In production, load the key from a config file or
// environment variable instead of hardcoding it.
const builder = Endpoint.builder()
presetIrohServices(builder, {
relays: ['YOUR_RELAY_URL_US', 'YOUR_RELAY_URL_EU'],
apiSecret: 'YOUR_API_KEY',
})

// Bind the endpoint, then wait until it's online to confirm it has an
// authorized connection to a relay.
const ep = await builder.bind()
await ep.online()
```

</CodeGroup>

In JavaScript, presets are functions applied to an `EndpointBuilder`, so use
`Endpoint.builder()` rather than `Endpoint.bind()` — `bind()` always applies the
n0 preset.

<Note>
Custom relay URLs are available on Pro and Enterprise projects. On a free project, pass your API key to the preset without `relays(...)` to authenticate against the public relays and surface your relay traffic on the dashboard.
Custom relay URLs are available on Pro and Enterprise projects, or if you self-host your own relay.
</Note>

On a free project, omit the relay URLs — the preset then authenticates against the n0 public relays.
Loading