getxpos

Go SDK for XPOS — instant public URLs via SSH tunnels. Minimal dependencies.

Features

• Minimal dependencies — standard library plus golang.org/x/crypto (SSH host-key verification)
• CLI + programmatic API — use from terminal or embed in your tooling
• HTTP & TCP tunnels — expose web apps or any TCP service
• Anonymous or authenticated — works instantly, tokens unlock more features
• Reserved subdomains & custom domains — with Pro/Business plans
• Context-aware — idiomatic Go with context.Context support

Quick Start

# Install CLI
go install github.com/getxpos/go/cmd/xpos@latest

# Run (anonymous tunnel, random subdomain, 3hr expiry)
xpos --port 3000

Installation

# CLI tool
go install github.com/getxpos/go/cmd/xpos@latest

# Library (add to your Go project)
go get github.com/getxpos/go

Authentication

Get a token from xpos.dev/dashboard/tokens, then either:

# Pass directly
xpos --port 3000 --token tk_xxx

# Or set environment variable
export XPOS_TOKEN=tk_xxx
xpos --port 3000

CLI Usage

# Anonymous tunnel (random subdomain, 3hr expiry)
xpos --port 3000

# Authenticated (random subdomain, 10hr expiry)
xpos --port 3000 --token tk_xxx

# Reserved subdomain (Pro+)
xpos --port 3000 --token tk_xxx --subdomain myapp

# Custom domain (Business)
xpos --port 8000 --token tk_xxx --domain tunnel.example.com

# Port-based TCP tunnel (Pro+)
xpos --port 5432 --token tk_xxx --mode tcp

CLI Options

Option	Description	Default
--port <port>	Local port to expose	(required)
--host <host>	Local host to forward	127.0.0.1
--token <token>	Auth token (or XPOS_TOKEN env)	—
--subdomain <name>	Reserved subdomain (requires token)	—
--domain <domain>	Custom domain (requires token)	—
--mode <mode>	http or tcp	http
--server <host>	SSH server hostname	go.xpos.dev
-h, --help	Show help	—
-v, --version	Show version	—

Programmatic API

import xpos "github.com/getxpos/go/xpos"

// HTTP tunnel (convenience function)
tunnel, err := xpos.Connect(ctx, xpos.WithPort(3000), xpos.WithToken("tk_xxx"))
if err != nil {
    log.Fatal(err)
}
fmt.Println(tunnel.URL)       // https://abc.xpos.to
fmt.Println(tunnel.ExpiresAt) // 2026-03-28T10:30:45Z
defer tunnel.Close()
<-tunnel.Done()

TCP Tunnel

tcp, err := xpos.Connect(ctx,
    xpos.WithPort(5432),
    xpos.WithToken("tk_xxx"),
    xpos.WithMode("tcp"),
)
fmt.Println(tcp.URL) // 1.2.3.4:54321
defer tcp.Close()

Manual Control

For more control, use NewTunnel + Start separately:

t, err := xpos.NewTunnel(
    xpos.WithPort(3000),
    xpos.WithToken("tk_xxx"),
    xpos.WithSubdomain("myapp"),
    xpos.WithOnConnect(func(url, expiresAt string) {
        fmt.Printf("Connected: %s\n", url)
    }),
    xpos.WithOnClose(func(exitCode int) {
        fmt.Printf("Tunnel closed (exit %d)\n", exitCode)
    }),
)
if err != nil {
    log.Fatal(err)
}

if err := t.Start(ctx); err != nil {
    log.Fatal(err)
}
defer t.Close()
<-t.Done()

Options

Option	Type	Description
WithPort(int)	int	Local port to expose (required)
WithHost(string)	string	Local host (default: "127.0.0.1")
WithToken(string)	string	Auth token (or reads XPOS_TOKEN env)
WithSubdomain(string)	string	Reserved subdomain
WithDomain(string)	string	Custom domain
WithMode(string)	string	"http" or "tcp" (default: "http")
WithServer(string)	string	SSH server (default: "go.xpos.dev")
WithSSHPort(int)	int	SSH port (default: 443)
WithConnectTimeout(time.Duration)	time.Duration	Connect timeout (default: 15s)
WithOnConnect(func)	func(url, expiresAt string)	Called on connect
WithOnOutput(func)	func(text string)	Called with raw SSH output
WithOnClose(func)	func(exitCode int)	Called on disconnect

Tunnel Methods

Method	Description
Start(ctx)	Start the tunnel (blocks until connected)
Close()	Gracefully close the tunnel
Wait()	Block until the tunnel closes
Done()	Returns a channel closed when tunnel ends

Requirements

• Go >= 1.18
• SSH client in PATH (ssh command — comes pre-installed on macOS, Linux, and Windows 10+)

Security

The auth token is written to a per-process SSH config file (mode 0600, inside a private 0700 temp directory) as the User directive, and the SDK spawns ssh -F <config> xpos — so the token is not placed on the ssh command line and does not appear in ps, /proc/<pid>/cmdline, or shell history. The config file is removed when the tunnel exits.

To minimize exposure:

• Provide the token via the XPOS_TOKEN environment variable rather than hard-coding it in source. This keeps it out of source control and shell history (the SDK reads XPOS_TOKEN automatically when no WithToken option is set).
• Rotate tokens regularly and revoke any token you suspect was exposed — manage tokens at xpos.dev/dashboard/tokens.
• Avoid running on shared multi-user hosts where untrusted local users can inspect process state.

Residual exposure: the token lives in that 0600 temp config file for the tunnel's lifetime, and — when supplied via XPOS_TOKEN — in this process's environment (/proc/<pid>/environ, readable only by the same UID or root) — both far tighter than the ps-readable argv of older designs.

Troubleshooting

"SSH not found" — Install OpenSSH. On Windows: Settings > Apps > Optional Features > OpenSSH Client.

Connection timeout — Check your firewall allows outbound connections on port 443.

"subdomain requires a token" — Reserved subdomains need a Pro plan. Get a token from your dashboard.

Links

• Website
• Dashboard
• GitHub

License

MIT