expose-localhost
Expose a local service to the public internet using ngrok. Starts a tunnel, optionally adds OAuth or WAF via Traffic Policy. Handles HTTP services and raw TCP (SSH, RDP, databases). Use when asked to expose, tunnel, share, or make a local service publicly accessible, or to reach a machine that has no public IP. Also covers sharing work-in-progress with a specific person and the dev-server quirks that break a shared preview.
ngrok · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add ngrok/skills --skill expose-localhostAbout this skill
name: expose-localhost description: Expose a local service to the public internet using ngrok. Starts a tunnel, optionally adds OAuth or WAF via Traffic Policy. Handles HTTP services and raw TCP (SSH, RDP, databases). Use when asked to expose, tunnel, share, or make a local service publicly accessible, or to reach a machine that has no public IP. Also covers sharing work-in-progress with a specific person and the dev-server quirks that break a shared preview. license: MIT metadata: author: ngrok version: "2.1" compatibility: Requires ngrok CLI installed and authenticated.
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 (
ngrokcommand available) - Auth token configured (
ngrok config add-authtoken <TOKEN>)
Workflow
Step 1: Pre-flight & Configuration
Silently verify ngrok is ready:
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)
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):
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:
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:
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:
- 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):
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):
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:
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 s