<titledata-rh="true">Getting Started with zrok | Zrok</title><metadata-rh="true"name="viewport"content="width=device-width,initial-scale=1"><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://docs.zrok.io/docs/getting-started/"><metadata-rh="true"property="og:locale"content="en"><metadata-rh="true"name="docusaurus_locale"content="en"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docusaurus_version"content="current"><metadata-rh="true"name="docusaurus_tag"content="docs-default-current"><metadata-rh="true"name="docsearch:version"content="current"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-current"><metadata-rh="true"property="og:title"content="Getting Started with zrok | Zrok"><metadata-rh="true"name="description"content="What's a zrok?"><metadata-rh="true"property="og:description"content="What's a zrok?"><linkdata-rh="true"rel="icon"href="/img/space-ziggy.png"><linkdata-rh="true"rel="canonical"href="https://docs.zrok.io/docs/getting-started/"><linkdata-rh="true"rel="alternate"href="https://docs.zrok.io/docs/getting-started/"hreflang="en"><linkdata-rh="true"rel="alternate"href="https://docs.zrok.io/docs/getting-started/"hreflang="x-default"><linkdata-rh="true"rel="preconnect"href="https://CO73R59OLO-dsn.algolia.net"crossorigin="anonymous"><linkrel="preconnect"href="https://www.googletagmanager.com">
<p><code>zrok</code> (<em>/ziːɹɒk/ ZEE-rock</em>) is a secure, open-source, self-hostable sharing platform that simplifies shielding and sharing network services or files. There's a hardened zrok-as-a-service offering available at <ahref="https://zrok.io"target="_blank"rel="noopener noreferrer">zrok.io</a> with a generous free tier.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="open-source">Open Source<ahref="#open-source"class="hash-link"aria-label="Direct link to Open Source"title="Direct link to Open Source"></a></h2>
<p><code>zrok</code> is licensed under Apache 2.0.</p>
<p>Check <ahref="https://github.com/orgs/openziti/projects/16"target="_blank"rel="noopener noreferrer">the roadmap</a> if you're thinking about the future. We would love to hear your ideas for <code>zrok</code>!</p>
<p>The best ways to engage are <ahref="https://openziti.discourse.group/"target="_blank"rel="noopener noreferrer">Discourse</a> for questions and <ahref="https://github.com/openziti/zrok/issues"target="_blank"rel="noopener noreferrer">GitHub Issues</a> for documenting problems.</p>
<p><ahref="/docs/concepts/opensource/">Read more about zrok open source</a>.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="ziti-native">Ziti native<ahref="#ziti-native"class="hash-link"aria-label="Direct link to Ziti native"title="Direct link to Ziti native"></a></h3>
<p><code>zrok</code> is a <em>Ziti Native Application</em>, built on the <ahref="https://openziti.io"target="_blank"rel="noopener noreferrer">OpenZiti</a> platform, and supported by the OpenZiti community and NetFoundry team.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="whats-it-for">What's it for?<ahref="#whats-it-for"class="hash-link"aria-label="Direct link to What's it for?"title="Direct link to What's it for?"></a></h2>
<p>Use <code>zrok</code> to share a running service, like a web server or a network socket, or to share a directory of static files.</p>
<p>If <ahref="/docs/concepts/sharing-public/">sharing publicly</a>, you can reserve a subdomain, enable authentication options, or both. Public shares proxy HTTPS to your service or files.</p>
<p>If <ahref="/docs/concepts/sharing-private/">sharing privately</a>, only users with the share token can access your share. In addition to what you can share publicly, private shares can include TCP and UDP services.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="installing-the-zrok-command">Installing the zrok Command<ahref="#installing-the-zrok-command"class="hash-link"aria-label="Direct link to Installing the zrok Command"title="Direct link to Installing the zrok Command"></a></h2>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="generating-an-invitation">Generating an Invitation<ahref="#generating-an-invitation"class="hash-link"aria-label="Direct link to Generating an Invitation"title="Direct link to Generating an Invitation"></a></h2>
<divclass="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><divclass="admonitionHeading_Gvgb"><spanclass="admonitionIcon_Rf37"><svgviewBox="0 0 14 16"><pathfill-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><divclass="admonitionContent_BuS1"><p>If not using <code>zrok.io</code> (zrok-as-a-service), you must configure the <code>zrok</code> command to use your instance. See the <ahref="/docs/guides/self-hosting/instance-configuration/">instance configuration guide</a> in the self-hosting section for details.</p></div></div>
<p>Invite yourself to <code>zrok</code> by running the <code>zrok invite</code> command:</p>
<divclass="language-buttonless codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockTitle_Ktv7">Output</div><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-buttonless codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">enter and confirm your email address...</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"style="display:inline-block"></span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">> user@domain.com</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">> user@domain.com</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"style="display:inline-block"></span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ Submit ]</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"style="display:inline-block"></span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">invitation sent to 'user@domain.com'!</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="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><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="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>The <code>zrok invite</code> command presents a small form that allows you to enter (and then confirm) your email address. Tabbing to the <code>[ Submit ]</code> button will send the request to your configured <code>zrok</code> service.</p>
<p>Next, check the email where you sent the invite. You should receive a message asking you to click a link to create your <code>zrok</code> account. When you click that link, you will be brought to a web page that will allow you to set a password for your new account:</p>
<p><imgloading="lazy"alt="Enter a Password"src="/assets/images/zrok_verify-22a26d401b9a77a4278f3c0f54d2a981.png"width="1791"height="1362"class="img_ev3q"></p>
<p>Enter a password and its confirmation, and click the <code>Register Account</code> button. You'll see the following:</p>
<p>Congratulations! Your <code>zrok</code> account is ready to go!</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="enabling-your-zrok-environment">Enabling Your zrok Environment<ahref="#enabling-your-zrok-environment"class="hash-link"aria-label="Direct link to Enabling Your zrok Environment"title="Direct link to Enabling Your zrok Environment"></a></h2>
<p>When your <code>zrok</code> account was created, the service generated a <em>secret token</em> that identifies and authenticates in a single step. Protect your secret token as if it were a password, or an important account number; it's a <em>secret</em>, protect it.</p>
<p>When we left off you had downloaded, extracted, and configured your <code>zrok</code> environment. In order to use that environment with your account, you'll need to <code>enable</code> it. Enabling an environment generates a secure identity and the necessary underlying security policies with the OpenZiti network hosting the <code>zrok</code> service.</p>
<p>From the web console, click on your email address in the upper right corner of the header. That drop down menu contains an <code>Enable Your Environment</code> link. Click that link and a modal dialog will be shown like this:</p>
<p>This dialog box shows you the <code>zrok enable</code> command that you can use to enable any shell to work with your <code>zrok</code> account with a single command.</p>
<p>Let's copy that command and paste it into your shell:</p>
<p>Excellent... our environment is now fully enabled.</p>
<p>If we return to the <em>web console</em>, we'll now see the new environment reflected in the explorer view:</p>
<p><imgloading="lazy"alt="New Environment in Web UI"src="/assets/images/zrok_web_ui_new_environment-414d8e8fc25b09f257cb40ba47d6acbb.png"width="1791"height="1369"class="img_ev3q"></p>
<p>In my case, the environment is named <code>michael@ziti-lx</code>, which is the username of my shell and the hostname of the system the shell is running on.</p>
<divclass="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><divclass="admonitionHeading_Gvgb"><spanclass="admonitionIcon_Rf37"><svgviewBox="0 0 14 16"><pathfill-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><divclass="admonitionContent_BuS1"><p>Should you want to use a non-default name for your environment, you can pass the <code>-d</code> option to the <code>zrok enable</code> command. See <code>zrok enable --help</code> for details.</p></div></div>
<p>If you click on the environment node in the explorer in the <em>web console</em>, the details panel shown at the bottom of the page will change:</p>
<p>The explorer supports clicking, dragging, mouse wheel zooming, and selecting the nodes in the graph for more information (and available actions) for the selected node. If you ever get lost in the explorer, click the <imgloading="lazy"alt="Zoom to Fit"src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAB4AAAAZCAIAAACpVwlNAAAEr2lUWHRYTUw6Y29tLmFkb2JlLnhtcAAAAAAAPD94cGFja2V0IGJlZ2luPSLvu78iIGlkPSJXNU0wTXBDZWhpSHpyZVN6TlRjemtjOWQiPz4KPHg6eG1wbWV0YSB4bWxuczp4PSJhZG9iZTpuczptZXRhLyIgeDp4bXB0az0iWE1QIENvcmUgNS41LjAiPgogPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4KICA8cmRmOkRlc2NyaXB0aW9uIHJkZjphYm91dD0iIgogICAgeG1sbnM6dGlmZj0iaHR0cDovL25zLmFkb2JlLmNvbS90aWZmLzEuMC8iCiAgICB4bWxuczpleGlmPSJodHRwOi8vbnMuYWRvYmUuY29tL2V4aWYvMS4wLyIKICAgIHhtbG5zOnBob3Rvc2hvcD0iaHR0cDovL25zLmFkb2JlLmNvbS9waG90b3Nob3AvMS4wLyIKICAgIHhtbG5zOnhtcD0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wLyIKICAgIHhtbG5zOnhtcE1NPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvbW0vIgogICAgeG1sbnM6c3RFdnQ9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZUV2ZW50IyIKICAgdGlmZjpJbWFnZUxlbmd0aD0iMjUiCiAgIHRpZmY6SW1hZ2VXaWR0aD0iMzAiCiAgIHRpZmY6UmVzb2x1dGlvblVuaXQ9IjIiCiAgIHRpZmY6WFJlc29sdXRpb249Ijk2LzEiCiAgIHRpZmY6WVJlc29sdXRpb249Ijk2LzEiCiAgIGV4aWY6UGl4ZWxYRGltZW5zaW9uPSIzMCIKICAgZXhpZjpQaXhlbFlEaW1lbnNpb249IjI1IgogICBleGlmOkNvbG9yU3BhY2U9IjEiCiAgIHBob3Rvc2hvcDpDb2xvck1vZGU9IjMiCiAgIHBob3Rvc2hvcDpJQ0NQcm9maWxlPSJzUkdCIElFQzYxOTY2LTIuMSIKICAgeG1wOk1vZGlmeURhdGU9IjIwMjMtMDEtMTlUMTA6NTY6NTYtMDU6MDAiCiAgIHhtcDpNZXRhZGF0YURhdGU9IjIwMjMtMDEtMTlUMTA6NTY6NTYtMDU6MDAiPgogICA8eG1wTU06SGlzdG9yeT4KICAgIDxyZGY6U2VxPgogICAgIDxyZGY6bGkKICAgICAgc3RFdnQ6YWN0aW9uPSJwcm9kdWNlZCIKICAgICAgc3RFdnQ6c29mdHdhcmVBZ2VudD0iQWZmaW5pdHkgUGhvdG8gMi4wLjMiCiAgICAgIHN0RXZ0OndoZW49IjIwMjMtMDEtMTlUMTA6NTY6NTYtMDU6MDAiLz4KICAgIDwvcmRmOlNlcT4KICAgPC94bXBNTTpIaXN0b3J5PgogIDwvcmRmOkRlc2NyaXB0aW9uPgogPC9yZGY6UkRGPgo8L3g6eG1wbWV0YT4KPD94cGFja2V0IGVuZD0iciI/Pq+HLHgAAAGBaUNDUHNSR0IgSUVDNjE5NjYtMi4xAAAokXWRy0tCQRSHP7UwemBQixYtJKyVRg8Q27RQyoJqYQZZbfTmI/BxuVcJaRu0FQqiNr0W9RfUNmgdBEURRNtaF7UpuZ2rghF5hjnzzW/OOcycAWs4rWT0piHIZPNaKOh3LkaWnPYXLHThwIclqujq7PxkmIb2eS/RYrces1bjuH+tbTWuK2BpER5XVC0vPCU8s55XTd4R7lZS0VXhM2G3JhcUvjP1WJVfTU5W+dtkLRwKgLVT2Jn8xbFfrKS0jLC8HFcmXVBq9zFf0h7PLszL2iezF50QQfw4mWaCAF6GGRPvxcMIg7KjQf5QJX+OnOQq4lWKaKyRJEUet6gFqR6XNSF6XEaaotn/v33VE6Mj1ertfmh+Noz3frBvQ7lkGF9HhlE+BtsTXGbr+blD8H2IXqprrgNwbML5VV2L7cLFFvQ8qlEtWpFsMq2JBLydQkcEum6gdbnas9o5Jw8Q3pCvuoa9fRiQeMfKD2DYZ+PDGzxnAAAACXBIWXMAAA7EAAAOxAGVKw4bAAABZklEQVRIie2VvW7CMBDHr1UfwE5fII7lvahIWUEiQ7qxMLEwsVQMSB0YKsTExsDGxFs0QyqlYyMVld3k4wWw/QgMlqp+JXFQGZB649n3k+9/f9sX9w+PcJq4PBH3H/0zrkrWfK99jVF5/V6qIIzqod1m485rC6nK0S5GAPArvRDNHFtINZ0vviQp4Un2OTObjIs6q6G122yMhgPfaxvuN0VbGDHHBgDm2FbVAGqgLYyEVPFmCwDB84uQilHyB2i32ej3uoySvZDT+YInGaPE77QqlSkznz5vv9cFAEbJdL4QUlkYjYYDnYnf3o9HC6mewog5ttZBq7xcrf1OK95sy61ZgQaAIIx2lGgdRsPBcrXmSbYXstLyRmPkSWZh5HdaAODe3uipVlaZmk9IxdMcAHiam3DBRJCPCMJol+bfbuMxaJ7mjJLZZFxeb2Gku6mDTrJXjExeviILFqJF8WtpGOf5y5wn+gBcXI4F9z6rgwAAAABJRU5ErkJggg=="width="30"height="25"class="img_ev3q"><em>zoom to fit</em> icon in the lower right corner of the explorer.</p>
<p>If we click on the <code>Detail</code> tab for our environment, we'll see something like:</p>
<divclass="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><divclass="admonitionHeading_Gvgb"><spanclass="admonitionIcon_Rf37"><svgviewBox="0 0 14 16"><pathfill-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><divclass="admonitionContent_BuS1"><p>With your <code>zrok</code> account you can <code>zrok enable</code> multiple environments. This will allow you to run <code>zrok share</code> in one environment, and <code>zrok access</code> in other environments.</p></div></div>
<p>Your environment is fully ready to go. Now we can move on to the fun stuff...</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="sharing">Sharing<ahref="#sharing"class="hash-link"aria-label="Direct link to Sharing"title="Direct link to Sharing"></a></h2>
<p><code>zrok</code> is designed to make sharing resources as effortless as possible, while providing a high degree of security and control.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="ephemeral-by-default">Ephemeral by Default<ahref="#ephemeral-by-default"class="hash-link"aria-label="Direct link to Ephemeral by Default"title="Direct link to Ephemeral by Default"></a></h3>
<p>Shared resources are <em>ephemeral</em> by default; as soon as you terminate the <code>zrok share</code> command, the entire share is removed and is no longer available to any users. Identifiers for shared resources are randomly allocated when the share is created.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="public-shares-and-frontends">Public Shares and Frontends<ahref="#public-shares-and-frontends"class="hash-link"aria-label="Direct link to Public Shares and Frontends"title="Direct link to Public Shares and Frontends"></a></h3>
<p>Resources that are shared <em>publicly</em> are exposed to any users on the internet who have access to the <code>zrok</code> instance's "frontend".</p>
<p>A frontend is an HTTPS listener exposed to the internet, that lets any user with your ephemeral share token access your publicly shared resources.</p>
<p>For example, I might create a public share using the <code>zrok share public</code> command, which results in my <code>zrok</code> instance exposing a URL like <code>https://2ptgbr8tlfvk.share.zrok.io</code> to access my resources.</p>
<p>In this case, my share was given the "share token" of <code>2ptgbr8tlfvk</code>. That URL can be given to any user, allowing them to immediately access the shared resources directly from my local environment, all without exposing any access to my private, secure environment. The physical network location of my environment is not exposed to anonymous consumers of my resources.</p>
<divclass="theme-admonition theme-admonition-note admonition_xJq3 alert alert--secondary"><divclass="admonitionHeading_Gvgb"><spanclass="admonitionIcon_Rf37"><svgviewBox="0 0 14 16"><pathfill-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><divclass="admonitionContent_BuS1"><p>Here is the <code>--help</code> output from <code>zrok share public</code>:</p><divclass="language-text codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">zrok share public</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="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><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><divclass="language-buttonless codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockTitle_Ktv7">Output</div><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-buttonless codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">Error: accepts 1 arg(s), received 0</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">Usage:</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> zrok share public <target> [flags]</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"style="display:inline-block"></span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">Flags:</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> --backend-mode string The backend mode {proxy, web, caddy, drive} (default "proxy")</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> --basic-auth stringArray Basic authentication users (<username:password>,...)</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> --frontends stringArray Selected frontends to use for the share (default [public])</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> --headless Disable TUI and run headless</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> -h, --help help for public</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"> --insecure Enable insecure TLS certificate validation for <target></span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"style="display:inline-block"></span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain"
<p>If we return to the web console, we see our share in the explorer:</p>
<p>If we click on the environment in the explorer, we're shown all of the shares for that environment (including our new share), along with a spark line that shows the activity:</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="private-shares">Private Shares<ahref="#private-shares"class="hash-link"aria-label="Direct link to Private Shares"title="Direct link to Private Shares"></a></h3>
<p><code>zrok</code> also provides a powerful <em>private</em> sharing model. If I execute the following command:</p>
<p>Rather than allowing access to your service through a public frontend, a <em>private</em> share is only exposed to the underlying OpenZiti network, and can only be accessed using the <code>zrok access</code> command.</p>
<p>The <code>zrok access private wvszln4dyz9q</code> command can be run by any <code>zrok</code> user, allowing them to create and bind a local HTTP listener, that allows for private access to your shared resources.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="proxy-backend-mode">Proxy Backend Mode<ahref="#proxy-backend-mode"class="hash-link"aria-label="Direct link to Proxy Backend Mode"title="Direct link to Proxy Backend Mode"></a></h3>
<p>Without specifying a <em>backend mode</em>, the <code>zrok share</code> command will assume that you're trying to share a <code>proxy</code> resource. A <code>proxy</code> resource is usually some private HTTP/HTTPS endpoint (like a development server, or a private application) running in your local environment. Usually such an endpoint would have no inbound connectivity except for however it is reachable from your local environment. It might be running on <code>localhost</code>, or only listening on a private LAN segment behind a firewall.</p>
<p>For these services a <code>proxy</code> share will allow those endpoints to be reached, either <em>publicly</em> or <em>privately</em> through the <code>zrok</code> service.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="web-backend-mode">Web Backend Mode<ahref="#web-backend-mode"class="hash-link"aria-label="Direct link to Web Backend Mode"title="Direct link to Web Backend Mode"></a></h3>
<p>The <code>zrok share</code> command accepts a <code>--backend-mode</code> option. Besides <code>proxy</code>, the current <code>v0.3</code> release (as of this writing) also supports a <code>web</code> mode. The <code>web</code> mode allows you to specify a local folder on your filesystem, and instantly turns your <code>zrok</code> client into a web server, exposing your web content either <em>publicly</em> or <em>privately</em> without having to a configure a web server.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="reserved-shares">Reserved Shares<ahref="#reserved-shares"class="hash-link"aria-label="Direct link to Reserved Shares"title="Direct link to Reserved Shares"></a></h3>
<p><code>zrok</code> shares are <em>ephemeral</em> unless you specifically create a "reserved" share.</p>
<p>A reserved share can be re-used multiple times; it will survive termination of the <code>zrok share</code> command, allowing for longer-lasting semi-permanent access to shared resources.</p>
<p>The first step is to create the reserved share:</p>
<divclass="language-txt codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><divclass="codeBlockTitle_Ktv7">Example</div><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-txt codeBlock_bY9V thin-scrollbar"style="color:#F8F8F2;background-color:#282A36"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">$ zrok reserve public --backend-mode web v0.3_getting_started</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.275] INFO main.(*reserveCommand).run: your reserved share token is 'mltwsinym1s2'</span><br></span><spanclass="token-line"style="color:#F8F8F2"><spanclass="token plain">[ 0.275] INFO main.(*reserveCommand).run: reserved frontend endpoint: https://mltwsinym1s2.share.zrok.io</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="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><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="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>I'm asking the <code>zrok</code> service to reserve a share with a <code>web</code> backend mode, pointing at my local <code>docs</code> folder.</p>
<p>You'll want to remember the share token (<code>mltwsinym1s2</code> in this case), and the frontend endpoint URL. If this were a <em>private</em> reserved share, there would not be a frontend URL.</p>
<p>If we do nothing else, and then point a web browser at the frontend endpoint, we get:</p>
<p>This is the <code>404</code> error message returned by the <code>zrok</code> frontend. We're getting this because we haven't yet started up a <code>zrok share</code> for the service. Let's do that:</p>
<p>With the reserved share, we're free to stop and restart the <code>zrok share reserved</code> command as many times as we want, without losing the token for our share.</p>
<p>When we're done with the reserved share, we can <em>release</em> it using this command:</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="concepts-review">Concepts Review<ahref="#concepts-review"class="hash-link"aria-label="Direct link to Concepts Review"title="Direct link to Concepts Review"></a></h2>
<p>In summary, <code>zrok</code> lets you easily and securely share resources with both general internet users (through <em>public</em> sharing) and also with other <code>zrok</code> users (through <em>private</em> sharing).</p>
<p>Here's a quick review of the <code>zrok</code> mental model and the vocabulary.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="instance-and-account">Instance and Account<ahref="#instance-and-account"class="hash-link"aria-label="Direct link to Instance and Account"title="Direct link to Instance and Account"></a></h3>
<p>You create an <em>account</em> with a <code>zrok</code><em>instance</em>. Your account is identified by a username and a password, which you use to log into the <em>web console</em>. Your account also has a <em>secret token</em>, which you will use to authenticate from the <code>zrok</code> command-line to interact with the <em>instance</em>.</p>
<p>You create a new <em>account</em> with a <code>zrok</code><em>instance</em> through the <code>zrok invite</code> command.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="environment">Environment<ahref="#environment"class="hash-link"aria-label="Direct link to Environment"title="Direct link to Environment"></a></h3>
<p>Using your <em>secret token</em> you use the <code>zrok</code> command-line interface to create an <em>environment</em>. An <em>environment</em> corresponds to a single command-line user on a specific <em>host system</em>.</p>
<p>You create a new <em>environment</em> by using the <code>zrok enable</code> command.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="shares">Shares<ahref="#shares"class="hash-link"aria-label="Direct link to Shares"title="Direct link to Shares"></a></h3>
<p>Once you've enabled an <em>environment</em>, you then create one or more <em>shares</em>. Shares have either a <em>public</em> or <em>private</em><em>sharing mode</em>. <em>Shares</em> share a specific type of resource using a <em>backend mode</em>. As of this writing <code>zrok</code> supports a <code>proxy</code><em>backend mode</em> to share local HTTP resources as a <em>reverse proxy</em>. <code>zrok</code> also supports a <code>web</code><em>backend mode</em> to share local file and HTML resources by enabling a basic HTTP server.</p>
<p>Every <em>share</em> is identified by a <em>share token</em>. <em>Public shares</em> can be accessed through either a <em>frontend</em> instance offered through the <code>zrok</code><em>instance</em>, or through the <code>zrok access</code> command. <em>Private shares</em> can only be accessed through the <code>zrok access</code> command.</p>
<p>You use the <code>zrok share</code> command to create and enable <em>ephemeral shares</em>.</p>
<h3class="anchor anchorWithStickyNavbar_LWe7"id="reserved-shares-1">Reserved Shares<ahref="#reserved-shares-1"class="hash-link"aria-label="Direct link to Reserved Shares"title="Direct link to Reserved Shares"></a></h3>
<p><code>zrok</code> supports creating <em>shares</em> that have a consistent <em>share token</em> that survives restarts of the <code>zrok share</code> command. These are considered <em>non-ephemeral</em>, and is callled a <em>reserved share</em>.</p>
<p>You use the <code>zrok reserve</code> command to create <em>reserved shares</em>. Reserved shares last until you use the <code>zrok release</code> command to delete them.</p>
<h2class="anchor anchorWithStickyNavbar_LWe7"id="self-hosting-an-instance">Self-Hosting an Instance<ahref="#self-hosting-an-instance"class="hash-link"aria-label="Direct link to Self-Hosting an Instance"title="Direct link to Self-Hosting an Instance"></a></h2>
