Registry / http-networking / untun
library0.1.3jsnpmunverified

untun is a JavaScript/TypeScript utility for creating temporary, publicly accessible tunnels to local HTTP(S) servers using Cloudflare Quick Tunnels. Currently at version 0.1.3, it is in active pre-1.0 development, indicating frequent patch releases with potential API changes. It offers both a convenient CLI for quick usage and a programmatic API for integration into applications. Key differentiators include its tight integration with the Cloudflare `cloudflared` binary, its lightweight nature as part of the `unjs` ecosystem, and first-class TypeScript support. It simplifies exposing local development servers to the internet without manual Cloudflare setup or account requirements, making it ideal for testing webhooks, demos, and collaborative development.

npm install untun
INSTALL
IMPORT
SIG · UNTUN
U
untun
http-networkingjavascriptv0.1.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

startTunnel
import { startTunnel } from 'untun'
const startTunnel = require('untun')
Primary function to initiate a Cloudflare Quick Tunnel. Supports both ESM and CommonJS, but ESM is preferred in modern Node.js environments.
Tunnel
import { type Tunnel } from 'untun'
Type definition for the object returned by `startTunnel`, which typically includes methods like `close()` and properties like `url`. Use `type` keyword for type-only imports.
StartTunnelOptions
import { type StartTunnelOptions } from 'untun'
Type definition for the options object passed to `startTunnel`. Useful for strongly-typed configuration.

Demonstrates how to programmatically start a Cloudflare Quick Tunnel for a local server, including basic error handling and graceful shutdown.

import { startTunnel } from 'untun'; async function main() { console.log('Starting local server...'); // In a real application, you'd start your HTTP server here. // For this example, we'll assume it's running on port 3000. try { console.log('Initiating Cloudflare Quick Tunnel...'); const tunnel = await startTunnel({ port: 3000, // Set to true to automatically accept Cloudflare's Terms of Service for quick testing. // In production or automated environments, consider setting via process.env.UNTUN_ACCEPT_CLOUDFLARE_NOTICE. acceptCloudflareNotice: process.env.UNTUN_ACCEPT_CLOUDFLARE_NOTICE === 'true' }); console.log(`✔ Tunnel ready at: ${tunnel.url}`); console.log('Press Ctrl+C to close the tunnel.'); // Keep the process alive until explicitly closed (e.g., via signal handler) process.on('SIGINT', async () => { console.log('\nClosing tunnel...'); await tunnel.close(); console.log('Tunnel closed. Exiting.'); process.exit(0); }); } catch (error) { console.error('Failed to start tunnel:', error); process.exit(1); } } main();
untun --version
Debug
Known issues
breakinguntun is currently pre-1.0 (v0.1.3), meaning its API surface may undergo breaking changes in minor or even patch versions as it evolves. Users should pin exact versions and review release notes carefully.
fix
Refer to the GitHub releases page for each update; consider using a version locking mechanism (e.g., `npm ci`) and thorough testing before upgrading in production.
affects: >=0.1.0
gotchaTo use untun programmatically or via CLI, you must accept Cloudflare's Terms of Service. This can be done by setting `acceptCloudflareNotice: true` in the options or by setting the `UNTUN_ACCEPT_CLOUDFLARE_NOTICE` environment variable to `true`.
fix
Set `acceptCloudflareNotice: true` in the `startTunnel` options object or define `process.env.UNTUN_ACCEPT_CLOUDFLARE_NOTICE = 'true'` before running untun.
affects: >=0.1.3
gotchauntun internally manages and executes the `cloudflared` binary. Updates to `cloudflared` (as seen in v0.1.3) can introduce new behaviors, requirements, or even breaking changes to the underlying tunnel mechanism, which untun abstracts.
fix
Monitor untun's release notes for `cloudflared` updates. If encountering unexpected tunnel behavior, check the official `cloudflared` documentation for the version untun is using.
affects: >=0.1.0
gotchaFailing to call `tunnel.close()` on the returned Tunnel object will leave the network tunnel active, potentially consuming resources or maintaining an unwanted public endpoint. Ensure proper cleanup, especially in long-running processes or on application shutdown.
fix
Implement signal handlers (e.g., `process.on('SIGINT', ...)`) to ensure `await tunnel.close()` is called before the application exits.
affects: >=0.1.0
Errors
Common errors & fixes
Error: You must accept Cloudflare Terms of Service to use Quick Tunnels.
The `acceptCloudflareNotice` option was not set to `true`, and the environment variable `UNTUN_ACCEPT_CLOUDFLARE_NOTICE` was not set.
fix
Add `acceptCloudflareNotice: true` to the `startTunnel` options, or set `process.env.UNTUN_ACCEPT_CLOUDFLARE_NOTICE = 'true'`.
Error: listen EADDRINUSE: address already in use :::3000
The specified local `port` (e.g., 3000) is already being used by another process on your machine, or your local HTTP server is not running on that port.
fix
Ensure your local server is running on the correct port, or choose an available port for your local server if using `untun`'s `port` option. Verify no other applications are using the target port.
Failed to start tunnel: Error: cloudflared process exited with code 1
The `cloudflared` binary, which untun relies on, failed to execute or encountered an internal error. This could be due to permission issues, corrupted binary download, or specific system configurations.
fix
Check for available system logs. Ensure `untun` has necessary execution permissions. If running in a restricted environment, verify network access for `cloudflared` to download updates or connect to Cloudflare. Try reinstalling `untun` to ensure a fresh `cloudflared` binary download.
Upgrade
Version history
0.1.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
13 hits · last 30 days
node
12
OpenAI (training)
1
Resources
untun — npm install untun · libregistry