Outline SDK: composing network transports instead of shipping a VPN

A transport toolkit rather than a ready-made client

The Outline SDK is described as an SDK to build network tools based on Outline components, and the project states that it exists so you can create tools to protect against network-level interference, add that protection to existing apps such as content or communication apps, and troubleshoot connectivity and measure interference with a collection of command-line tools.

The framing matters. This is not a VPN client with a settings screen. It is a set of parts that you assemble into whatever shape of client you need. The claimed advantages are multi-platform support for Android, iOS, Windows, macOS and Linux, field-testing in the Outline Client and Server, and a design intended for modularity so you can craft custom transports.

The homepage points at the developer section of the Outline site, and the repository is under the OutlineFoundation organisation after the transition from Jigsaw. The code is Go, the licence is Apache-2.0, and the project is explicitly labelled Beta in its README title.

For an engineer the question is whether the parts fit your problem. If you need a consumer VPN application, the Outline Client already is one, and writing your own on top of this SDK is work you would have to justify. If you need something specific, a diagnostic tool, an embedded transport in a chat app, a research harness, then the SDK is the interesting object.

Connections, dialers and resolvers: the three interfaces

The SDK is built on a small number of concepts, defined as interoperable interfaces that allow composition and reuse. Understanding those three is enough to read most of the API.

Connections enable communication between two endpoints over an abstract transport, and there are two of them. transport.StreamConn is a stream based connection, like TCP and the SOCK_STREAM Posix socket type, and transport.PacketConn is a datagram based one, like UDP and SOCK_DGRAM. The project notes it uses Packet rather than Datagram because that is the convention in the Go standard library.

The point of the abstraction is nesting. A StreamConn can be over TCP, over TLS over TCP, over HTTP over TLS over TCP, or over QUIC. Each layer wraps the one below it, so a different transport can be substituted without touching the code above.

Dialers create connections given a host and port address while encapsulating the underlying transport or proxy protocol. StreamDialer and PacketDialer create StreamConn and PacketConn respectively, and dialers nest too. The documented example is a TLS stream dialer using a TCP dialer underneath, and a SOCKS5 over TLS dialer that opens the TLS connection to the proxy before doing the SOCKS5 handshake to the target.

Resolvers, in the dns package, answer DNS questions while encapsulating the underlying algorithm or protocol, and are primarily used to map domain names to IP addresses. That is the third axis of the design: what you connect to, how you connect, and how you look up the name.

Two strategies for DNS blocking, and two for SNI blocking

The SDK is explicit about the two interference problems it addresses and offers more than one strategy for each, because a single technique is easy to block.

For DNS-based blocking, the dns package replaces system resolution with more resilient options: encrypted DNS over HTTPS or over TLS, and alternative hosts and ports for UDP and TCP resolvers, which makes it possible to reach resolvers that are not themselves blocked. The second approach is address override, using the override config from x/configurl with a host option to force a specific address, or implementing your own dialer that maps addresses. Override is the heavier hammer: it stops relying on DNS entirely for the names you care about.

For SNI-based blocking, the strategies are split by layer. At the TCP layer there is TCP stream fragmentation with transport/split and TLS record fragmentation with transport/tlsfrag. At the application layer there is domain fronting and SNI hiding with transport/tls.

The split matters because the two layers fail differently. Fragmentation changes the shape of the traffic on the wire, while SNI hiding changes what the ClientHello says. An operator blocking by SNI can be defeated at the TLS layer without touching TCP framing, and vice versa.

Note the naming. These are components, not turnkey policies. The SDK gives you the pieces; deciding which combination to ship, and how to configure the fragmentation, is left to the application.

Proxy tunnels and TUN-based VPNs from the same building blocks

Two protocols are provided for carrying connections over a proxy. Shadowsocks lives in transport/shadowsocks, and the documentation points at the Outline Manager as the way to create servers in the cloud easily. SOCKS5 lives in transport/socks5, and the documentation suggests leveraging a local SOCKS5 proxy that tunnels connections over SSH.

Because a SOCKS5 connection is itself a connection type, the proxy support composes with the layering described above rather than sitting beside it. A dialer stack can open TLS to the proxy, then run SOCKS5 inside it, and the result is still a StreamConn that the rest of your code cannot tell apart from a direct connection.

