# InstaTunnel

InstaTunnel is a secure localhost tunnel for developers who want a fast ngrok alternative.

It helps you expose local apps, APIs, webhook endpoints, and MCP services over HTTPS in seconds.

## Language support

- This npm README stays in English for maximum npm search/discoverability.
- The CLI supports language selection:
  - `--lang en|es|de|ja|fr`
  - `INSTATUNNEL_LANG=en|es|de|ja|fr`
- Localized docs:
  - English: https://instatunnel.my/docs
  - Spanish: https://instatunnel.my/es/docs
  - German: https://instatunnel.my/de/docs
  - Japanese: https://instatunnel.my/ja/docs
  - French: https://instatunnel.my/fr/docs

## Why developers choose InstaTunnel

- Fast setup: tunnel your local app with one command
- Custom subdomains: create memorable URLs on `instatunnel.my`
- Dashboard analytics: inspect traffic and usage
- Pro features: custom domains and MCP endpoint tunnels (beta)
- MCP transport v2 streaming support for long-running responses
- MCP security controls: staged token header + stricter MCP rate limits
- Built for daily dev workflows: demos, QA, webhooks, mobile testing

## InstaTunnel vs ngrok

If you are searching for:
- ngrok alternative
- localhost tunnel alternative
- free tunnel for webhook testing
- custom subdomain tunneling tool

InstaTunnel is designed for the same core use case with a simpler setup and strong defaults.

## Install

```bash
npm install -g instatunnel
```

## Quick start

```bash
# Auto-detect your local app
instatunnel

# Tunnel a specific local port
instatunnel 3000

# Use a custom subdomain
instatunnel 3000 --subdomain myapp

# Region flag (single-region deployment currently supports only us)
instatunnel 3000 --region us
```

## Webhook helper commands

```bash
# Generate provider setup commands + dashboard fields
instatunnel webhook init --provider stripe --port 4242 --path /webhooks/stripe

# Validate secret env var is set before signature checks
instatunnel webhook verify --provider github --secret-env GITHUB_WEBHOOK_SECRET

# Show test-event flow (and optional runnable flow for Stripe)
instatunnel webhook test --provider stripe
instatunnel webhook test --provider stripe --run
```

Supported providers:
- stripe
- github
- shopify
- twilio
- paypal

Step-by-step provider guides:
- https://instatunnel.my/docs/webhooks/stripe
- https://instatunnel.my/docs/webhooks/github
- https://instatunnel.my/docs/webhooks/shopify
- https://instatunnel.my/docs/webhooks/twilio
- https://instatunnel.my/docs/webhooks/paypal
- Localized webhook hubs:
  - https://instatunnel.my/es/docs/webhooks
  - https://instatunnel.my/de/docs/webhooks
  - https://instatunnel.my/ja/docs/webhooks
  - https://instatunnel.my/fr/docs/webhooks

## MCP tunnel support (Pro and Business)

```bash
# New users: start auth flow (verification email)
instatunnel auth login -e you@example.com

# Existing users: save API key locally
instatunnel auth set-key "it_your_api_key"

# Show saved key (masked by default)
instatunnel auth show-key

# Reveal full key + copy to clipboard
instatunnel auth show-key --reveal --copy

# PowerShell copy helper (Windows)
Set-Clipboard "it_your_api_key"

# Save directly from clipboard (Windows PowerShell)
instatunnel auth set-key "$(Get-Clipboard)"

# macOS copy helper
pbpaste | xargs -I {} instatunnel auth set-key "{}"

# Linux copy helper (xclip)
xclip -o -selection clipboard | xargs -I {} instatunnel auth set-key "{}"

# MCP tunnel (default transport v1)
instatunnel 8787 --mcp

# MCP tunnel with streaming transport v2
instatunnel 8787 --mcp --transport v2
```

Transport guidance:
- `v1` is default and most compatible. Use it for standard HTTP/webhook forwarding.
- `v2` is for streaming behavior (MCP Streamable HTTP, long-lived tool responses, server push-like flows).
- If unsure, start with `v1` and switch to `v2` only for streaming MCP clients.
- `--transport v2` requires newer InstaTunnel CLI versions (`1.1.7+`). Update with:
  `npm install -g instatunnel@latest`

### MCP URL and IDE JSON config (easy setup)

1. Run MCP tunnel with a fixed subdomain:

```bash
# Start with v1 default (most compatible)
instatunnel 8787 --mcp --subdomain mymcp

# Switch to v2 only when streaming behavior is needed
instatunnel 8787 --mcp --transport v2 --subdomain mymcp
```

2. Copy the generated tunnel URL from CLI output:
`https://mymcp.instatunnel.my`
3. Append `/mcp` to get the endpoint your AI tool should call:
`https://mymcp.instatunnel.my/mcp`
4. Create a token for your MCP server:

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

5. Configure your MCP server to require:
`Authorization: Bearer <your_token>`
6. Paste this into your IDE MCP settings:

```json
{
  "mcpServers": {
    "instatunnel-remote": {
      "type": "streamable-http",
      "url": "https://YOUR-SUBDOMAIN.instatunnel.my/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_TOKEN"
      }
    }
  }
}
```

Fill values:
- `YOUR-SUBDOMAIN`: the subdomain used in `--subdomain`.
- `YOUR_MCP_TOKEN`: the same token expected by your MCP server.

If you do not enforce auth on your MCP server, remove `headers`.

