Tunnels

Expose your local development server to the internet with a secure public HTTPS URL

What are Tunnels?

DeployBase Tunnels let you expose a local development server (running on your machine) to the internet via a public HTTPS URL like https://tunnel-a1b2c3d4.deploybase.io.

This is useful for testing webhooks, sharing work-in-progress with clients, mobile device testing, or any scenario where your local server needs to be accessible from the internet.

Quick Start

Step 1: Create a Tunnel

Go to your hosting account in the dashboard, open the Applications tab, and click "Create Tunnel". Set an optional label and port number (default 3000). You'll receive a tunnel token — copy it immediately, it's shown only once.

Or create via API — see the API Reference below.

Step 2: Start Your Local Server

Make sure your local app is running on the port you specified:

# Example: Node.js app on port 3000
node server.js

Step 3: Run the Tunnel CLI

Connect your local server to the public URL:

npx deploybase-tunnel --token YOUR_TOKEN --port 3000

Once connected, you'll see your public URL in the terminal output.

Step 4: Access Your App

Your app is now accessible at https://tunnel-XXXX.deploybase.io. Share this URL with anyone who needs to access your local server.

CLI Reference

Usage

npx deploybase-tunnel --token <TOKEN> --port <PORT> [--host <HOST>]

Flag	Required	Description
`--token`	Yes	Your tunnel authentication token
`--port`	Yes	Local port your server is running on
`--host`	No	Local hostname (default: `localhost`)

Example Output

Illustration — sample data

$ npx deploybase-tunnel --token dbt_a1b2c3... --port 3000

  DeployBase Tunnel
  Connected! Your app is live at:
  https://tunnel-a1b2c3d4.deploybase.io

  Forwarding requests to localhost:3000
  Ready for connections...

  GET  /           200  45ms
  POST /api/webhook 200  120ms

API Reference

You can create and manage tunnels programmatically using the REST API. All endpoints require authentication via an API token.

Authentication

Generate an API token from Dashboard > Settings > Security. Then pass it in the Authorization header:

Authorization: Bearer dk_your_api_token

The token is shown only once when generated. Store it securely.

Get Your Hosting Account ID

You need a hosting account ID to create a tunnel.

curl https://deploybase.io/api/hosting/accounts \
  -H "Authorization: Bearer dk_your_api_token"

Response includes an array of accounts. Copy the id of the account you want to use.

POST

/api/tunnels

Create a new tunnel. Returns the tunnel token (shown only once).

curl -X POST https://deploybase.io/api/tunnels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dk_your_api_token" \
  -d '{
    "hostingAccountId": "YOUR_ACCOUNT_ID",
    "label": "My Dev Server",
    "localPort": 3000
  }'

Response:

{
  "tunnel": {
    "id": "clxx...",
    "subdomain": "tunnel-a1b2c3d4",
    "label": "My Dev Server",
    "localPort": 3000,
    "token": "dbt_abc123..."
  }
}

Important: The token is only returned at creation. Copy it immediately — you cannot retrieve it later.

GET

/api/tunnels

List all your tunnels. Optionally filter by account.

curl "https://deploybase.io/api/tunnels?accountId=YOUR_ACCOUNT_ID" \
  -H "Authorization: Bearer dk_your_api_token"

DELETE

/api/tunnels/:id

Delete a tunnel.

curl -X DELETE https://deploybase.io/api/tunnels/TUNNEL_ID \
  -H "Authorization: Bearer dk_your_api_token"

PATCH

/api/tunnels/:id

Update tunnel label or port.

curl -X PATCH https://deploybase.io/api/tunnels/TUNNEL_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer dk_your_api_token" \
  -d '{"label": "New Label", "localPort": 8080}'

Complete Example (API + CLI)

Here's the full flow to create and connect a tunnel using only the command line. First, generate an API token from Dashboard > Settings > Security.

# Set your API token (generated from Dashboard > Settings > Security)
TOKEN="dk_your_api_token"

# 1. List your hosting accounts to get the account ID
curl https://deploybase.io/api/hosting/accounts \
  -H "Authorization: Bearer $TOKEN"

# 2. Create a tunnel (save the tunnel token from the response!)
curl -X POST https://deploybase.io/api/tunnels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"hostingAccountId": "ACCOUNT_ID", "label": "Dev Server", "localPort": 3000}'

# 3. Start your local server
node server.js &

# 4. Connect the tunnel
npx deploybase-tunnel --token TUNNEL_TOKEN_FROM_STEP_2 --port 3000

Limits & Notes

-Maximum 5 tunnels per hosting account
-Each tunnel gets a unique subdomain (e.g., tunnel-a1b2c3d4.deploybase.io)
-Tunnel token is shown only once at creation — store it securely
-Only one active connection per tunnel at a time (new connection replaces the old one)
-The CLI auto-reconnects if the connection drops (exponential backoff, max 30s)
-Request timeout: 30 seconds

Back to Documentation