@tunnelapi/sdk

TunnelAPI SDK for programmatic tunnel creation. Create secure SSH, TCP, and HTTP tunnels for IoT devices, embedded systems, and remote access.

Installation

npm install @tunnelapi/sdk

Quick Start

import TunnelAPI from '@tunnelapi/sdk';

// Initialize with your API token
const api = new TunnelAPI({
  token: 'tapi_your_token_here'
});

// Create an HTTP tunnel
const tunnel = await api.createTunnel({
  localPort: 3000,
  name: 'My Web Server'
});

console.log('Public URL:', tunnel.getPublicUrl());
// Output: https://swift-fox-a1b2c3.free-tunnelapi.app

Use Cases

SSH Tunnel for Device Rental (Jetson, IoT)

Perfect for sharing embedded devices like NVIDIA Jetson Nano, TX2, Orin, or any Linux device:

import TunnelAPI from '@tunnelapi/sdk';

const api = new TunnelAPI({ token: process.env.TUNNELAPI_TOKEN });

// Create SSH tunnel for device access
const sshTunnel = await api.createSSHTunnel({
  localPort: 22,
  name: `Device-${sessionId}`
});

// Get the public SSH URL for the user
const sshUrl = sshTunnel.getPublicUrl();
console.log(`SSH Access: ssh user@${sshUrl.replace('https://', '')}`);

// Handle incoming connections
sshTunnel.on('tcp-connect', (connectionId, remoteAddress) => {
  console.log(`New SSH connection from ${remoteAddress}`);
});

// When session ends, close the tunnel
sshTunnel.close();
await api.deleteTunnel(sshTunnel.getInfo().id);

HTTP Tunnel with Request Handling

const tunnel = await api.createTunnel({
  localPort: 8080,
  protocol: 'http'
});

// Handle incoming requests
tunnel.onRequest(async (request) => {
  console.log(`${request.method} ${request.path}`);
  
  // Forward to local server or handle directly
  return {
    statusCode: 200,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ message: 'Hello from tunnel!' })
  };
});

TCP Tunnel for Custom Protocols

const tcpTunnel = await api.createTCPTunnel({
  localPort: 5432, // PostgreSQL
  name: 'Database Tunnel'
});

tcpTunnel.on('tcp-connect', (connId, remoteAddr) => {
  console.log(`TCP connection: ${connId} from ${remoteAddr}`);
});

tcpTunnel.on('tcp-data', (connId, data) => {
  // Forward data to local service
  localSocket.write(data);
});

API Reference

TunnelAPI

Main class for interacting with TunnelAPI.

const api = new TunnelAPI({
  token: string,        // Required: API token (starts with tapi_)
  apiUrl?: string,      // Optional: API URL (default: https://api.tunnelapi.in)
  wsUrl?: string,       // Optional: WebSocket URL (default: wss://tunnel.tunnelapi.in)
  timeout?: number,     // Optional: Request timeout in ms (default: 30000)
  debug?: boolean       // Optional: Enable debug logging
});

Methods

| Method | Description | |--------|-------------| | createTunnel(options) | Create a new tunnel | | createSSHTunnel(options) | Create an SSH/TCP tunnel | | createTCPTunnel(options) | Create a TCP tunnel | | listTunnels(options?) | List all tunnels | | getTunnel(tunnelId) | Get tunnel details | | deleteTunnel(tunnelId) | Delete a tunnel | | getUsage() | Get usage statistics | | closeAll() | Close all active connections |

CreateTunnelOptions

interface CreateTunnelOptions {
  localPort: number;           // Required: Local port to tunnel
  protocol?: string;           // Optional: 'http' | 'https' | 'tcp' | 'ssh' | 'ws'
  subdomain?: string;          // Optional: Custom subdomain (paid tiers)
  name?: string;               // Optional: Tunnel name
  metadata?: object;           // Optional: Custom metadata
  autoConnect?: boolean;       // Optional: Auto-connect WebSocket (default: true)
}

Tunnel Events

tunnel.on('connected', () => {
  console.log('Tunnel connected');
});

tunnel.on('disconnected', (reason) => {
  console.log('Tunnel disconnected:', reason);
});

tunnel.on('request', (request, respond) => {
  respond({
    statusCode: 200,
    headers: {},
    body: 'OK'
  });
});

tunnel.on('error', (error) => {
  console.error('Tunnel error:', error);
});

// TCP/SSH specific events
tunnel.on('tcp-connect', (connectionId, remoteAddress) => {});
tunnel.on('tcp-data', (connectionId, data) => {});
tunnel.on('tcp-close', (connectionId) => {});

Token Management

API tokens can be created and managed from the TunnelAPI dashboard:

1. Go to tunnelapi.in/dashboard/tokens
2. Click "Create Token"
3. Set permissions and expiration
4. Copy the token (shown only once)

Token Scopes

| Scope | Description | |-------|-------------| | tunnels:create | Create new tunnels | | tunnels:read | List and view tunnels | | tunnels:delete | Delete tunnels | | tunnels:manage | Full tunnel management | | usage:read | View usage statistics |

Tier Limits

| Feature | Solo | Team | Enterprise | |---------|------|------|------------| | API Tokens | 3 | 10 | Unlimited | | SDK Tunnels | 5 | 25 | Unlimited | | Custom Subdomains | ✓ | ✓ | ✓ |

Error Handling

try {
  const tunnel = await api.createTunnel({ localPort: 3000 });
} catch (error) {
  if (error.code === 403) {
    console.log('Tunnel limit reached or insufficient permissions');
  } else if (error.code === 401) {
    console.log('Invalid or expired token');
  } else {
    console.log('Error:', error.message);
  }
}

Environment Variables

TUNNELAPI_TOKEN=tapi_your_token_here
TUNNELAPI_URL=https://api.tunnelapi.in  # Optional

const api = new TunnelAPI({
  token: process.env.TUNNELAPI_TOKEN!
});

License

MIT

Support

• Documentation: docs.tunnelapi.in
• Issues: GitHub Issues
• Email: [email protected]