CINXE.COM
<!doctype html> <html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-agent/index" data-has-hydrated="false"> <head> <meta charset="UTF-8"> <meta name="generator" content="Docusaurus v3.5.2"> <title data-rh="true">Overview | ngrok documentation</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:image" content="https://ngrok.com/docs/img/ngrok-docs-opengraph.png"><meta data-rh="true" name="twitter:image" content="https://ngrok.com/docs/img/ngrok-docs-opengraph.png"><meta data-rh="true" property="og:url" content="https://ngrok.com/docs/agent/"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="keywords" content="ngrok, documentation, api, errors, reference, getting started, tutorials"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Overview | ngrok documentation"><meta data-rh="true" name="description" content="Overview"><meta data-rh="true" property="og:description" content="Overview"><link data-rh="true" rel="icon" href="/docs/img/favicon.ico"><link data-rh="true" rel="canonical" href="https://ngrok.com/docs/agent/"><link data-rh="true" rel="alternate" href="https://ngrok.com/docs/agent/" hreflang="en"><link data-rh="true" rel="alternate" href="https://ngrok.com/docs/agent/" hreflang="x-default"><link data-rh="true" rel="preconnect" href="https://8D7MHVMLBR-dsn.algolia.net" crossorigin="anonymous"><link rel="preconnect" href="https://www.googletagmanager.com"> <script>window.dataLayer=window.dataLayer||[]</script> <script>!function(e,t,a,n){e[n]=e[n]||[],e[n].push({"gtm.start":(new Date).getTime(),event:"gtm.js"});var g=t.getElementsByTagName(a)[0],m=t.createElement(a);m.async=!0,m.src="https://www.googletagmanager.com/gtm.js?id=GTM-P4F37ZW",g.parentNode.insertBefore(m,g)}(window,document,"script","dataLayer")</script> <script id="hs-script-loader" src="//js.hs-scripts.com/21124867.js"></script> <link rel="preload" href="https://cdn.ngrok.com/static/fonts/euclid-square/EuclidSquare-Regular-WebS.woff" as="font" type="font/woff" crossorigin="anonymous"> <link rel="preload" href="https://cdn.ngrok.com/static/fonts/euclid-square/EuclidSquare-RegularItalic-WebS.woff" as="font" type="font/woff" crossorigin="anonymous"> <link rel="preload" href="https://cdn.ngrok.com/static/fonts/euclid-square/EuclidSquare-Medium-WebS.woff" as="font" type="font/woff" crossorigin="anonymous"> <link rel="preload" href="https://cdn.ngrok.com/static/fonts/euclid-square/EuclidSquare-Semibold-WebS.woff" as="font" type="font/woff" crossorigin="anonymous"> <link rel="preload" href="https://cdn.ngrok.com/static/fonts/euclid-square/EuclidSquare-MediumItalic-WebS.woff" as="font" type="font/woff" crossorigin="anonymous"> <link rel="preload" href="https://cdn.ngrok.com/static/fonts/ibm-plex-mono/IBMPlexMono-Text.woff" as="font" type="font/woff" crossorigin="anonymous"> <link rel="preload" href="https://cdn.ngrok.com/static/fonts/ibm-plex-mono/IBMPlexMono-TextItalic.woff" as="font" type="font/woff" crossorigin="anonymous"> <link rel="preload" href="https://cdn.ngrok.com/static/fonts/ibm-plex-mono/IBMPlexMono-SemiBold.woff" as="font" type="font/woff" crossorigin="anonymous"> <link rel="preload" href="https://cdn.ngrok.com/static/fonts/ibm-plex-mono/IBMPlexMono-SemiBoldItalic.woff" as="font" type="font/woff" crossorigin="anonymous"> <script src="/docs/scripts/ketch.js"></script> <script src="https://global.ketchcdn.com/web/v2/config/ngrok/ngrok_ketch_tag/boot.js" async defer="defer"></script> <script src="/docs/scripts/fix-redirect.js" async></script> <script src="/docs/scripts/anchor-scroll-to.js" async></script> <script src="https://tag.clearbitscripts.com/v1/pk_1caf9e9fb3222466245fb17c8f807837/tags.js"></script><link rel="stylesheet" href="/docs/assets/css/styles.13d6ab4e.css"> <script src="/docs/assets/js/runtime~main.36fd4022.js" defer="defer"></script> <script src="/docs/assets/js/main.94660bb2.js" defer="defer"></script> </head> <body class="navigation-with-keyboard"> <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-P4F37ZW" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript> <script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();t(null!==e?e:"light")}(),function(){try{const n=new URLSearchParams(window.location.search).entries();for(var[t,e]of n)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><div role="region" aria-label="Skip to main content"><a class="skipToContent_IipK" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a href="https://ngrok.com" target="_blank" rel="noopener noreferrer" class="navbar__brand"><div class="navbar__logo"><img src="/docs/img/ngrok-black.svg" alt="ngrok" class="themedComponent_Az_r themedComponent--light_ik9_"><img src="/docs/img/ngrok-white.svg" alt="ngrok" class="themedComponent_Az_r themedComponent--dark_eDvw"></div></a><a href="https://ngrok.com/product/platform" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Platform</a><a href="https://ngrok.com/use-cases" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Use cases</a><a href="https://ngrok.com/blog" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Blog</a><a href="https://ngrok.com/resources" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Resources</a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs/">Docs</a><a href="https://ngrok.com/pricing" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Pricing</a><a href="https://download.ngrok.com" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Get ngrok</a></div><div class="navbar__items navbar__items--right"><a href="https://dashboard.ngrok.com/login" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link dev-portal-login dev-portal-link">Log in</a><a href="https://ngrok.com/signup" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link dev-portal-signup dev-portal-link">Sign Up</a><div class="toggle_DITL colorModeToggle_bvw4"><button class="clean-btn toggleButton_bazi toggleButtonDisabled_IzIM" type="button" disabled="" title="Switch between dark and light mode (currently light mode)" aria-label="Switch between dark and light mode (currently light mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_j6C1"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_uFh4"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="navbarSearchContainer_nbxA"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_pOYi"><div class="docsWrapper_kVRX"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_OuIh" type="button"></button><div class="docRoot_v94m"><aside class="theme-doc-sidebar-container docSidebarContainer_JlOU"><div class="sidebarViewport_A_zS"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20" aria-hidden="true"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button><div class="sidebar_idex"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_nVoB"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/">Overview</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/what-is-ngrok/">What is ngrok?</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/how-ngrok-works/">How does ngrok work?</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/why-ngrok/">Why ngrok?</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/whats-new/">What's new?</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/getting-started/">Getting Started</a><button aria-label="Expand sidebar category 'Getting Started'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1"><div class="menu__section">Endpoints</div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/http/">HTTP</a><button aria-label="Expand sidebar category 'HTTP'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/tls/">TLS</a><button aria-label="Expand sidebar category 'TLS'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/tcp/">TCP</a><button aria-label="Expand sidebar category 'TCP'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1"><div class="menu__section">Connectivity</div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible menu__list-item-collapsible--active"><a class="menu__link menu__link--sublist menu__link--active" aria-current="page" href="/docs/agent/">Agent</a><button aria-label="Collapse sidebar category 'Agent'" aria-expanded="true" type="button" class="clean-btn menu__caret"></button></div><ul style="display:block;overflow:visible;height:auto" class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/agent/">Overview</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/agent/web-inspection-interface/">Web Inspection Interface</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/agent/cli/">CLI</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/agent/cli-api/">CLI API Commands</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-2 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" tabindex="0" href="/docs/agent/config/">Configuration file</a><button aria-label="Expand sidebar category 'Configuration file'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/agent/api/">API</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/agent/ssh-reverse-tunnel-agent/">SSH Reverse Tunnel</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/agent/ingress/">Ingress Address</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/agent/changelog/">Changelog</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/agent/version-support-policy/">Version Support Policy</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/agent/diagnose/">Diagnose</a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/agent-sdks/">Agent SDKs</a><button aria-label="Expand sidebar category 'Agent SDKs'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/k8s/">Kubernetes</a><button aria-label="Expand sidebar category 'Kubernetes'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1"><div class="menu__section">Platform</div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/network-edge/">Network Edge</a><button aria-label="Expand sidebar category 'Network Edge'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/api/">API</a><button aria-label="Expand sidebar category 'API'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/obs/">Observability</a><button aria-label="Expand sidebar category 'Observability'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/iam/">IAM</a><button aria-label="Expand sidebar category 'IAM'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/errors/">Errors</a><button aria-label="Expand sidebar category 'Errors'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1"><div class="menu__section">Walkthroughs</div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/guides/">Guides</a><button aria-label="Expand sidebar category 'Guides'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" href="/docs/integrations/">Integrations</a><button aria-label="Expand sidebar category 'Integrations'" aria-expanded="false" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1"><div class="menu__section"></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="/docs/faq/">FAQ</a></li></ul></nav></div></div></aside><main class="docMainContainer_HBBy"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_dNMx"><div class="docItemContainer_iJh1"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_SKcw" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/docs/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_ZMzL"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">Agent</span><meta itemprop="position" content="1"></li></ul></nav><div class="tocCollapsible_AX1Z theme-doc-toc-mobile tocMobile_HCfs"><button type="button" class="clean-btn tocCollapsibleButton_gEwV">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>ngrok Agent</h1></header> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="overview">Overview<a href="#overview" class="hash-link" aria-label="Direct link to Overview" title="Direct link to Overview"></a></h2> <p>The ngrok agent is a lightweight command-line program that forwards traffic from endpoints it creates on the ngrok edge to your upstream application services.</p> <p>The ngrok agent is a standalone native executable with zero runtime dependencies. It runs on <a href="#system-requirements">all major operating systems</a> and it is packaged for distribution on most popular package managers.</p> <p>The ngrok agent uses a simple <a href="/docs/agent/config/">YAML configuration file</a>, can install itself as a native operating system service and also has a built-in CLI for calling the <a href="/docs/api/">ngrok API</a>.</p> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="install">Install<a href="#install" class="hash-link" aria-label="Direct link to Install" title="Direct link to Install"></a></h2> <p>Follow the <a href="/docs/getting-started/#step-1-install">getting started guide</a> or visit the <a href="https://download.ngrok.com" target="_blank" rel="noopener noreferrer">download page</a> to install and set up the ngrok agent.</p> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="example-usage">Example Usage<a href="#example-usage" class="hash-link" aria-label="Direct link to Example Usage" title="Direct link to Example Usage"></a></h2> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="http-endpoint">HTTP Endpoint<a href="#http-endpoint" class="hash-link" aria-label="Direct link to HTTP Endpoint" title="Direct link to HTTP Endpoint"></a></h3> <p>Serve your web app listening at port 8080 on a random public URL</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok http </span><span class="token number" style="color:#36acaa">8080</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="static-domain">Static Domain<a href="#static-domain" class="hash-link" aria-label="Direct link to Static Domain" title="Direct link to Static Domain"></a></h3> <p>Serve a web app on example.ngrok.app</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok http </span><span class="token number" style="color:#36acaa">80</span><span class="token plain"> </span><span class="token parameter variable" style="color:#36acaa">--url</span><span class="token plain"> example.ngrok.app</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="basic-auth">Basic Auth<a href="#basic-auth" class="hash-link" aria-label="Direct link to Basic Auth" title="Direct link to Basic Auth"></a></h3> <p>Secure your web app with a username + password</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok http </span><span class="token number" style="color:#36acaa">80</span><span class="token plain"> --basic-auth </span><span class="token string" style="color:#e3116c">"username1:password1"</span><span class="token plain"> --basic-auth </span><span class="token string" style="color:#e3116c">"username2:password2"</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="forward-to-non-local">Forward to non-local<a href="#forward-to-non-local" class="hash-link" aria-label="Direct link to Forward to non-local" title="Direct link to Forward to non-local"></a></h3> <p>Forward to a service not listening on localhost</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok http </span><span class="token number" style="color:#36acaa">192.168</span><span class="token plain">.1.2:80</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="local-https-server">Local HTTPS Server<a href="#local-https-server" class="hash-link" aria-label="Direct link to Local HTTPS Server" title="Direct link to Local HTTPS Server"></a></h3> <p>Forward to an upstream service listening for <code>https</code></p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok http https://localhost:8443</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="forwarding-to-ipv6-address">Forwarding to IPv6 Address<a href="#forwarding-to-ipv6-address" class="hash-link" aria-label="Direct link to Forwarding to IPv6 Address" title="Direct link to Forwarding to IPv6 Address"></a></h3> <p>The ngrok agent can also forward to IPv6 addresses</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok http </span><span class="token string" style="color:#e3116c">'[::1]:80'</span><span class="token plain"> </span><span class="token parameter variable" style="color:#36acaa">--url</span><span class="token plain"> ipv6.example.com</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok http </span><span class="token string" style="color:#e3116c">'https://[2001:db8::123.123.123.123]:8443'</span><span class="token plain"> </span><span class="token parameter variable" style="color:#36acaa">--url</span><span class="token plain"> ipv6.example.com</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="tcp-endpoint">TCP Endpoint<a href="#tcp-endpoint" class="hash-link" aria-label="Direct link to TCP Endpoint" title="Direct link to TCP Endpoint"></a></h3> <p>Accept traffic to a non-HTTP service.</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok tcp </span><span class="token number" style="color:#36acaa">22</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="tls-endpoint">TLS Endpoint<a href="#tls-endpoint" class="hash-link" aria-label="Direct link to TLS Endpoint" title="Direct link to TLS Endpoint"></a></h3> <p>Listen on <code>your-name.ngrok.app</code> for TLS traffic. It could be HTTPS, but any protocol wrapped in TLS is accepted.</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok tls </span><span class="token number" style="color:#36acaa">80</span><span class="token plain"> --terminate-at edge </span><span class="token parameter variable" style="color:#36acaa">--url</span><span class="token plain"> your-name.ngrok.app</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="multiple-endpoints">Multiple Endpoints<a href="#multiple-endpoints" class="hash-link" aria-label="Direct link to Multiple Endpoints" title="Direct link to Multiple Endpoints"></a></h3> <p>Start multiple tunnels defined in the <a href="/docs/agent/config/">configuration file</a>.</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok start foo bar baz</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="tab-completion">Tab Completion<a href="#tab-completion" class="hash-link" aria-label="Direct link to Tab Completion" title="Direct link to Tab Completion"></a></h2> <p>The ngrok agent has built-in tab completion which makes it easy to navigate its command and flags by hitting tab in your terminal when using a <code>bash</code> or <code>zsh</code> shell. Add tab-completion to your shell session with:</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token builtin class-name">.</span><span class="token plain"> </span><span class="token operator" style="color:#393A34"><</span><span class="token punctuation" style="color:#393A34">(</span><span class="token plain">ngrok completion</span><span class="token operator" style="color:#393A34">></span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <p>Install it permanently by following the documentation for the <a href="/docs/agent/cli/#ngrok-completion"><code>ngrok completion</code> command</a>.</p> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="authtokens">Authtokens<a href="#authtokens" class="hash-link" aria-label="Direct link to Authtokens" title="Direct link to Authtokens"></a></h2> <p>The ngrok agent authenticates with an authtoken. <a href="https://dashboard.ngrok.com/get-started/your-authtoken" target="_blank" rel="noopener noreferrer">Your authtoken is available on the ngrok dashboard</a>. Add your authtoken to the ngrok agent with the following command:</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok config add-authtoken </span><span class="token operator" style="color:#393A34"><</span><span class="token plain">TOKEN</span><span class="token operator" style="color:#393A34">></span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <p>This command updates the <code>authtoken</code> property in your <a href="/docs/agent/config/">ngrok configuration file</a>.</p> <p>Use a separate authtoken for each agent you configure. You can <a href="https://dashboard.ngrok.com/tunnels/authtokens" target="_blank" rel="noopener noreferrer">provision additional authtokens on your ngrok dashboard</a> or <a href="/docs/agent/config/v3/#authtoken">via API</a>. Separate authtokens isolate the security risk if an authtoken is compromised. It also allows you to configure <a href="#authtoken-acls">ACLs</a> on a per agent basis.</p> <p>When you provision a new authtoken, the full token is only displayed once. As a security feature, ngrok does not store a recoverable representation of the token.</p> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="authtoken-acls">Authtoken ACLs<a href="#authtoken-acls" class="hash-link" aria-label="Direct link to Authtoken ACLs" title="Direct link to Authtoken ACLs"></a></h2> <p>Authtoken ACLs restrict what actions an ngrok agent connecting with that authtoken is allowed to take. You may define multiple ACLs. Authtokens with no ACLs may take all actions. The following ACLs are supported:</p> <table><thead><tr><th>Example</th><th>Description</th></tr></thead><tbody><tr><td><code>bind:foo.ngrok.app</code></td><td>The agent may only create an endpoint on <code>foo.ngrok.app</code></td></tr><tr><td><code>bind:*.example.com</code></td><td>The agent may only create endpoints on subdomains of <code>example.com</code></td></tr><tr><td><code>bind:foo=bar</code></td><td>The agent may create a labeled tunnel with the label <code>foo=bar</code></td></tr><tr><td><code>bind:app=*</code></td><td>The agent may create labeled tunnels with labels like <code>app=x</code> or <code>app=y</code></td></tr><tr><td><code>bind:*</code></td><td>The agent may listen on all endpoints</td></tr></tbody></table> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="api-keys">API Keys<a href="#api-keys" class="hash-link" aria-label="Direct link to API Keys" title="Direct link to API Keys"></a></h2> <p>The ngrok agent contains a <a href="/docs/agent/cli/#ngrok-api">complete CLI for the ngrok API</a>.</p> <p>To use it, <a href="https://dashboard.ngrok.com/api" target="_blank" rel="noopener noreferrer">create an API Key on your ngrok dashboard</a> and then run:</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok config add-api-key </span><span class="token operator" style="color:#393A34"><</span><span class="token plain">API KEY</span><span class="token operator" style="color:#393A34">></span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <p>After you've installed the API Key, try querying your list of domains or online endpoints:</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok api endpoints list</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">ngrok api reserved-domains list</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="configuration-file">Configuration File<a href="#configuration-file" class="hash-link" aria-label="Direct link to Configuration File" title="Direct link to Configuration File"></a></h2> <p>The ngrok agent uses a <a href="/docs/agent/config/">YAML configuration file</a> to customize its behavior. The config file is useful if your configuration is too complex for the command line and if you want the agent to run multiple tunnels simultaneously.</p> <p>Consult the <a href="/docs/agent/config/">ngrok agent configuration file reference</a> for a full list of configuration file options.</p> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="environment-variables">Environment Variables<a href="#environment-variables" class="hash-link" aria-label="Direct link to Environment Variables" title="Direct link to Environment Variables"></a></h2> <p>The ngrok agent supports environment variables for some configuration. Environment variables take precedence over the corresponding values specified in the configuration file.</p> <table><thead><tr><th>Name</th><th>Configuration Property</th></tr></thead><tbody><tr><td><code>NGROK_AUTHTOKEN</code></td><td><a href="/docs/agent/config/v3/#authtoken"><code>authtoken</code></a></td></tr><tr><td><code>NGROK_API_KEY</code></td><td><a href="/docs/agent/config/v3/#api_key"><code>api_key</code></a></td></tr></tbody></table> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="background-service">Running ngrok in the background<a href="#background-service" class="hash-link" aria-label="Direct link to Running ngrok in the background" title="Direct link to Running ngrok in the background"></a></h2> <p>ngrok includes commands to run itself in the background as a native operating system service, i.e. as a daemon. When it runs as an operating system service it:</p> <ul> <li>Starts when the machine boots</li> <li>Automatically restarts after crashes</li> <li>Can be managed via native OS service tooling</li> <li>Sends logs to the OS's native logging service</li> <li>Starts all tunnels defined in the configuration file, the equivalent of running <code>ngrok start --all</code></li> </ul> <div class="theme-admonition theme-admonition-tip admonition_lLl2 alert alert--success"><div class="admonitionHeading_W0l2"><span class="admonitionIcon_qwqe"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</div><div class="admonitionContent_WR9v"><p>In most cases, installing ngrok as a service requires administrator privileges.</p></div></div> <table><thead><tr><th>OS</th><th>Notes</th></tr></thead><tbody><tr><td>Linux</td><td>The ngrok agent creates a <code>systemd</code> unit file. Errors and warnings are logged to <code>syslog</code>.</td></tr><tr><td>Windows</td><td>The ngrok agent installs itself as a Windows service. It can be managed via Windows Services. Errors and warnings are logged to the Windows event log.</td></tr><tr><td>MacOS</td><td>The ngrok agent creates a plist file and configures itself to run via <code>launchd</code>. Errors and warnings are logged to <code>syslog</code>.</td></tr></tbody></table> <h4 class="anchor anchorWithStickyNavbar_qeIy" id="try-it-out">Try it out<a href="#try-it-out" class="hash-link" aria-label="Direct link to Try it out" title="Direct link to Try it out"></a></h4> <p>Create an ngrok <a href="#configuration-file">configuration file</a>. For this example, we'll assume it's <code>C:\ngrok\ngrok.yml</code>. In your configuration file, make sure you include the <a href="/docs/agent/config/v3/#authtoken"><code>authtoken</code></a> property and define all of the tunnels that you want to start. Then run:</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok </span><span class="token function" style="color:#d73a49">service</span><span class="token plain"> </span><span class="token function" style="color:#d73a49">install</span><span class="token plain"> </span><span class="token parameter variable" style="color:#36acaa">--config</span><span class="token plain"> C:</span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain">ngrok</span><span class="token punctuation" style="color:#393A34">\</span><span class="token plain">ngrok.yml</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <p>This will validate that the configuration file is valid, and if so, install ngrok as a service using the given configuration file. The service installation includes the location of the ngrok executable and the configuration file, so don't move or delete either after you've installed the service.</p> <p>You can then start the ngrok agent service with:</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok </span><span class="token function" style="color:#d73a49">service</span><span class="token plain"> start</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <p>You can manage the agent with your OS's normal service tooling, but the agent also includes the <a href="/docs/agent/cli/#ngrok-service"><code>ngrok service</code> commands</a> to manage the installed service:</p> <ul> <li><code>ngrok service start</code></li> <li><code>ngrok service stop</code></li> <li><code>ngrok service restart</code></li> <li><code>ngrok service uninstall</code></li> </ul> <div class="theme-admonition theme-admonition-tip admonition_lLl2 alert alert--success"><div class="admonitionHeading_W0l2"><span class="admonitionIcon_qwqe"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</div><div class="admonitionContent_WR9v"><p>If you see an exit code <code>5</code> or <code>Input/output error</code>, it usually indicates that ngrok is not able to find the config file and/or does not have permissions to do so. Make sure you have installed the ngrok service with a valid config file and that when the service is run (either as you or an administrator) it has access to that same config file.</p></div></div> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="remote-management">Remote Management<a href="#remote-management" class="hash-link" aria-label="Direct link to Remote Management" title="Direct link to Remote Management"></a></h2> <p>The ngrok agent can be stopped, restarted, or upgraded remotely using the <a href="/docs/api/resources/tunnel-sessions/#restart-tunnel-agent">Tunnel Sessions</a> API. You can also perform these actions from the ngrok Dashboard.</p> <div class="theme-admonition theme-admonition-warning admonition_lLl2 alert alert--warning"><div class="admonitionHeading_W0l2"><span class="admonitionIcon_qwqe"><svg viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"></path></svg></span>warning</div><div class="admonitionContent_WR9v"><p>Use this with caution if you have made changes to the config file. If for some reason ngrok cannot restart, you may lose access to the agent completely.</p></div></div> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="connectivity">Connectivity<a href="#connectivity" class="hash-link" aria-label="Direct link to Connectivity" title="Direct link to Connectivity"></a></h2> <p>When the ngrok agent and Agent SDKs start, they establish long-lived TLS connections to the ngrok service through which they create new endpoints and receive connections from ngrok's edge that are intended for your upstream services.</p> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="connectivity-address">Address<a href="#connectivity-address" class="hash-link" aria-label="Direct link to Address" title="Direct link to Address"></a></h3> <p>By default, the latest ngrok agent dials the following "agent ingress address" when it connects to the ngrok service. This address resolves to a <a href="/docs/network-edge/#ip-addresses">dynamic set of IP Addresses</a>.</p> <div class="codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-text codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">connect.ngrok-agent.com:443</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <div class="theme-admonition theme-admonition-note admonition_lLl2 alert alert--secondary"><div class="admonitionHeading_W0l2"><span class="admonitionIcon_qwqe"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_WR9v"><p>All connections to ngrok servers are made on port 443.</p></div></div> <p>You can <a href="/docs/agent/ingress/">customize the agent ingress address</a> to brand it with your own domain.</p> <p>The agent by default only connects to a single region. However connections to multiple regions can be created with traffic load balanced across these connections. If you are interested in this capability, please <a href="https://ngrok.com/enterprise/contact" target="_blank" rel="noopener noreferrer">contact us</a>.</p> <p>The complete list of addresses and IP addresses available for the agent to connect to ngrok can be found in our <a href="https://s3.amazonaws.com/dns.ngrok.com/tunnel.json" target="_blank" rel="noopener noreferrer">ngrok DNS tunnel.json file</a>.</p> <div class="theme-admonition theme-admonition-note admonition_lLl2 alert alert--secondary"><div class="admonitionHeading_W0l2"><span class="admonitionIcon_qwqe"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_WR9v"><p>Prior to ngrok agent version 3.3.0, the ngrok agent connected to <code>tunnel.*.ngrok.com</code> domains. The latest agent uses <code>connect.*.ngrok-agent.com</code> domains.</p></div></div> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="additional-urls">Additional URLs<a href="#additional-urls" class="hash-link" aria-label="Direct link to Additional URLs" title="Direct link to Additional URLs"></a></h3> <p>In addition to the addresses used for connecting to the ngrok server, the ngrok agent may reach out to the following URLs.</p> <h4 class="anchor anchorWithStickyNavbar_qeIy" id="certificate-revocation-list-crl-check">Certificate Revocation List (CRL) Check<a href="#certificate-revocation-list-crl-check" class="hash-link" aria-label="Direct link to Certificate Revocation List (CRL) Check" title="Direct link to Certificate Revocation List (CRL) Check"></a></h4> <p>The ngrok agent reaches out to the following domains to check for revoked certificates. This check can be disabled by adding <code>crl_noverify: true</code> to your ngrok agent config.</p> <ul> <li>Prior to ngrok agent version 3.10.0: <code>http://crl.ngrok.com/ngrok.crl</code></li> <li>Latest versions: <code>http://crl.ngrok-agent.com/ngrok.crl</code></li> </ul> <div class="theme-admonition theme-admonition-note admonition_lLl2 alert alert--secondary"><div class="admonitionHeading_W0l2"><span class="admonitionIcon_qwqe"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_WR9v"><p>These connections use HTTP and port 80.</p></div></div> <h4 class="anchor anchorWithStickyNavbar_qeIy" id="ngrok-agent-update-check">ngrok Agent Update Check<a href="#ngrok-agent-update-check" class="hash-link" aria-label="Direct link to ngrok Agent Update Check" title="Direct link to ngrok Agent Update Check"></a></h4> <p>The ngrok agent will automatically look for updates when it starts up. This check can be disabled by adding <code>update_check: false</code> to your ngrok agent config.</p> <ul> <li><code>https://update.equinox.io</code></li> </ul> <div class="theme-admonition theme-admonition-note admonition_lLl2 alert alert--secondary"><div class="admonitionHeading_W0l2"><span class="admonitionIcon_qwqe"><svg viewBox="0 0 14 16"><path fill-rule="evenodd" d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</div><div class="admonitionContent_WR9v"><p>Even though the Equinox service was <a href="https://equinox.io/blog/shutting-down" target="_blank" rel="noopener noreferrer">shut down in 2021</a>, it is wholely owned and operated by ngrok, and as such, continues to be used for building and distributing our binaries.</p></div></div> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="dns-resolution">DNS Resolution<a href="#dns-resolution" class="hash-link" aria-label="Direct link to DNS Resolution" title="Direct link to DNS Resolution"></a></h3> <p>When the ngrok agent dials the ngrok service to establish its TLS connections, it resolves DNS for the <a href="/docs/agent/ingress/">connection address</a> which is defined by the <a href="/docs/agent/config/v3/#connect_url"><code>connect_url</code></a> configuration property. ngrok attempts to resolve DNS using multiple mechanisms so that it can establish connectivity even in network environments where DNS service is failing. ngrok attempts to resolve the IPs of its service using the following mechanisms:</p> <ul> <li>Via the system's default DNS resolvers</li> <li>Via Google's DNS servers (<code>8.8.8.8</code> and <code>8.8.4.4</code>)</li> <li>Via Google's DNS-over-HTTPS service (<a href="https://developers.google.com/speed/public-dns/docs/doh" target="_blank" rel="noopener noreferrer">https://developers.google.com/speed/public-dns/docs/doh</a>)</li> <li>Via a <a href="https://s3.amazonaws.com/dns.ngrok.com/tunnel.json" target="_blank" rel="noopener noreferrer">file hosted on an ngrok-controlled S3 bucket</a></li> </ul> <p>Instead of using the system's default DNS resolvers, you can configure the DNS servers the ngrok agent uses for resolution with the <a href="/docs/agent/config/v3/#dns_resolver_ips"><code>dns_resolver_ips</code></a> configuration option.</p> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="tls-verification">TLS Verification<a href="#tls-verification" class="hash-link" aria-label="Direct link to TLS Verification" title="Direct link to TLS Verification"></a></h3> <p>The ngrok agent connects to the ngrok service over TLS connections. The agent verifies the TLS Certificate returned by the ngrok service. The certificates returned by the ngrok service are signed by ngrok's own root certificate authority. The ngrok agent verifies the returned certificate against certificate authorities bundled into the agent itself.</p> <p>Lastly, the ngrok agent makes a request to <code>crl.ngrok-agent.com</code> to verify that the certificate returned by the ngrok service has not been revoked. It is possible to skip this step by setting <code>crl_noverify: true</code> in your configuration file.</p> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="heartbeats">Heartbeats<a href="#heartbeats" class="hash-link" aria-label="Direct link to Heartbeats" title="Direct link to Heartbeats"></a></h3> <p>Once the ngrok agent has established connectivity to the ngrok service, it periodically sends application-level heartbeat messages to validate the liveness of the connection. You may customize this behavior via the <a href="/docs/agent/config/v3/#heartbeat_interval"><code>heartbeat_interval</code></a> and <a href="/docs/agent/config/v3/#heartbeat_tolerance"><code>heartbeat_tolerance</code></a> configuration parameters.</p> <p>If the ngrok agent does not receive a response to its heartbeat within the tolerance window, it terminates the connection and begins reconnecting.</p> <p>ngrok's heartbeat mechanism allows it to recover from any type of network outage, even those caused by packet loss, dynamic IP changes, interface changes (e.g. WiFi to LTE) or complete network outages.</p> <p>The ngrok service also sends its own heartbeats to the agent which it uses to detect liveness and terminate dead connections.</p> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="reconnection">Reconnection<a href="#reconnection" class="hash-link" aria-label="Direct link to Reconnection" title="Direct link to Reconnection"></a></h3> <p>If the ngrok agent is disconnected for any reason, it will automatically begin reconnecting. Reconnecting begins the entire connection process over again, beginning with DNS resolution. The ngrok agent attempts to recover quickly and slowly backs off its reconnection attempts but always attempts to re-establish connectivity unless the ngrok service explicitly instructs it to stop reconnecting.</p> <h3 class="anchor anchorWithStickyNavbar_qeIy" id="troubleshooting-connectivity">Troubleshooting<a href="#troubleshooting-connectivity" class="hash-link" aria-label="Direct link to Troubleshooting" title="Direct link to Troubleshooting"></a></h3> <p>If the ngrok agent can't connect to the ngrok service, it is often difficult to understand why.</p> <p>The ngrok agent includes the <code>ngrok diagnose</code> command to help you troubleshoot connection failures. It runs a series of tests to diagnose potential issues when connecting to the ngrok service. Consult the <a href="/docs/agent/cli/#ngrok-diagnose"><code>ngrok diagnose</code> documentation</a> or <a href="/docs/agent/diagnose/">Diagnose</a> page for additional details.</p> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="system-requirements">System Requirements<a href="#system-requirements" class="hash-link" aria-label="Direct link to System Requirements" title="Direct link to System Requirements"></a></h2> <h4 class="anchor anchorWithStickyNavbar_qeIy" id="supported-platforms">Supported Platforms<a href="#supported-platforms" class="hash-link" aria-label="Direct link to Supported Platforms" title="Direct link to Supported Platforms"></a></h4> <p>The ngrok agent runs on all major platforms including Linux, MacOS, Windows and most CPU architectures. See the <a href="https://download.ngrok.com" target="_blank" rel="noopener noreferrer">ngrok agent download</a> page. It is also distributed as a Docker container.</p> <table><thead><tr><th>OS</th><th>Supported Architectures</th></tr></thead><tbody><tr><td>Windows</td><td>64-bit, 32-bit (<code>x86-64</code>, <code>x86</code>)</td></tr><tr><td>MacOS</td><td>Intel, Apple Silicon (<code>x86-64</code>, <code>arm64</code>)</td></tr><tr><td>Linux</td><td><code>x86-64</code>, <code>x86</code>, <code>arm</code>, <code>arm64</code>, <code>mips</code>, <code>mips64</code>, <code>mips64le</code>, <code>mipsle</code>, <code>ppc64</code>, <code>ppc64le</code>, <code>s390x</code></td></tr><tr><td>FreeBSD</td><td><code>x86-64</code>, <code>x86</code>, <code>arm</code>, <code>arm64</code></td></tr></tbody></table> <p>If the agent does not run on your target platform, you can still use ngrok via the <a href="/docs/agent-sdks/">Agent SDKs</a> or the <a href="/docs/agent/ssh-reverse-tunnel-agent/">SSH Reverse Tunnel Agent</a>.</p> <h4 class="anchor anchorWithStickyNavbar_qeIy" id="resource-requirements">Resource Requirements<a href="#resource-requirements" class="hash-link" aria-label="Direct link to Resource Requirements" title="Direct link to Resource Requirements"></a></h4> <p>The ngrok agent is lightweight enough to run most everywhere, even on many embedded platforms. Keep in mind that the ngrok agent's resource usage depends on how much concurrent traffic you drive through it. If your resource requirements are more stringent, you can still use ngrok via the <a href="/docs/agent-sdks/">Agent SDKs</a> or the <a href="/docs/agent/ssh-reverse-tunnel-agent/">SSH Reverse Tunnel Agent</a>.</p> <table><thead><tr><th>Resource</th><th>Value</th></tr></thead><tbody><tr><td>Memory</td><td>64MB minimum, 128MB recommended</td></tr><tr><td>Disk</td><td>25MB</td></tr><tr><td>CPU</td><td>No requirement</td></tr></tbody></table> <div class="theme-admonition theme-admonition-tip admonition_lLl2 alert alert--success"><div class="admonitionHeading_W0l2"><span class="admonitionIcon_qwqe"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</div><div class="admonitionContent_WR9v"><p>You can reduce memory usage in the ngrok agent by disabling <a href="/docs/agent/config/#inspect_db_size">inspection in the configuration file</a>.</p></div></div> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="updates">Updates<a href="#updates" class="hash-link" aria-label="Direct link to Updates" title="Direct link to Updates"></a></h2> <p>The ngrok agent can update itself even if you didn't install it with a package manager. Update the ngrok agent with the <a href="/docs/agent/cli/#ngrok-update"><code>ngrok update</code></a> command.</p> <div class="language-bash codeBlockContainer_eHBk theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_feMQ"><pre tabindex="0" class="prism-code language-bash codeBlock_HtbR thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_JKK0"><span class="token-line" style="color:#393A34"><span class="token plain">ngrok update</span><br></span></code></pre><div class="buttonGroup_Ug71"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_c3my" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_y0ux"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_mLQu"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div> <p>By default, the ngrok agent automatically checks for available updates when it runs. If an update is available, it will prompt you to update by pressing <code>Ctrl+U</code>. You can configure whether the agent checks for updates via the <a href="/docs/agent/config/v3/#update_check"><code>update_check</code> config parameter</a>.</p> <p>You can configure which release channel (e.g. <code>stable</code>, <code>beta</code>) the agent uses for updates via the <a href="/docs/agent/config/v3/#update_channel"><code>update_channel</code> config parameter</a>.</p> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="ip-restrictions">IP Restrictions<a href="#ip-restrictions" class="hash-link" aria-label="Direct link to IP Restrictions" title="Direct link to IP Restrictions"></a></h2> <p>All agents must use an authtoken to authenticate with ngrok, but you may also further restrict with IP Policies that specify which IPs and CIDRs agents may connect to your ngrok account from.</p> <ul> <li><a href="https://dashboard.ngrok.com/security/ip-restrictions" target="_blank" rel="noopener noreferrer">IP Restrictions on your ngrok dashboard</a></li> <li><a href="/docs/api/resources/ip-restrictions/">IP Restrictions API Resource</a></li> </ul> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="api">API<a href="#api" class="hash-link" aria-label="Direct link to API" title="Direct link to API"></a></h2> <p>The ngrok agent has its own HTTP API that can be used to dynamically inspect, start and stop tunnels on the agent while it is running. Consult the <a href="/docs/agent/api/">ngrok agent API reference documentation</a> for more details.</p> <div class="theme-admonition theme-admonition-tip admonition_lLl2 alert alert--success"><div class="admonitionHeading_W0l2"><span class="admonitionIcon_qwqe"><svg viewBox="0 0 12 16"><path fill-rule="evenodd" d="M6.5 0C3.48 0 1 2.19 1 5c0 .92.55 2.25 1 3 1.34 2.25 1.78 2.78 2 4v1h5v-1c.22-1.22.66-1.75 2-4 .45-.75 1-2.08 1-3 0-2.81-2.48-5-5.5-5zm3.64 7.48c-.25.44-.47.8-.67 1.11-.86 1.41-1.25 2.06-1.45 3.23-.02.05-.02.11-.02.17H5c0-.06 0-.13-.02-.17-.2-1.17-.59-1.83-1.45-3.23-.2-.31-.42-.67-.67-1.11C2.44 6.78 2 5.65 2 5c0-2.2 2.02-4 4.5-4 1.22 0 2.36.42 3.22 1.19C10.55 2.94 11 3.94 11 5c0 .66-.44 1.78-.86 2.48zM4 14h5c-.23 1.14-1.3 2-2.5 2s-2.27-.86-2.5-2z"></path></svg></span>tip</div><div class="admonitionContent_WR9v"><p>If you want to programmatically control the ngrok agent, the <a href="/docs/agent-sdks/">Agent SDKs</a> are usually a more flexible and powerful choice.</p></div></div> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="using-ngrok-without-the-agent">Using ngrok without the agent<a href="#using-ngrok-without-the-agent" class="hash-link" aria-label="Direct link to Using ngrok without the agent" title="Direct link to Using ngrok without the agent"></a></h2> <p>There are three ways to use ngrok without the agent:</p> <ul> <li><a href="/docs/agent-sdks/">Agent SDKs</a></li> <li><a href="/docs/k8s/">Kubernetes Operator</a></li> <li><a href="/docs/agent/ssh-reverse-tunnel-agent/">SSH Reverse Tunnel</a></li> </ul> <p>You may want to use ngrok with one of the alternatives above if:</p> <ul> <li>You don't want to manage the lifetime of a separate agent process</li> <li>You don't want to bundle and distribute the ngrok agent</li> <li>The ngrok agent doesn't run on your target platform</li> <li>The ngrok agent's resource requirements are too high for your target platform</li> <li>You want fine-grained programmatic control over the agent's functionality</li> </ul> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="changelog">Changelog<a href="#changelog" class="hash-link" aria-label="Direct link to Changelog" title="Direct link to Changelog"></a></h2> <p>We publish the <a href="/docs/agent/changelog/">ngrok agent changelog</a> with details on each release of the ngrok agent.</p> <h2 class="anchor anchorWithStickyNavbar_qeIy" id="pricing">Pricing<a href="#pricing" class="hash-link" aria-label="Direct link to Pricing" title="Direct link to Pricing"></a></h2> <p>The ngrok agent is available to all ngrok users at no additional charge. You only incur costs if the resources provisioned by the agent incur a cost. For more information, see the <a href="https://ngrok.com/pricing" target="_blank" rel="noopener noreferrer">ngrok Pricing page</a>.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col"><a href="https://github.com/ngrok/ngrok-docs/edit/main/docs/agent/index.mdx" target="_blank" rel="noopener noreferrer" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_pNyv" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_wOM1"><span class="theme-last-updated">Last updated<!-- --> on <b><time datetime="2024-11-26T19:41:31.000Z" itemprop="dateModified">Nov 26, 2024</time></b> by <b>samcrichard</b></span></div></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/tcp/traffic-policy/actions/restrict-ips/"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Restrict IPs</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/agent/web-inspection-interface/"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Web Inspection Interface</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_iEsB thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#overview" class="table-of-contents__link toc-highlight">Overview</a></li><li><a href="#install" class="table-of-contents__link toc-highlight">Install</a></li><li><a href="#example-usage" class="table-of-contents__link toc-highlight">Example Usage</a><ul><li><a href="#http-endpoint" class="table-of-contents__link toc-highlight">HTTP Endpoint</a></li><li><a href="#static-domain" class="table-of-contents__link toc-highlight">Static Domain</a></li><li><a href="#basic-auth" class="table-of-contents__link toc-highlight">Basic Auth</a></li><li><a href="#forward-to-non-local" class="table-of-contents__link toc-highlight">Forward to non-local</a></li><li><a href="#local-https-server" class="table-of-contents__link toc-highlight">Local HTTPS Server</a></li><li><a href="#forwarding-to-ipv6-address" class="table-of-contents__link toc-highlight">Forwarding to IPv6 Address</a></li><li><a href="#tcp-endpoint" class="table-of-contents__link toc-highlight">TCP Endpoint</a></li><li><a href="#tls-endpoint" class="table-of-contents__link toc-highlight">TLS Endpoint</a></li><li><a href="#multiple-endpoints" class="table-of-contents__link toc-highlight">Multiple Endpoints</a></li></ul></li><li><a href="#tab-completion" class="table-of-contents__link toc-highlight">Tab Completion</a></li><li><a href="#authtokens" class="table-of-contents__link toc-highlight">Authtokens</a></li><li><a href="#authtoken-acls" class="table-of-contents__link toc-highlight">Authtoken ACLs</a></li><li><a href="#api-keys" class="table-of-contents__link toc-highlight">API Keys</a></li><li><a href="#configuration-file" class="table-of-contents__link toc-highlight">Configuration File</a></li><li><a href="#environment-variables" class="table-of-contents__link toc-highlight">Environment Variables</a></li><li><a href="#background-service" class="table-of-contents__link toc-highlight">Running ngrok in the background</a></li><li><a href="#remote-management" class="table-of-contents__link toc-highlight">Remote Management</a></li><li><a href="#connectivity" class="table-of-contents__link toc-highlight">Connectivity</a><ul><li><a href="#connectivity-address" class="table-of-contents__link toc-highlight">Address</a></li><li><a href="#additional-urls" class="table-of-contents__link toc-highlight">Additional URLs</a></li><li><a href="#dns-resolution" class="table-of-contents__link toc-highlight">DNS Resolution</a></li><li><a href="#tls-verification" class="table-of-contents__link toc-highlight">TLS Verification</a></li><li><a href="#heartbeats" class="table-of-contents__link toc-highlight">Heartbeats</a></li><li><a href="#reconnection" class="table-of-contents__link toc-highlight">Reconnection</a></li><li><a href="#troubleshooting-connectivity" class="table-of-contents__link toc-highlight">Troubleshooting</a></li></ul></li><li><a href="#system-requirements" class="table-of-contents__link toc-highlight">System Requirements</a></li><li><a href="#updates" class="table-of-contents__link toc-highlight">Updates</a></li><li><a href="#ip-restrictions" class="table-of-contents__link toc-highlight">IP Restrictions</a></li><li><a href="#api" class="table-of-contents__link toc-highlight">API</a></li><li><a href="#using-ngrok-without-the-agent" class="table-of-contents__link toc-highlight">Using ngrok without the agent</a></li><li><a href="#changelog" class="table-of-contents__link toc-highlight">Changelog</a></li><li><a href="#pricing" class="table-of-contents__link toc-highlight">Pricing</a></li></ul></div></div></div></div></main></div></div></div><footer class="footer"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">ngrok Service</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs/getting-started/">Get Started</a></li><li class="footer__item"><a href="https://dashboard.ngrok.com/signup" target="_blank" rel="noopener noreferrer" class="footer__link-item">Sign up</a></li><li class="footer__item"><a href="https://dashboard.ngrok.com/login" target="_blank" rel="noopener noreferrer" class="footer__link-item">Log in</a></li><li class="footer__item"><a href="https://download.ngrok.com" target="_blank" rel="noopener noreferrer" class="footer__link-item">Download</a></li><li class="footer__item"><a href="https://ngrok.com/docs" target="_blank" rel="noopener noreferrer" class="footer__link-item">Docs</a></li><li class="footer__item"><a href="https://status.ngrok.com" target="_blank" rel="noopener noreferrer" class="footer__link-item">Status</a></li></ul></div><div class="col footer__col"><div class="footer__title">ngrok.com</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://ngrok.com/product" target="_blank" rel="noopener noreferrer" class="footer__link-item">Product</a></li><li class="footer__item"><a href="https://ngrok.com/pricing" target="_blank" rel="noopener noreferrer" class="footer__link-item">Pricing</a></li><li class="footer__item"><a href="https://ngrok.com/customers" target="_blank" rel="noopener noreferrer" class="footer__link-item">Customers</a></li><li class="footer__item"><a href="https://ngrok.com/solutions" target="_blank" rel="noopener noreferrer" class="footer__link-item">Solutions</a></li><li class="footer__item"><a href="https://ngrok.com/partners" target="_blank" rel="noopener noreferrer" class="footer__link-item">Partners</a></li><li class="footer__item"><a href="https://trust.ngrok.com" target="_blank" rel="noopener noreferrer" class="footer__link-item">Trust Portal</a></li></ul></div><div class="col footer__col"><div class="footer__title">Legal</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://ngrok.com/abuse" target="_blank" rel="noopener noreferrer" class="footer__link-item">Abuse</a></li><li class="footer__item"><a href="https://ngrok.com/dpa" target="_blank" rel="noopener noreferrer" class="footer__link-item">DPA</a></li><li class="footer__item"><a href="https://ngrok.com/privacy" target="_blank" rel="noopener noreferrer" class="footer__link-item">Privacy</a></li><li class="footer__item"><a href="https://ngrok.com/security" target="_blank" rel="noopener noreferrer" class="footer__link-item">Security</a></li><li class="footer__item"><a href="https://ngrok.com/tos" target="_blank" rel="noopener noreferrer" class="footer__link-item">Terms of service</a></li><li class="footer__item"><a href="https://ngrok.com/privacy-preferences" target="_blank" rel="noopener noreferrer" class="footer__link-item">Privacy Preferences</a></li></ul></div><div class="col footer__col"><div class="footer__title">More</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://ngrok.com/careers" target="_blank" rel="noopener noreferrer" class="footer__link-item">Careers</a></li><li class="footer__item"><a href="https://blog.ngrok.com" target="_blank" rel="noopener noreferrer" class="footer__link-item">Blog</a></li><li class="footer__item"><a href="https://ngrok.com/slack" target="_blank" rel="noopener noreferrer" class="footer__link-item">Community</a></li><li class="footer__item"><a href="https://twitter.com/ngrokHQ" target="_blank" rel="noopener noreferrer" class="footer__link-item">Twitter</a></li><li class="footer__item"><a href="https://www.linkedin.com/company/ngrok" target="_blank" rel="noopener noreferrer" class="footer__link-item">LinkedIn</a></li><li class="footer__item"><a href="https://github.com/ngrok" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub</a></li></ul></div></div><div class="footer__bottom text--center"><div class="footer__copyright">© ngrok 2024</div></div></div></footer></div> </body> </html>