Microsoft Teams Side Panel (Node.js) Local Debugging Issue: Connectivity Lost After Ngrok/Local Tunnel Restart

To achieve a persistent local development setup for your Microsoft Teams Meeting Side Panel using Node.js, you can consider the following approaches:

1. Using Microsoft Dev Tunnels:
   • Microsoft Dev Tunnels allows you to create a persistent tunnel that remains the same across sessions. You can create a tunnel with a command like:

          devtunnel create --allow-anonymous
     

   • After creating the tunnel, start it with:

          devtunnel host -p 3001 --allow-anonymous
     

   • This will provide you with a static URL that you can use in your Azure Bot Service and Teams app manifest, avoiding the need for manual updates after each restart.
2. Configuring Ngrok with a Reserved Static Domain:
   • If you prefer using Ngrok, you can set up a reserved domain. This requires a paid Ngrok plan that allows you to reserve a static subdomain. Once you have a reserved domain, you can start Ngrok with:

          ngrok http -subdomain=<your_subdomain> 3001
     

   • Update your Azure Bot Service and Teams app manifest with this static URL, ensuring that the Messaging Endpoint and validDomains are set correctly.
3. Updating Configuration Once:
   • For both methods, ensure that you update the Messaging Endpoint in Azure and the validDomains array in your Teams app manifest only once with the static URL. This will provide long-term stability and eliminate the need for repetitive updates after restarts.

By implementing either of these solutions, you can streamline your development workflow and avoid the inefficiencies caused by dynamic URLs.

Hi Irshad Gouri

Thank you for reaching out to Microsoft Q&A forum

Based on your description, I understand you need a solution that provides a static, persistent public URL to avoid manually updating the app after each restart, either through a persistent Microsoft Dev Tunnel or a reserved Ngrok domain. 

First, I have to acknowledge that due to the highly technical nature of this issue, it may be challenging for me to provide a definitive solution because of limitations in the testing environment and available resources. However, I will do my best to offer a solution within my capacity. For this case, I’ve conducted some research and found the following information: 

Initially, as stated in Dev tunnels documentation the root cause of this behavior is that Teams apps rely on specific URLs declared in your app manifest and the Azure Bot Service, but when you're using ephemeral tunnels, like with Ngrok or Microsoft Dev Tunnels, the hostname changes every time you restart. This causes mismatches that can block iframes, break SSO, or result in rejected bot traffic since those URLs are no longer valid.

Therefore, an ordinary approach for this context is:

You must switch from ephemeral tunnels to a persistent hostname and update all references once. Microsoft Dev Tunnels supports persistent URLs you can reuse across sessions, and Ngrok offers reserved domains/custom domains, so your public URL remains stable.

Regarding your concern: Has anyone found a robust solution for a persistent local development setup for this Teams sample that avoids manual configuration updates after every restart?

You can try 2 options for this context to see if it can fulfill your concern

Option A: Using Microsoft Dev tunnels

Create a named persistent tunnel and reuse it every session.

# 1) Install & sign in
winget install Microsoft.devtunnel          # or brew install --cask devtunnel (macOS)
devtunnel user login                        # Microsoft Entra or GitHub
# 2) Create a named tunnel and add port 3001 (HTTPS)
devtunnel create my-sidepanel --allow-anonymous
devtunnel port create -p 3001 --protocol https
# 3) Host the same tunnel each time (URL stays the same)
devtunnel host my-sidepanel

These commands use a named tunnel so the public URL persists across sessions; hosting the same tunnel name reuses the URL. You can read here for more information:

• Dev tunnels command-line reference
• Create and host a dev tunnel

Additionally, if you use the Teams Toolkit/Agents Toolkit, disable its auto-create tunnel and point your .env.local to the persistent Dev Tunnel URL (BOT_DOMAIN, BOT_ENDPOINT). This avoids generating a new URL on each F5.

Option B: Using Ngrok with a reserved/static domain (paid or BYO domain)

1/ Reserve a subdomain (like myapp.ngrok.app) or bring your own domain via CNAME to ngrok’s edge.

# Start the tunnel bound to your reserved hostname
ngrok http --url myapp.ngrok.app 3001
# or with config file / API for reserved domains

Reserved/custom domains don’t change across sessions; use ngrok’s dashboard/API to create and bind them.

2/ One‑time updates you must make (then you’re done) is setting Azure Bot Service → Messaging endpoint: set to your static base URL + /api/messages (e.g., https://<static-host>/api/messages). You can do it in Portal or via CLI:

az bot update -n <BotName> -g <ResourceGroup> \
  --endpoint "https://<static-host>/api/messages"

Link references:

https://ngrok.com/docs/universal-gateway/domains

https://ngrok.com/docs/universal-gateway/custom-domains

https://ngrok.com/docs/api-reference/reserveddomains/create

Note: Microsoft is providing this information as a convenience to you. These sites are not controlled by Microsoft, and Microsoft cannot make any representations regarding the quality, safety, or suitability of any software or information found there. Please ensure that you fully understand the risks before using any suggestions from the above link.

Hope my answer will help you, for any further concern, kindly let me know in the comment section.

If the answer is helpful, please click "Accept Answer" and kindly upvote it. If you have extra questions about this answer, please click "Comment".     

Note: Please follow the steps in our documentation to enable e-mail notifications if you want to receive the related email notification for this thread.