stacks-tunnel

name	stacks-tunnel
description	Use when setting up tunnels in Stacks — local development tunnels for webhook testing, custom cloud tunnel deployment to AWS EC2, tunnel event callbacks (onConnect, onRequest, onResponse, onError), subdomain configuration, or the buddy share command. Covers @stacksjs/tunnel.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript
allowed-tools	Read Edit Write Bash Grep Glob

Stacks Tunnel

Local and cloud-deployed development tunnels for exposing local servers.

Key Paths

• Core package: storage/framework/core/tunnel/src/
• External tool: ~/Code/Tools/localtunnels/

Local Tunnel (Quick)

import { createLocalTunnel } from '@stacksjs/tunnel'

const url = await createLocalTunnel(3000)
// Returns: 'https://abc123.loca.lt'
console.log(`Share this URL: ${url}`)

Advanced Local Tunnel

import { localTunnel } from '@stacksjs/tunnel'

const tunnel = await localTunnel({
  port: 3000,                          // required
  server: 'https://localtunnel.me',   // tunnel server
  subdomain: 'my-app',                // request specific subdomain
  verbose: true,
  timeout: 30000,                      // connection timeout (ms)
  maxReconnectAttempts: 5,

  // Event callbacks
  onConnect: (url) => {
    console.log(`Tunnel connected: ${url}`)
  },
  onRequest: (info) => {
    console.log(`Request: ${info.method} ${info.path}`)
  },
  onResponse: (info) => {
    console.log(`Response: ${info.status}`)
  },
  onError: (error) => {
    console.error('Tunnel error:', error)
  },
  :  {
    .()
  }
})


.(tunnel.)          
.(tunnel.)   


tunnel.()

Cloud Tunnel Deployment (AWS)

import { deployTunnelServer, destroyTunnelServer } from '@stacksjs/tunnel'

// Deploy custom tunnel server to EC2
await deployTunnelServer({
  region: 'us-east-1',
  instanceType: 't3.micro',
  domain: 'tunnel.myapp.com'
})

// Tear down
await destroyTunnelServer({
  region: 'us-east-1'
})

CLI Command

buddy share              # start tunnel for dev server

TunnelOptions Interface

interface TunnelOptions {
  port: number                        // local port to tunnel
  server?: string                     // tunnel relay server URL
  subdomain?: string                  // requested subdomain
  verbose?: boolean                   // debug output
  timeout?: number                    // connection timeout (ms)
  maxReconnectAttempts?: number       // retry limit

  onConnect?: (url: string) => void
  onRequest?: (info: RequestInfo) => void
  onResponse?: (info: ResponseInfo) => void
  onError?: (error: Error) => void
  onReconnecting?: (attempt: number) => void
}

interface LocalTunnel {
  url: string                         
  :                    
  :                
  :                     
}

Gotchas

• Tunnels are for development only — not production use
• createLocalTunnel() is the simple version — returns just the URL
• localTunnel() is the full version with callbacks and control
• Cloud deployment creates an EC2 instance — incurs AWS costs
• Tunnel URLs are temporary — change between sessions unless subdomain is configured
• Ensure dev server is running before starting the tunnel
• maxReconnectAttempts prevents infinite reconnection loops
• The underlying tool is from ~/Code/Tools/localtunnels/
• buddy share wraps createLocalTunnel() for the configured dev port