For full device level behaviour, the network package creates TUN based VPNs using transport layer proxies, the technique often called tun2socks. The dependency list confirms the implementation approach: go-tun2socks is a direct dependency, alongside go-shadowsocks2 and go-socks5, gopacket for packet handling, golang.org/x/crypto and golang.org/x/net.

That composition is the reason to use the SDK rather than a single-purpose library. A tun2socks implementation normally binds you to one transport. Here the transport underneath the TUN layer can be Shadowsocks, SOCKS5 over TLS, or something you write, and the DNS strategy that the virtual interface uses can be chosen independently of the tunnel.

Four integration routes, and the module path that just moved

There are four ways to get the SDK into a project. The Generated Mobile Library uses gomobile bind to generate Java and Objective-C bindings, for Android, iOS and macOS apps. The Side Service runs the SDK out of process and is aimed at desktop and Android apps. The Go Library is the direct route for a Go application. The Generated C Library covers the remaining native cases.

The choice of route is a deployment decision rather than a technical one. An in-process Go library is simplest. A side service is what you want when the host app is not written in Go, or when you want the network code to survive an app restart. The generated bindings are for embedding in mobile apps where a native or cross-platform UI already exists.

The repository also carries run_on_android.sh and run_on_podman.sh at the root, which suggests the side service route is expected to be exercised on a phone and in a container.

Now the part that will break your build if you miss it. As part of the transition from Jigsaw to the new Outline Foundation, the Go module paths were migrated, and the module file at the root of the repository now reads:

module golang.getoutline.org/sdk

go 1.25.0

toolchain go1.25.5

The migration covers two paths, golang.getoutline.org/sdk and golang.getoutline.org/sdk/x. The documentation asks users to update imports as soon as possible, states that the old github.com/Jigsaw-Code/outline-sdk paths are deprecated and will no longer receive updates, and says that future stable releases are published exclusively under the new module paths. If you hit errors with go get or go run using the old paths, that is why.

Beta, Apache-2.0 and an experimental module for QUIC

The repository is not archived and the last push was on 2026-10-19. The release history shows how young this is: v0.1.0-rc1 on 2026-06-23, then two tags in the x module, x/v0.2.1 on 2026-09-09 described as QUIC version selection and maintenance, and x/v0.2.2 on 2026-09-26 described as QUIC preludes.

Those x tags are worth understanding rather than skipping. The stable line is still at a release candidate, while the experimental module is where the QUIC work is landing. The pattern says the core library is being stabilised while new transport work happens behind an unstable module path, which is a sensible structure, and also a reminder that anything you build on x/ is on a moving target.

The licence is Apache-2.0, which is permissive and carries an explicit patent grant, with the LICENSE file at the repository root. For a networking library that you may embed in a commercial application, that is a clean answer with no additional commercial condition attached.

The dependency list deserves a look before you adopt it. Besides the transport libraries, the module pulls in gopacket, x/crypto and x/net directly, and the indirect list includes spf13/cobra, the usual command line framework, along with a long tail of libraries. The cobra dependency is a hint that the command line tooling is part of the same module, which is convenient for the diagnostic tools and worth remembering if you only want the library part.

The command-line tools themselves cover resolving a domain name, fetching a web page, running a local forward proxy, testing proxy connectivity and testing download speed. For troubleshooting interference, those are the pieces that tell you which layer is failing.

Editorial conclusion

Adopt the Outline SDK if you are writing your own client or tool and need to choose a transport deliberately, for instance a QUIC connection with a specific DNS strategy, or if you need tun2socks behaviour without shipping a full VPN stack. Do not adopt it if you only need a working Outline setup, since the Outline Manager and client already cover that, and treat it as beta code that needs your own testing before it ships to users. Before you start, update your imports to golang.getoutline.org/sdk and golang.getoutline.org/sdk/x, because the old github.com/Jigsaw-Code/outline-sdk paths are deprecated and receive no further updates, then confirm the Go 1.25 toolchain requirement in go.mod matches your build environment.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. OutlineFoundation/outline-sdk on GitHub
3. Project website
4. README
5. Releases