Choose an SDK
Choose a rstream SDK for the application runtime, connection model and protocols it needs.
rstream SDKs embed connectivity in an application. An outbound agent connection carries tunnels to the edge; published tunnels expose forwarding addresses, while private tunnels are reached by name or ID through an authenticated client.
The Go SDK is the reference implementation and offers the broadest protocol coverage. The other SDKs adapt that model to their runtime and concurrency conventions.
Choose the integration boundary
The CLI is the shortest path for forwarding an existing local service. Embed an SDK when the application process should own tunnel creation, accepted streams, private dialing and shutdown. HTTP API clients administer or observe resources; they do not carry the service's tunnel traffic. Browser clients receive narrowly scoped credentials from an application backend.
| Requirement | Owner and first step |
|---|---|
| Publish an existing listening service | Run the CLI forwarding workflow, or use a declarative controller. |
| Serve or dial from application code | Choose a native SDK below; keep the client, control channel and tunnel with the service lifecycle. |
| Discover projects, query engines or automate management | Choose an API client for the required surface. |
| Build a browser inventory or terminal | Follow Browser clients; the backend authorizes each delegated capability. |
Choose the application runtime
| SDK | Primary use | Integration guide |
|---|---|---|
| Go | Services, devices and agents using bytestream or datagram protocols. | Go SDK |
| JavaScript and TypeScript | Node.js tunnel runtimes, Control plane and Engine API clients, browser and React interfaces. | JavaScript SDK |
| C++ | Native services and devices using Boost.Asio handlers, futures or coroutines, with executor and allocator control. | C++ SDK |
| Python | Async services and workers, with direct ASGI and WSGI integration. | Python SDK |
| Java | JVM services using JDK streams, futures and framework examples. | Java SDK |
The capability comparison distinguishes advanced surfaces. Native engine connections use TLS in every SDK; Go also implements QUIC. Datagram tunnel creation is available in Go. Check the language guide for supported configuration options and certificate setup.
Browser packages use browser APIs and receive scoped credentials from an application backend. They do not load the CLI’s local configuration or host a native agent. In Node.js, @rstreamlabs/runtime owns native tunnel connections; @rstreamlabs/tunnels provides Engine HTTP APIs and @rstreamlabs/rstream provides Control plane APIs.
Make a first connection
The language guides provide installation and a first HTTP service using each runtime’s native server interface. Native SDKs can reuse a project context selected through the CLI workflow. Unattended services can instead receive project-scoped credentials or a provisioned certificate identity.
The agent’s transport and a tunnel’s published protocol are separate choices. Project settings and access policy remain authoritative for both. A language’s support for an application protocol does not imply that every SDK implements the same transport or helper.
Run as an application service
Native runtime objects belong to the application lifecycle, outside individual request handlers. Keep the control channel open while admitting streams, close each accepted or dialed stream, and stop serving before releasing its owners. The Go, Node.js, Python and Java low-level runtimes do not recreate a failed control channel or its tunnels. The application supervises recovery with bounded backoff, stops retries on shutdown and preserves a requested hostname when a stable public address is required. The C++ direct client follows that model; its acceptor interface also offers configurable automatic reconnect.
A tunnel name is a private lookup key, not a reserved public hostname. Recovery creates a new tunnel generation and does not replay application requests. The language guides describe cancellation and stream ownership for their runtime.
Developer login contexts are convenient locally. Services and devices should receive their own restricted project identity rather than a copied personal login context. Project-scoped credentials can be durable; short-lived delegated tokens are intended for immediate handoff and must be obtained again for a later connection attempt. See CLI credential handling and Tokens.
Continue the integration
| Task | Next step |
|---|---|
| Connect application processes privately | Private tunnels |
| Query or automate the platform | API integration |
| Verify lifecycle notifications | Webhooks |
| Scope backend and browser credentials | Fine-grained tokens |
| Start from a complete application | rstream examples |
Repository READMEs introduce each SDK and link to runnable examples. Their deeper guides describe API options, supported configuration and development checks.