Optional staged MCP token header (`X-InstaTunnel-MCP-Token`):

```bash
export INSTATUNNEL_MCP_TOKEN="your-shared-secret"
instatunnel 8787 --mcp --transport v2
```

MCP notes:
- v1 stays default for compatibility and standard forwarding.
- v2 is recommended for streaming MCP responses.
- If unsure, start with v1.
- `--transport v2` requires CLI `1.1.7+` (run `npm install -g instatunnel@latest`).
- MCP traffic has dedicated protective limits.

## CLI diagnostics (doctor)

```bash
# Run full CLI health checks
instatunnel doctor

# Include MCP readiness checks
instatunnel doctor --mcp

# Check if local app is listening before tunneling
instatunnel doctor --port 3000

# JSON output for scripts/CI
instatunnel doctor --json
```

## CLI analytics and logs

```bash
# Usage stats (last 30 days, requires API key)
instatunnel --stats

# Live request-log polling (requires Pro/Business for request logs)
instatunnel --logs
```

## Flag reference

```text
--subdomain, -s    Set tunnel subdomain
--domain, -d       Use custom domain (Pro/Business)
--region, -r       Region (current deployment: us)
--password         Password protect tunnel
--auth             Basic auth username:password
--mcp              MCP mode (Pro/Business)
--transport        v1 (default) or v2 (streaming)
--qr               Show QR code
--list             List active tunnels (auth)
--kill             Stop tunnel by subdomain (auth)
--logs             Poll live request logs (Pro/Business)
--stats            Show real usage summary (auth)
--share            Print social sharing templates
--react/--next/--laravel  Framework shortcuts
```

## Release notes

Latest release: `1.1.20`

- Aligned in-app release notes with CLI update notices using shared latest-version payload.
- Added release-notes link in CLI update prompts:
  - `https://instatunnel.my/downloads#release-notes`
- Downloads + dashboard now show consistent latest-version, update command, and highlights.

- Added modular webhook command group:
  - `instatunnel webhook init`
  - `instatunnel webhook verify`
  - `instatunnel webhook test`
- Added provider-aware guidance for Stripe, GitHub, Shopify, Twilio, and PayPal.
- Added prioritized OAuth callback testing and Team QA/demo workflow examples.
- Added `--run` support for Stripe test flow where feasible.
- Added `instatunnel doctor` for auth/network/MCP diagnostics (`--mcp`, `--port`, `--json`).
- Existing MCP and core tunnel commands remain backward compatible.

## Update commands

```bash
# Update
npm install -g instatunnel@latest

# Verify installed version
instatunnel --version

# Check latest published npm version
npm view instatunnel version
```

Language-specific CLI examples:
- Force Japanese CLI output for this command:
  - `INSTATUNNEL_LANG=ja instatunnel --version`
- Run doctor in Spanish via flag:
  - `instatunnel --lang es doctor`

Detailed usage (English): https://instatunnel.my/docs/cli-flags
Release notes (English): https://instatunnel.my/downloads#release-notes
Detailed usage (es/de/ja/fr):
- https://instatunnel.my/es/docs/cli-flags
- https://instatunnel.my/de/docs/cli-flags
- https://instatunnel.my/ja/docs/cli-flags
- https://instatunnel.my/fr/docs/cli-flags
Release notes (es/de/ja/fr):
- https://instatunnel.my/es/downloads#release-notes
- https://instatunnel.my/de/downloads#release-notes
- https://instatunnel.my/ja/downloads#release-notes
- https://instatunnel.my/fr/downloads#release-notes

## Popular use cases

- Localhost API sharing for frontend-backend integration
- Webhook testing for Stripe, GitHub, Slack, and custom integrations
- QA and client demos from local machines
- Mobile device testing against local environments
- MCP endpoint exposure for remote AI tooling workflows

## Prioritized workflows

### OAuth callback testing (localhost redirect flows)

```bash
# 1) Run your local app
npm run dev

# 2) Expose it with a stable subdomain
instatunnel 3000 --subdomain oauth-dev
```

Set your provider redirect URI (Google/GitHub/etc.) to:

`https://oauth-dev.instatunnel.my/auth/callback`

Then run:

```bash
instatunnel --logs
```

to inspect callback requests and response codes during auth flow testing.

### Team QA / demo links for local apps

```bash
# Protected review link for teammates/clients
instatunnel 3000 --subdomain acme-qa --auth qa:review2026 --qr

# Optional share copy helper
instatunnel --share
```

Best practices:
- Use a stable subdomain per project (`acme-qa`, `acme-staging`, etc.)
- Rotate demo credentials each cycle
- Stop tunnel after review with `Ctrl+C` or `instatunnel --kill <subdomain>`

## Common search terms

People usually find InstaTunnel via terms like:
- ngrok alternative
- localhost tunnel
- expose localhost to internet
- webhook testing tool
- https tunnel for local development
- custom subdomain tunnel
- MCP tunnel
- tunnel for local API

## Links

- Website: https://instatunnel.my
- Docs: https://instatunnel.my/docs
- Docs (ES): https://instatunnel.my/es/docs
- Docs (DE): https://instatunnel.my/de/docs
- Docs (JA): https://instatunnel.my/ja/docs
- Docs (FR): https://instatunnel.my/fr/docs
- Webhook Guides: https://instatunnel.my/docs/webhooks
- Pricing: https://instatunnel.my/pricing
- Dashboard: https://dashboard.instatunnel.my
- Support: support@instatunnel.my