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

# Obtain the Go SDK module from your NFLTR account team, then:
go get nfltr.xyz/sdk/agent@v1

Basic Usage

package main

import (
    "context"
    "log"
    "os"

    "nfltr.xyz/sdk/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 edge agents — Ship the SDK embedded in your Go service. Each customer deployment connects back to the hosted relay at nfltr.xyz.
• 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.