Connecting

Connection Modes

KapeVpnManager supports two connection modes via KapeConnectionMode:

var vpn = new KapeVpnManager(handle);

// Automatic — the daemon picks the best location
await vpn.ConnectAsync(KapeConnectionMode.Auto);

// Manual — connect to a specific location
await vpn.ConnectAsync(KapeConnectionMode.Manual("us-east-1"));

// Direct shorthand for manual
await vpn.ConnectAsync(location);   // a KapeServerLocation

Mode	Behaviour
Auto	The daemon selects the best available location (Smart Location).
Manual(locationId)	Connects to the specified location. The locationId comes from KapeServerLocation.Id.

ConnectAsync selects the location, asks the daemon to connect and returns once the status reaches Connected. Pass a CancellationToken to time out. If already connected to that location it returns at once; if connected to a different one, the daemon switches servers without disconnecting first.

The daemon remembers the selection: SelectedLocationId is the chosen location's id, or null for Auto.

Disconnecting

await vpn.DisconnectAsync();

Connection Status

The daemon pushes every state transition:

vpn.ConnectionStatusChanged += status => { /* every transition */ };
var current = vpn.ConnectionStatus;

Value	Meaning
Disconnected	No active tunnel
Connecting	Establishing the tunnel
Connected	Tunnel is up and carrying traffic
Reconnecting	The tunnel dropped or is being replaced; the daemon is bringing it back
Disconnecting	Intentional disconnect in progress

Once connected, ExternalVpnIp is the tunnel's public IP and ExternalIp the device's own; LocationName names the connected location.

Connection Errors

Failures the daemon reports while connecting or connected are delivered via the ConnectionError event. Each distinct occurrence fires the event exactly once.

vpn.ConnectionError += error => Console.WriteLine($"Tunnel failed: {error}");

KapeVpnError	Meaning
AuthenticationFailed	Authentication was rejected by the server
ConnectionLost	The tunnel dropped unexpectedly
ProxyUnreachable	The configured proxy could not be reached
DnsConfigFailed	DNS configuration could not be applied
ConnectionLimitReached	The account's simultaneous-connection limit was exceeded
SessionExpired	The server-side session expired; the user must log in again

A call the daemon rejects outright — for example connecting while logged out — throws KapeError from ConnectAsync instead, with the daemon's error name (DaemonRPCNotLoggedIn) as the message.

Losing the Daemon

When the connection to the daemon itself closes — for example while it restarts after an upgrade — KapeSdkHandle.Disconnected fires and every later call throws KapeError with KapeError.TransportDomain. DisconnectReason holds the underlying exception, or null on a clean close. Create a new handle to reconnect:

handle.Disconnected += async () =>
{
    await Task.Delay(TimeSpan.FromSeconds(2));
    handle = await KapeSdkHandle.CreateAsync();
    vpn = new KapeVpnManager(handle);
};