Embeddable Go SDK Go

Embed an NFLTR tunnel agent directly in your Go application. No subprocess, no sidecar, no shell exec — just agent.New(), Connect(ctx), and your service is accessible over the internet.

Architecture

The SDK wraps the same gRPC transport used by the nfltr CLI into a clean Go API. Your application creates an agent instance, configures routes and labels, then calls Connect(). The tunnel runs in the background as goroutines inside your process.

Quick Start

Install

go get github.com/onpremlink/onpremlink/pkg/agent

Basic Usage

package main

import (
    "context"
    "log"
    "os"

    "github.com/onpremlink/onpremlink/pkg/agent"
)

func main() {
    a := agent.New(agent.Config{
        ServerAddr: "grpc.nfltr.xyz:443",
        AgentID:    "my-service-01",
        APIKey:     os.Getenv("NFLTR_API_KEY"),
        TLS:        true,
        Routes: []agent.Route{
            {Backend: "http://localhost:8080"},
        },
    })

    ctx := context.Background()
    if err := a.Connect(ctx); err != nil {
        log.Fatal(err)
    }
    log.Println("tunnel active, agent-id:", a.AgentID())

    // Block until context is cancelled or Close() is called
    <-a.Done()
}

Configuration Options

Multi-Route

a := agent.New(agent.Config{
    ServerAddr: "grpc.nfltr.xyz:443",
    AgentID:    "my-app",
    APIKey:     apiKey,
    TLS:        true,
    Routes: []agent.Route{
        {Backend: "http://localhost:5173"},          // default
        {Prefix: "api", Backend: "http://localhost:8080"},
        {Prefix: "ws", Backend: "http://localhost:4000"},
    },
})

Fleet Labels

a := agent.New(agent.Config{
    ServerAddr: "grpc.nfltr.xyz:443",
    AgentID:    "client-acme-prod",
    APIKey:     apiKey,
    TLS:        true,
    Labels:     map[string]string{
        "client": "acme",
        "env":    "prod",
        "region": "us-east",
    },
    Routes: []agent.Route{
        {Backend: "http://localhost:8080"},
    },
})

mTLS Authentication

a := agent.New(agent.Config{
    ServerAddr: "grpc.yourco.com:443",
    AgentID:    "edge-node-01",
    TLSConfig:  &tls.Config{
        Certificates: []tls.Certificate{cert},
        RootCAs:      caCertPool,
    },
    Routes: []agent.Route{
        {Backend: "http://localhost:8080"},
    },
})

Lifecycle Management

// Connect returns immediately after the tunnel is established
err := a.Connect(ctx)

// AgentID returns the full agent identifier
id := a.AgentID() // "alice.my-service-01"

// Done returns a channel that closes when the agent disconnects
<-a.Done()

// Close gracefully shuts down the tunnel
a.Close()

The SDK handles automatic reconnection on network interruptions. Your application doesn't need to manage retries.

Use Cases

• SaaS product with on-premise agents — Ship the SDK embedded in your Go service. Each customer deployment connects back to your cloud.
• IoT gateway — Embed the agent in your edge gateway application. No separate binary to distribute or manage.
• Kubernetes operator — The operator embeds the agent to establish tunnels for each managed resource.
• CI/CD pipeline — Programmatically create and destroy tunnels during test runs.