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.
Local and cloud-deployed development tunnels for exposing local servers.
storage/framework/core/tunnel/src/import { createLocalTunnel } from '@stacksjs/tunnel'
const url = await createLocalTunnel(3000)
// Returns: 'https://abc123.loca.lt'
console.log(`Share this URL: ${url}`)
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)
},
onReconnecting: (attempt) => {
console.log(`Reconnecting... attempt ${attempt}`)
}
})
// Access tunnel info
console.log(tunnel.url) // public URL
console.log(tunnel.subdomain) // assigned subdomain
// Close tunnel
tunnel.close()
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'
})
buddy share # start tunnel for dev server
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 // public tunnel URL
subdomain: string // assigned subdomain
client: TunnelClient // underlying client
close: () => void // close tunnel
}
createLocalTunnel() is the simple version — returns just the URLlocalTunnel() is the full version with callbacks and controlmaxReconnectAttempts prevents infinite reconnection loopsbuddy share wraps createLocalTunnel() for the configured dev port