Ngrok Tunneling

Make your local development sites accessible from anywhere on the internet using ngrok tunnels. Perfect for sharing work with clients, testing webhooks, or collaborating with remote teams.

Note

What is ngrok? Ngrok creates a secure tunnel from the internet to your local development server, giving it a public URL that anyone can access.

Prerequisites

Before you can use ngrok tunneling, you need:

• An active DAMP project with DevContainer running
• A free ngrok account (sign up at ngrok.com)
• Your ngrok authtoken from the ngrok dashboard

Tip

Free ngrok accounts work great for development! Paid plans offer custom domains, reserved URLs, and higher limits.

Setup Your Authtoken

1. Open DAMP Settings

   Navigate to Settings → Ngrok Tunneling section.

2. Enter your authtoken

   Paste your ngrok authtoken from the dashboard into the Authtoken field.

3. Validate the token (optional)

   Click “Validate” to ensure your token is working correctly.

4. Save configuration

   Click “Save Configuration” to store your settings.

Your authtoken is now saved and will be used for all tunnel connections.

Start a Tunnel

1. Open your project

   Navigate to the Sites page and select a project.

2. Ensure DevContainer is running

   The site’s DevContainer must be active (status should show “Active”).

   Caution

   Tunnels can only be created for sites with running DevContainers. Start your DevContainer in VS Code first.

3. Open Tunnel Management

   Click the tunnel icon or navigate to the tunnel section for your site.

4. Start the tunnel

   Click “Start Tunnel” button.

   Wait a few seconds while ngrok establishes the connection…

5. Get your public URL

   Once connected, you’ll see a public URL like:

   https://abc123.ngrok-free.app

   Click the copy button to copy the URL to your clipboard.

Share Your Site

Your site is now accessible from anywhere! Share the public URL with:

• 🌐 Clients - Show off your work in progress
• 👥 Team members - Collaborate remotely
• 🔗 Webhook services - Test integrations (Stripe, PayPal, etc.)
• 📱 Mobile devices - Test on real devices

Pro Tip

Use ngrok tunnels to test mobile apps against your local API or verify responsive designs on actual devices.

Monitor Your Tunnel

While your tunnel is active, DAMP shows real-time statistics:

• Connection count - Number of active connections
• HTTP requests - Total requests received
• Public URL - Your current tunnel address
• Status - Active/Inactive indicator

Advanced Configuration

Site-Specific Settings

Each site can have its own ngrok configuration:

1. Open Site-Specific Settings

   In the tunnel management panel, click “Site-Specific Settings”.

2. Configure options

   • Custom Domain: Use a branded URL (requires paid plan)
   • Region: Pin tunnel to specific region (us, eu, ap, etc.)
   • Compression: Enable gzip compression (requires paid plan)

3. Save settings

   Click “Save Site Settings” to apply.

Global Settings

Configure default settings for all tunnels in Settings → Ngrok Tunneling:

• Region - Choose closest region for better performance
• Compression - Enable by default for all tunnels

Stop a Tunnel

When you’re done sharing:

1. Click “Stop Tunnel” button
2. The public URL will immediately become unavailable
3. All active connections are gracefully closed

Note

Tunnels automatically stop when you close DAMP or shut down the DevContainer.

Use Cases

Client Demos

Share work-in-progress with clients without deploying:

1. Start your local site
2. Create ngrok tunnel
3. Share the public URL
4. Client can view your site immediately

Webhook Testing

Test webhook integrations from services like Stripe or GitHub:

1. Start tunnel to your local site
2. Configure webhook URL in the service
3. Receive real webhook events locally
4. Debug with your local development tools

Mobile Testing

Test your site on real mobile devices:

1. Start tunnel for your responsive site
2. Open the ngrok URL on your phone/tablet
3. Test touch interactions and mobile layouts
4. Debug using desktop dev tools

Remote Collaboration

Show your work to remote team members instantly:

1. Start tunnel for your feature branch
2. Share URL in team chat
3. Get instant feedback
4. Iterate together in real-time

Limitations & Best Practices

Free Account Limits

• ⏱️ 40 connections/minute - Enough for normal development
• 🔗 1 online tunnel - Can only run one tunnel at a time
• 🌐 Random URLs - New URL on each restart
• ⏰ 8-hour sessions - Tunnel disconnects after 8 hours

Tip

Upgrade to a paid plan for custom domains, reserved URLs, and higher limits.

Security Considerations

• 🔒 HTTPS only - Ngrok provides secure tunnels by default
• 🚫 Don’t share sensitive data - Remember the internet can access your tunnel
• 🔐 Use authentication - Add password protection for sensitive sites
• ⏱️ Stop when done - Don’t leave tunnels running unnecessarily

Performance Tips

• 📍 Choose nearest region - Reduces latency
• 🗜️ Enable compression - Faster transfers (paid feature)
• 🧹 Clean up inactive tunnels - Stop tunnels you’re not using

Troubleshooting

”Devcontainer Not Running”

Problem: Can’t start tunnel Solution: Open project in VS Code and start the DevContainer first

”Invalid Authtoken”

Problem: Token validation fails Solution:

1. Get fresh token from ngrok dashboard
2. Ensure no extra spaces when pasting
3. Save and validate again

”Connection Failed”

Problem: Tunnel won’t start Solution:

1. Check your internet connection
2. Verify Docker and DevContainer are running
3. Try stopping and starting the DevContainer
4. Check ngrok service status at status.ngrok.com

”URL Not Working”

Problem: Public URL not accessible Solution:

1. Verify tunnel status shows “Active”
2. Check site is running in DevContainer
3. Test local URL first (https://sitename.local)
4. Refresh the tunnel status

FAQ

Q: Do I need to pay for ngrok? A: No, the free tier works great for development. Paid plans add custom domains and higher limits.

Q: Can I use the same tunnel URL every time? A: Only with ngrok paid plans. Free accounts get a new random URL each time.

Q: How long does a tunnel stay active? A: Free accounts: 8 hours maximum. Paid accounts: unlimited.

Q: Can I run multiple tunnels at once? A: Free accounts: 1 tunnel. Paid accounts: multiple tunnels.

Q: Is it safe to share my ngrok URL? A: Ngrok uses HTTPS, but the URL is public. Don’t expose sensitive data without authentication.

Q: Why does my tunnel disconnect? A: Common causes: 8-hour limit, internet disruption, DevContainer stopped, or ngrok service issues.

---

Start sharing! 🚀 Ngrok tunneling makes it incredibly easy to share your local development work with the world. No deployment, no configuration - just click and share.

Need help? Check our troubleshooting guide or join our community.