Expose Localhost

Expose a local service to the public internet using ngrok. Optionally add OAuth, OWASP protection, or rate limiting via Traffic Policy.

Prerequisites

ngrok CLI installed (
```
ngrok
```
command available)
Auth token configured (
```
ngrok config add-authtoken <TOKEN>
```
)

Workflow

Step 1: Pre-flight & Configuration

Silently verify ngrok is ready:

bash

ngrok config check

If auth token missing, tell user to run:

ngrok config add-authtoken <TOKEN>

(get token at https://dashboard.ngrok.com/get-started/your-authtoken)

Then ask all questions upfront before doing anything:

Before I expose your service, I need a few details:

1. **Port**: I see your app runs on port 3000. Is that correct?
2. **Domain**: Use your dev domain, or do you have a custom domain?
3. **Access control**: Open access, or require login (Google/GitHub/etc.)?
4. **Save config?**: One-time setup, or save for reuse?

Do NOT mention cloud endpoints, reserved domains, or internal endpoints — those are advanced concepts the user shouldn't need to think about.

Detecting the port: Check

package.json

scripts for

--port

.env

for

PORT=

docker-compose.yml

for port mappings.

Is it even HTTP? If the user says SSH, RDP, a database, or names a port like 22, 3389, 5432, or 3306, this is a raw TCP service — skip to Non-HTTP Services (TCP). The domain and access-control questions above do not apply there.

Domains: Most ngrok accounts have a free static dev domain (e.g.,

something.ngrok-free.dev

). Running

ngrok http PORT

uses it automatically. Users can also provide a custom domain configured in the ngrok dashboard. Some accounts (especially new ones) may not have a dev domain yet — if ngrok fails with

ERR_NGROK_15013

, tell the user: "You don't have a dev domain yet. Claim your free one at https://dashboard.ngrok.com/domains — then we can try again."

If user requests OAuth, also ask: "Should only specific people be able to access it? I can restrict by email address or email domain."

After gathering answers, confirm and get a Y/n before proceeding.

Step 2: Start the Tunnel

No security (simplest)

bash

ngrok http {PORT} &
sleep 3
curl -s http://localhost:4040/api/tunnels | grep -o '"public_url":"[^"]*"' | head -1

With a specific domain, add

--url https://{DOMAIN}

With security (Traffic Policy)

Create the traffic policy file first, then start ngrok with it.

OAuth-only (default when user requests auth):

yaml

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google

Replace

google

with the chosen provider (google, github, microsoft, gitlab, linkedin, twitch).

If the user requests OAuth, default to OAuth-only. Do NOT add OWASP or rate limiting unless explicitly asked — OAuth already blocks unauthenticated access.

OAuth with email restriction — use a separate rule with a CEL expression to deny non-matching emails. Do NOT add an

allow

field to the OAuth action.

Single email:

yaml

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google
  - expressions:
      - "actions.ngrok.oauth.identity.email != 'user@example.com'"
    actions:
      - type: deny
        config:
          status_code: 403

Email domain:

yaml

on_http_request:
  - actions:
      - type: oauth
        config:
          provider: google
  - expressions:
      - "!actions.ngrok.oauth.identity.email.endsWith('@your-company.com')"
    actions:
      - type: deny
        config:
          status_code: 403

Multiple emails — name the identity explicitly on the left of

in

yaml

  - expressions:
      - "!(actions.ngrok.oauth.identity.email in ['a@x.com', 'b@x.com'])"
    actions:
      - type: deny
        config:
          status_code: 403

Shared secret (when the person won't log in with an IdP — an external client, a reviewer without a company account):

yaml

on_http_request:
  - actions:
      - type: basic-auth
        config:
          credentials:
            - "reviewer:{PASSWORD}"

Hand them the URL and the password over a channel you already trust. If they have a stable IP,

restrict-ips

is an alternative with nothing to share.

Open-access hardening (no auth, but wants protection):

yaml

on_http_request:
  - actions:
      - type: rate-limit
        config:
          name: default-rate-limit
          algorithm: sliding_window
          capacity: 200
          rate: "60s"
          bucket_key:
            - conn.client_ip
      - type: owasp-crs-request
        config:
          on_error: halt

on_http_response:
  - actions:
      - type: owasp-crs-response
        config:
          on_error: halt

After writing the policy file, start ngrok:

bash

ngrok http {PORT} --traffic-policy-file .ngrok/traffic-policy.yml &
sleep 3
curl -s http://localhost:4040/api/tunnels | grep -o '"public_url":"[^"]*"' | head -1

Add

--url https://{DOMAIN}

if using a specific domain.

Sharing a dev server? Vite, Next, and webpack reject requests whose Host header isn't localhost, and their hot-reload websockets need the ngrok domain allowed. Set this up before handing over the URL — see

references/TROUBLESHOOTING.md

Step 3: Handle Errors

If a traffic policy action fails due to plan limitations:

Tell the user which specific action requires an upgrade
Offer to remove that action from the policy and retry
Do NOT suggest switching to cloud endpoints as a workaround

Step 4: Persistent Configuration (If Requested)

Save these files to the project:

.ngrok/traffic-policy.yml
— the policy (if security was configured)
.ngrok/expose.sh
:

bash

#!/bin/bash
set -e
echo "Your service will be at: https://{DOMAIN}"
ngrok http {PORT} --url https://{DOMAIN} --traffic-policy-file .ngrok/traffic-policy.yml

Omit

--traffic-policy-file

if no policy. Omit

--url

if no specific domain.

Optionally add to

package.json

json

{ "scripts": { "tunnel": "bash .ngrok/expose.sh" } }

Teardown

bash

pkill ngrok

Non-HTTP Services (TCP)

For SSH, RDP, or a database, use

ngrok tcp

instead of

ngrok http

bash

ngrok tcp {PORT} &
sleep 3
curl -s http://localhost:4040/api/tunnels | grep -o '"public_url":"[^"]*"' | head -1

ngrok returns an address like

tcp://1.tcp.ngrok.io:12345

. The host and port are used separately by the client:

bash

# local sshd on port 22, reached through the address above
ssh -p 12345 {USER}@1.tcp.ngrok.io

Common ports: SSH

, RDP

, PostgreSQL

, MySQL

The address changes on every restart. For one that persists, reserve it first. ngrok assigns the hostname and port — unlike domains, you cannot choose them:

bash

ngrok api reserved-addrs create --description "SSH for {NAME}" --region us
ngrok tcp {PORT} --url tcp://{ADDR}

Reserved TCP addresses need a paid plan and keep billing until deleted.

Access control is different here. OAuth and OWASP are HTTP-only and will not work. TCP policies run in the

on_tcp_connect

phase, where

restrict-ips

is the usual control:

yaml

on_tcp_connect:
  - actions:
      - type: restrict-ips
        config:
          enforce: true
          allow:
            - 203.0.113.0/24

Attach it the same way:

ngrok tcp {PORT} --traffic-policy-file .ngrok/traffic-policy.yml

Cloud Endpoints (Advanced)

Only use if the user explicitly needs a URL that persists after the agent stops (e.g., webhooks, long-lived integrations).

Requires the ngrok MCP server or an API key. If the user manages ngrok as code, add the endpoint there instead. If not, and the MCP server is connected, use it and do not ask for an API key:

gw_reserve_domain

and

gw_create_cloud_endpoint

replace steps 1 and 2, and

delete_resource

replaces step 4. Otherwise the user sets an API key with

ngrok config add-api-key <KEY>

(from https://dashboard.ngrok.com/api-keys). See

ngrok-surfaces

for the order to pick in.

Reserve domain:

ngrok api reserved-domains create --domain "{DOMAIN}"

Create cloud endpoint with a traffic policy that includes
```
forward-internal
```
as the last action:

bash

ngrok api endpoints create --url "https://{DOMAIN}" --bindings public --traffic-policy "$(cat .ngrok/traffic-policy.yml)"

The traffic policy must end with:

yaml

- type: forward-internal
  config:
    url: https://{NAME}.internal

Start the internal agent:

ngrok http {PORT} --url https://{NAME}.internal

Teardown:

ngrok api endpoints delete {ENDPOINT_ID}

Related Skills

This skill covers giving a service a public URL. Neighbouring jobs have their own skills — hand off rather than reimplementing them here:

Auth, rate limits, IP rules, or a maintenance page in general —
```
secure-endpoint
```
. (Sharing a preview with one named person is handled here, in Step 2.)
It should receive webhooks —
```
receive-webhooks
```
verifies provider signatures at the edge and can keep the receiver off the public internet.
It is an MCP server —
```
run-mcp-gateway
```
handles per-provider credentials.
One endpoint per sandbox, tenant, or device, created by a controlplane —
```
provision-sandbox-access
```
.
Something is broken (
```
ERR_NGROK_*
```
, a 400 through the URL but not on localhost) —
```
troubleshoot-ngrok
```
.
Setup or auth problems —
```
ngrok-setup
```
.

For the underlying model — endpoint types, HTTP vs TCP, and the full Traffic Policy action set — see

ngrok-engine

. For applying config on a surface other than the CLI (SDKs, REST API, Terraform, Kubernetes), see

ngrok-surfaces

expose-localhost

NPX Install

Tags

SKILL.md Content

Expose Localhost

Prerequisites

Workflow

Step 1: Pre-flight & Configuration

Step 2: Start the Tunnel

No security (simplest)

With security (Traffic Policy)

Step 3: Handle Errors

Step 4: Persistent Configuration (If Requested)

Teardown

Non-HTTP Services (TCP)

Cloud Endpoints (Advanced)

Related Skills