getxpos

Node.js SDK for XPOS — instant public URLs via SSH tunnels. Zero dependencies.

Features

• Zero dependencies — uses only Node.js built-ins
• 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

Quick Start

# One-off (no install needed)
npx getxpos --port 3000

# Or install globally
npm install -g getxpos
xpos --port 3000

Installation

# Global (recommended for CLI usage)
npm install -g getxpos

# Project dependency (for programmatic API)
npm install getxpos --save-dev

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
--ssh-port <port>	SSH server port (1-65535)	443
-h, --help	Show help	—
-v, --version	Show version	—

Programmatic API

import { xpos } from 'getxpos';

// HTTP tunnel
const tunnel = await xpos.connect({ port: 3000, token: 'tk_xxx' });
console.log(tunnel.url);        // https://abc.xpos.to
console.log(tunnel.expiresAt);  // 2026-03-28T10:30:45Z
tunnel.close();

// Port-based TCP tunnel
const tcp = await xpos.connect({ port: 5432, token: 'tk_xxx', mode: 'tcp' });
console.log(tcp.url);           // myapp.xpos.to:54321
tcp.close();

Named imports

import { connect, XposTunnel } from 'getxpos';

const tunnel = await connect({ port: 3000 });
console.log(tunnel.url);
tunnel.close();

Events

const tunnel = new XposTunnel({ port: 3000 });

tunnel.on('connect', ({ url, expiresAt }) => {
  console.log(`Connected: ${url}`);
});

tunnel.on('output', (text) => {
  // Raw SSH output
});

tunnel.on('close', ({ code }) => {
  console.log('Tunnel closed');
});

await tunnel.start();

Options

Option	Type	Description
port	number	Local port to expose (required)
host	string	Local host (default: "127.0.0.1")
token	string	Auth token (or reads XPOS_TOKEN env)
subdomain	string	Reserved subdomain
domain	string	Custom domain
mode	string	"http" or "tcp" (default: "http")
server	string	SSH server (default: "go.xpos.dev")

Requirements

• Node.js >= 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 token is not 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