
Small API to launch WireGuard userspace VPN sessions using BoringTun crypto and a native Rust daemon for TUN packet I/O, route/DNS management, local IPC, and runtime snapshots.
A Kotlin Multiplatform WireGuard runtime backed by BoringTun and a native Rust daemon.
WG-Kotlin provides a small Kotlin API for opening WireGuard userspace VPN sessions. Crypto and key helpers are backed by BoringTun through UniFFI, while privileged TUN, route, and DNS work is handled by a local Rust daemon.
utun[0-9]+ on every daemon platform.Vpn, then start, inspect, or stop TUN sessions by name.Publish WG-Kotlin to Maven Local:
./gradlew publishToMavenLocal -PsignAllPublications=falseThen add it to your JVM/KMP project:
repositories {
mavenLocal()
mavenCentral()
// Required by the current kotlinx.rpc protobuf runtime.
maven("https://redirector.kotlinlang.org/maven/kxrpc-grpc")
}
kotlin {
sourceSets {
commonMain.dependencies {
implementation("com.rafambn:wg-kotlin:0.5.1")
}
}
}The wg-kotlin JVM JAR includes the generated UniFFI bindings and BoringTun for
Windows x64, macOS x64/ARM64, and Linux x64/ARM64.
JNA loads the library for the current platform. Consumers need no classifiers,
extra runtime dependencies, Rust toolchain, or manual native-library installation.
Linux x64 builds use Ubuntu 22.04 and Linux ARM64 builds use Ubuntu 24.04; older
libc versions are not covered by these builds.
Local development builds include only the build host's native runtime. Release publishing assembles all five runtimes through the Publish Maven workflow and rejects incomplete sets before uploading. The daemon is distributed separately.
Download the executable for your platform from GitHub Releases, or build it:
cargo build --manifest-path wg-kotlin-daemon-rust/daemon/Cargo.toml --releasePublishing a GitHub release, including a prerelease, runs the Build and Test
workflow for Windows x64, macOS x64/ARM64, and Linux x64/ARM64. It attaches the
Windows .exe and Unix .tar.gz archives to that release. The archives preserve
the daemon's executable permission. Creating a tag alone does not trigger it.
Linux daemon archives use the x86_64-unknown-linux-musl and
aarch64-unknown-linux-musl targets with a statically linked C runtime, so they do
not require the host's glibc or MUSL libraries. The workflow checks that neither
a dynamic loader nor shared libraries are required before uploading. Linux still
requires kernel 5.3+ and resolvectl; the application supplies elevation.
The separate Publish Maven workflow builds BoringTun for all five platforms,
verifies a JVM consumer using one dependency, and publishes WG-Kotlin
to Maven Central. Running it manually without release_tag performs the builds
and verification without publishing to Central. To recover an existing release,
run either workflow from master and provide its exact tag in release_tag.
The workflow builds that tag's source with the updated workflow, then attaches
the daemon assets or publishes Maven artifacts. Do not republish a Maven version
that is already available on Central. Neither workflow starts an elevated daemon.
The application supplies the privileged launcher. The library verifies OS peer identity, opens local IPC sessions, and controls daemon termination:
import com.rafambn.wgkotlin.daemon.DaemonProcess
import com.rafambn.wgkotlin.daemon.ProcessDaemonHandle
// Linux desktop example. The system polkit agent handles the permission dialog.
val daemon = DaemonProcess.launch { arguments ->
val process = ProcessBuilder(listOf("pkexec", "/absolute/path/wg-kotlin-daemon") + arguments)
.redirectOutput(ProcessBuilder.Redirect.DISCARD)
.redirectError(ProcessBuilder.Redirect.INHERIT)
.start()
ProcessDaemonHandle(process)
}DaemonProcess.launch(...) registers the daemon used by Vpn(...); it does not
create VPN objects. A Vpn(engine) manages multiple TUNs through
start(configuration), information(tunName), and stop(tunName).
Each daemon has one endpoint: a named pipe on Windows or a Unix domain socket on Linux/macOS. Each TUN owns an independent connection to that endpoint. The daemon checks the app's kernel-reported PID and live process identity before accepting configuration. The client verifies the daemon's identity too. There is no bearer secret or TCP listener.
For macOS and Windows, supply an app-specific native launcher returning control of the actual daemon process. Standard streams need not survive elevation. See the launcher contract and platform integration.
Generate a key pair:
import com.rafambn.wgkotlin.util.WireGuardKeys
val localKeys = WireGuardKeys.generateKeyPair()
val presharedKey = WireGuardKeys.generatePresharedKey()Start a VPN session from a coroutine. IP addresses and CIDRs must already be parsed:
import com.rafambn.wgkotlin.DnsConfig
import com.rafambn.wgkotlin.Vpn
import com.rafambn.wgkotlin.VpnConfiguration
import com.rafambn.wgkotlin.VpnPeer
import com.rafambn.wgkotlin.daemon.proto.Cidr
import com.rafambn.wgkotlin.daemon.proto.Ip
import com.rafambn.wgkotlin.daemon.proto.invoke
import kotlinx.io.bytestring.ByteString
val vpn = Vpn()
val address = Ip { value = Ip.Value.V4(ByteString(byteArrayOf(10, 0, 0, 2))) }
val dnsServer = Ip { value = Ip.Value.V4(ByteString(byteArrayOf(1, 1, 1, 1))) }
val peerAddress = Ip { value = Ip.Value.V4(ByteString(byteArrayOf(203.toByte(), 0, 113, 10))) }
val defaultRoute = Cidr {
ip = Ip { value = Ip.Value.V4(ByteString(ByteArray(4))) }
prefix = 0u
}
vpn.start(
VpnConfiguration(
interfaceName = "utun0",
privateKey = localKeys.privateKey,
listenPort = 0,
addresses = listOf(Cidr { ip = address; prefix = 32u }),
dns = DnsConfig(
servers = listOf(dnsServer),
searchDomains = listOf("example.com"),
),
peers = listOf(
VpnPeer(
publicKey = "remote-peer-public-key-base64",
presharedKey = presharedKey,
endpointAddress = peerAddress,
endpointPort = 51820,
allowedIps = listOf(defaultRoute),
persistentKeepalive = 25,
),
),
),
).getOrThrow()
val information = vpn.information("utun0")
vpn.stop("utun0").getOrThrow()
// Close all VPN sessions first. Requests daemon shutdown, then forces exit
// after five seconds if necessary.
daemon.close()
// For an unresponsive daemon, daemon.kill() forces OS termination directly.utun[0-9]+, even on Linux and Windows.resolvectl in PATH, even when a session does not configure DNS.51820 when listenPort is not set.WG-Kotlin uses the com.rafambn Maven namespace and Apache 2.0 license.
Maven Central publishing requires a Central user token and a signing key.
Provide mavenCentralUsername,
mavenCentralPassword, signingInMemoryKey, and signingInMemoryKeyPassword as
Gradle properties or ORG_GRADLE_PROJECT_ environment variables. See the
publishing plugin documentation.
The Rust crate lives in boringtun/ with the standard src/lib.rs layout.
The wg-kotlin Gradle module builds it and generates its bindings directly; the crate has no separate
Gradle module or Maven publication.
To upload WG-Kotlin for manual release in the Central Portal:
./gradlew publishToMavenCentral -PnativeRuntimeDirectory=/absolute/path/native-runtimesnative-runtimes must contain the shared libraries under their JNA resource
prefixes: darwin-aarch64, darwin-x86-64, linux-aarch64, linux-x86-64, and
win32-x86-64. The Publish Maven workflow builds and assembles this directory.
For release publishing, configure the repository secrets MAVEN_CENTRAL_USERNAME,
MAVEN_CENTRAL_PASSWORD, GPG_KEY_CONTENTS, and SIGNING_PASSWORD. The release tag
must match the Gradle version, optionally prefixed with v.
After publishing locally, verify an independent JVM consumer that loads BoringTun without a daemon:
./gradlew -p tests/jvm-consumer runBuild and test Kotlin:
./gradlew :wg-kotlin:checkRun Rust daemon tests:
cargo test --manifest-path wg-kotlin-daemon-rust/Cargo.tomlRun everything:
./gradlew buildJDK 17 is required for Gradle builds.
A Kotlin Multiplatform WireGuard runtime backed by BoringTun and a native Rust daemon.
WG-Kotlin provides a small Kotlin API for opening WireGuard userspace VPN sessions. Crypto and key helpers are backed by BoringTun through UniFFI, while privileged TUN, route, and DNS work is handled by a local Rust daemon.
utun[0-9]+ on every daemon platform.Vpn, then start, inspect, or stop TUN sessions by name.Publish WG-Kotlin to Maven Local:
./gradlew publishToMavenLocal -PsignAllPublications=falseThen add it to your JVM/KMP project:
repositories {
mavenLocal()
mavenCentral()
// Required by the current kotlinx.rpc protobuf runtime.
maven("https://redirector.kotlinlang.org/maven/kxrpc-grpc")
}
kotlin {
sourceSets {
commonMain.dependencies {
implementation("com.rafambn:wg-kotlin:0.5.1")
}
}
}The wg-kotlin JVM JAR includes the generated UniFFI bindings and BoringTun for
Windows x64, macOS x64/ARM64, and Linux x64/ARM64.
JNA loads the library for the current platform. Consumers need no classifiers,
extra runtime dependencies, Rust toolchain, or manual native-library installation.
Linux x64 builds use Ubuntu 22.04 and Linux ARM64 builds use Ubuntu 24.04; older
libc versions are not covered by these builds.
Local development builds include only the build host's native runtime. Release publishing assembles all five runtimes through the Publish Maven workflow and rejects incomplete sets before uploading. The daemon is distributed separately.
Download the executable for your platform from GitHub Releases, or build it:
cargo build --manifest-path wg-kotlin-daemon-rust/daemon/Cargo.toml --releasePublishing a GitHub release, including a prerelease, runs the Build and Test
workflow for Windows x64, macOS x64/ARM64, and Linux x64/ARM64. It attaches the
Windows .exe and Unix .tar.gz archives to that release. The archives preserve
the daemon's executable permission. Creating a tag alone does not trigger it.
Linux daemon archives use the x86_64-unknown-linux-musl and
aarch64-unknown-linux-musl targets with a statically linked C runtime, so they do
not require the host's glibc or MUSL libraries. The workflow checks that neither
a dynamic loader nor shared libraries are required before uploading. Linux still
requires kernel 5.3+ and resolvectl; the application supplies elevation.
The separate Publish Maven workflow builds BoringTun for all five platforms,
verifies a JVM consumer using one dependency, and publishes WG-Kotlin
to Maven Central. Running it manually without release_tag performs the builds
and verification without publishing to Central. To recover an existing release,
run either workflow from master and provide its exact tag in release_tag.
The workflow builds that tag's source with the updated workflow, then attaches
the daemon assets or publishes Maven artifacts. Do not republish a Maven version
that is already available on Central. Neither workflow starts an elevated daemon.
The application supplies the privileged launcher. The library verifies OS peer identity, opens local IPC sessions, and controls daemon termination:
import com.rafambn.wgkotlin.daemon.DaemonProcess
import com.rafambn.wgkotlin.daemon.ProcessDaemonHandle
// Linux desktop example. The system polkit agent handles the permission dialog.
val daemon = DaemonProcess.launch { arguments ->
val process = ProcessBuilder(listOf("pkexec", "/absolute/path/wg-kotlin-daemon") + arguments)
.redirectOutput(ProcessBuilder.Redirect.DISCARD)
.redirectError(ProcessBuilder.Redirect.INHERIT)
.start()
ProcessDaemonHandle(process)
}DaemonProcess.launch(...) registers the daemon used by Vpn(...); it does not
create VPN objects. A Vpn(engine) manages multiple TUNs through
start(configuration), information(tunName), and stop(tunName).
Each daemon has one endpoint: a named pipe on Windows or a Unix domain socket on Linux/macOS. Each TUN owns an independent connection to that endpoint. The daemon checks the app's kernel-reported PID and live process identity before accepting configuration. The client verifies the daemon's identity too. There is no bearer secret or TCP listener.
For macOS and Windows, supply an app-specific native launcher returning control of the actual daemon process. Standard streams need not survive elevation. See the launcher contract and platform integration.
Generate a key pair:
import com.rafambn.wgkotlin.util.WireGuardKeys
val localKeys = WireGuardKeys.generateKeyPair()
val presharedKey = WireGuardKeys.generatePresharedKey()Start a VPN session from a coroutine. IP addresses and CIDRs must already be parsed:
import com.rafambn.wgkotlin.DnsConfig
import com.rafambn.wgkotlin.Vpn
import com.rafambn.wgkotlin.VpnConfiguration
import com.rafambn.wgkotlin.VpnPeer
import com.rafambn.wgkotlin.daemon.proto.Cidr
import com.rafambn.wgkotlin.daemon.proto.Ip
import com.rafambn.wgkotlin.daemon.proto.invoke
import kotlinx.io.bytestring.ByteString
val vpn = Vpn()
val address = Ip { value = Ip.Value.V4(ByteString(byteArrayOf(10, 0, 0, 2))) }
val dnsServer = Ip { value = Ip.Value.V4(ByteString(byteArrayOf(1, 1, 1, 1))) }
val peerAddress = Ip { value = Ip.Value.V4(ByteString(byteArrayOf(203.toByte(), 0, 113, 10))) }
val defaultRoute = Cidr {
ip = Ip { value = Ip.Value.V4(ByteString(ByteArray(4))) }
prefix = 0u
}
vpn.start(
VpnConfiguration(
interfaceName = "utun0",
privateKey = localKeys.privateKey,
listenPort = 0,
addresses = listOf(Cidr { ip = address; prefix = 32u }),
dns = DnsConfig(
servers = listOf(dnsServer),
searchDomains = listOf("example.com"),
),
peers = listOf(
VpnPeer(
publicKey = "remote-peer-public-key-base64",
presharedKey = presharedKey,
endpointAddress = peerAddress,
endpointPort = 51820,
allowedIps = listOf(defaultRoute),
persistentKeepalive = 25,
),
),
),
).getOrThrow()
val information = vpn.information("utun0")
vpn.stop("utun0").getOrThrow()
// Close all VPN sessions first. Requests daemon shutdown, then forces exit
// after five seconds if necessary.
daemon.close()
// For an unresponsive daemon, daemon.kill() forces OS termination directly.utun[0-9]+, even on Linux and Windows.resolvectl in PATH, even when a session does not configure DNS.51820 when listenPort is not set.WG-Kotlin uses the com.rafambn Maven namespace and Apache 2.0 license.
Maven Central publishing requires a Central user token and a signing key.
Provide mavenCentralUsername,
mavenCentralPassword, signingInMemoryKey, and signingInMemoryKeyPassword as
Gradle properties or ORG_GRADLE_PROJECT_ environment variables. See the
publishing plugin documentation.
The Rust crate lives in boringtun/ with the standard src/lib.rs layout.
The wg-kotlin Gradle module builds it and generates its bindings directly; the crate has no separate
Gradle module or Maven publication.
To upload WG-Kotlin for manual release in the Central Portal:
./gradlew publishToMavenCentral -PnativeRuntimeDirectory=/absolute/path/native-runtimesnative-runtimes must contain the shared libraries under their JNA resource
prefixes: darwin-aarch64, darwin-x86-64, linux-aarch64, linux-x86-64, and
win32-x86-64. The Publish Maven workflow builds and assembles this directory.
For release publishing, configure the repository secrets MAVEN_CENTRAL_USERNAME,
MAVEN_CENTRAL_PASSWORD, GPG_KEY_CONTENTS, and SIGNING_PASSWORD. The release tag
must match the Gradle version, optionally prefixed with v.
After publishing locally, verify an independent JVM consumer that loads BoringTun without a daemon:
./gradlew -p tests/jvm-consumer runBuild and test Kotlin:
./gradlew :wg-kotlin:checkRun Rust daemon tests:
cargo test --manifest-path wg-kotlin-daemon-rust/Cargo.tomlRun everything:
./gradlew buildJDK 17 is required for Gradle builds.