ngrokd-go

A Go SDK for connecting to remote services via ngrok's private endpoints. Embed this library directly in your Go application instead of running the ngrok daemon.

Installation

go get github.com/ngrok-oss/ngrokd-go

Two Dialers

Dialer

Simple dialer that uses an existing certificate. Auto-loads from ~/.ngrokd-go/certs if no cert provided.

// Auto-load cert from default location
dialer, err := ngrokd.Dialer(ngrokd.DirectConfig{})

// Or provide cert explicitly
cert, _ := tls.LoadX509KeyPair("tls.crt", "tls.key")
dialer, err := ngrokd.Dialer(ngrokd.DirectConfig{
    Cert: cert,
})

// Use with http.Client
client := &http.Client{
    Transport: &http.Transport{DialContext: dialer.DialContext},
}
resp, _ := client.Get("http://my-service.namespace:8080")

DiscoveryDialer

Provisions certificates via API and provides endpoint visibility.

dialer, err := ngrokd.DiscoveryDialer(ctx, ngrokd.Config{
    APIKey: os.Getenv("NGROK_API_KEY"),
})

// List available endpoints
endpoints, _ := dialer.Endpoints(ctx)
for _, ep := range endpoints {
    fmt.Println(ep.URL)
}

// Dial like normal
client := &http.Client{
    Transport: &http.Transport{DialContext: dialer.DialContext},
}

Workflow

1. First time: Use DiscoveryDialer with API key to provision certificate (saved to ~/.ngrokd-go/certs)
2. After that: Use Dialer without API key—auto-loads saved certificate

// One-time provisioning
d, _ := ngrokd.DiscoveryDialer(ctx, ngrokd.Config{APIKey: "..."})
// Cert is now saved to ~/.ngrokd-go/certs

// Later, no API key needed
d, _ := ngrokd.Dialer(ngrokd.DirectConfig{})

Configuration

DirectConfig (for Dialer)

ngrokd.DirectConfig{
    Cert:      tls.Certificate{},  // Optional: explicit cert
    CertStore: ngrokd.NewFileStore("/custom/path"),  // Optional: custom storage
}

Config (for DiscoveryDialer)

ngrokd.Config{
    APIKey:            "your-api-key",  // Required
    EndpointSelectors: []string{"true"},  // CEL expressions to filter endpoints
}

Certificate Storage

Certificates are stored to avoid re-provisioning:

• FileStore (default) — ~/.ngrokd-go/certs
• MemoryStore — ephemeral, for Lambda/Fargate
• Custom — implement CertStore interface

Examples

See examples/ for complete demos.

License

MIT