Skip to main content

Getting Started

This guide walks you through the complete flow: connecting to the daemon, authenticating, browsing VPN servers, and establishing a VPN connection.

1. Create the Handle​

KapeSdkHandle is the connection to the daemon. Create one per application session and dispose it on shutdown — it implements IAsyncDisposable.

using Kape.Core;

await using var handle = await KapeSdkHandle.CreateAsync();  // auto-detects platform

CreateAsync connects and waits for the daemon's first state push, so every property below is populated once it returns. It throws KapeError if the daemon cannot be reached. Keep the handle alive for the lifetime of your app; all other SDK objects reference it. See Installation for explicit endpoint control.

2. Authenticate​

using Kape.Auth;

var auth = new KapeAuthClient(handle);

if (auth.AuthState == KapeAuthState.Unauthenticated)
    await auth.LoginAsync(activationCode);

// Check the session
if (auth.CurrentAuthenticationSession is { } session)
    Console.WriteLine($"Logged in as {session.Email}");

3. Observe Auth State​

auth.AuthStateChanged += state =>
{
    switch (state)
    {
        case KapeAuthState.Authenticated:   /* show home screen */  break;
        case KapeAuthState.Unauthenticated: /* show login screen */ break;
    }
};
warning

Every SDK event fires on the connection's internal read-loop thread. GUI applications must dispatch to the UI thread before touching UI state.

4. Browse VPN Locations​

using Kape.Vpn;

var locations = new KapeLocationService(handle);
var all = await locations.FetchLocationsAsync();

// Locations grouped by country
foreach (var country in all.GroupBy(l => l.Country))
{
    Console.WriteLine($"{country.Key}:");
    foreach (var server in country)
        Console.WriteLine($"  {server.Name} ({server.PingMs} ms)");
}

5. Connect to VPN​

var vpn = new KapeVpnManager(handle);

// Observe connection status
vpn.ConnectionStatusChanged += status =>
    Console.WriteLine(status); // Connecting, Connected, Disconnecting, Disconnected

// Connect to a location; returns once the tunnel is up
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
await vpn.ConnectAsync(location, cts.Token);

6. Disconnect​

await vpn.DisconnectAsync();

7. Log Out​

await auth.LogoutAsync();

Example Apps​

The SDK ships with complete working examples:

  • Kape.PlatformSdk.Example — console app: connect, print status changes, interactive commands
  • Kape.PlatformSdk.Gui — Avalonia desktop demo: login, location picker, protocol selection, split tunnel, connect/disconnect

Next Steps​

  • Authentication — daemon-owned login
  • VPN — connection lifecycle, protocols, server locations, network protection