---
title: Getting Started
sidebar_label: Getting Started
sidebar_position: 10
---

import { AssetsProvider } from '@site/src/components/assets-context';
import DownloadCard from '@site/src/components/download-card';
import DownloadCardStyles from '@site/src/css/download-card.module.css';
import InstallCards from '/../docs/guides/install/_install_cards.mdx';

## Your Secure Internet Sharing Perimeter

`zrok` (*/ziːɹɒk/ ZEE-rock*) 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 [myzrok.io](https://myzrok.io) with a generous free tier.

## What's it for?

Use `zrok` to share a running service, like a web server or a network socket, or to share a directory of static files. `zrok` goes beyond simple tunneling to provide sharing solutions for a variety of network and storage use cases.

When using `zrok` to [share publicly](./concepts/sharing-public.mdx), you can reserve a public hostname, enable authentication options, or both. Public shares proxy HTTPS to your service or files.

If [sharing privately](./concepts/sharing-private.mdx), only users with the share token (and the appropriate permission grants) can access your share. In addition to what you can share publicly, private shares can include TCP and UDP services.

Here's a quick overview of what's involved in getting started with `zrok`:

### Your First Share

1. Get an account token
<Columns className='text--center getting-started-cards' style={{marginLeft: 1}}>
    <Column style={{paddingBottom: 20}}>
        <Card shadow='tl'>
            <CardHeader>
                <h3>Hosted zrok</h3>
            </CardHeader>
            <CardBody>
                Use NetFoundry's public zrok instance.
            </CardBody>
            <CardFooter>
                <a href="https://myzrok.io/">
                    <button className='button button--secondary button--block'>Get an Account</button>
                </a>
            </CardFooter>
        </Card>
    </Column>
    <Column style={{paddingBottom: 20}}>
        <Card shadow='tl'>
            <CardHeader>
               <h3>Self-Hosted zrok</h3>
            </CardHeader>
            <CardBody>
                Run a zrok instance on Linux, Docker, or Kubernetes.
            </CardBody>
            <CardFooter>
                <a href="/docs/category/self-hosting/">
                    <button className='button button--secondary button--block'>Guides</button>
                </a>
            </CardFooter>
        </Card>
    </Column>
</Columns>

2. [Download the zrok binary](#installing-the-zrok-command)
3. Enable zrok for your [environment](#enabling-your-zrok-environment)

    ```bash
    zrok enable <your_account_token>
    ```

4. Share `http://localhost:8080`

    ```bash
    zrok share public 8080
    ```

5. Visit the public URL displayed in your terminal

    ![zrok share public](images/zrok-share-public.png)

# A Deeper Look at Getting Started

Here's a deeper, more thorough look at getting started with `zrok`:

## Installing the zrok Command

<InstallCards />

## Enabling Your zrok Environment

After you have [an account](#your-first-share), you can enable your `zrok` environment.

A zrok environment usually refers to an enabled device where shares and accesses can be created, .e.g., `~/.zrok` on a Unix machine. It can be a specific user's environment or a system-wide agent's environment owned by the administrator.

When your `zrok` account was created, the service generated an _account token_ that identifies and authenticates in a single step. Protect your account token as if it were a password, or an important account number; it's a _secret_, protect it.

When we left off you had downloaded, extracted, and configured your `zrok` software. In order to use that environment with your account, you'll need to `enable` an _environment_ on your system. Enabling an environment generates a secure identity and the necessary underlying security policies with the OpenZiti network hosting the `zrok` service so that you can begin sharing.

Log into the API console at:

[https://api-v1.zrok.io/](https://api-v1.zrok.io/)

When you first log into your account on the API console, your interface will look like this:

![zrok API console, empty](images/zrok-getting-started-button.png)

In the toolbar, there is a big green button that says "CLICK HERE TO GET STARTED!". If you click that button, you'll see the getting started wizard, which looks like this:

![zrok getting started modal](images/zrok-getting-started-modal.png)

This wizard is broken into multiple steps. The first step we've already covered, which gets the zrok software installed onto your system.

Below "step 2" is a command: `zrok enable 7g3K6gVKikWb` (your account will have a different account token, other than `7g3K6gVKikWb`). You'll want to copy this command into your shell and execute it:

```txt
$ zrok enable 7g3K6gVKikWb 
⣻  contacting the zrok service...
```

After a few seconds, the message will change and indicate that the enable operation succeeded:

```txt
$ zrok enable 7g3K6gVKikWb 
⣻  the zrok environment was successfully enabled...
```

Now, if we run a `zrok status` command, you will see the details of your environment:

```txt
$ zrok status

Config:

 CONFIG           VALUE                   SOURCE 
 apiEndpoint      https://api-v1.zrok.io  env    
 defaultFrontend  public                  binary 
 headless         false                   binary 

Environment:

 PROPERTY       VALUE   
 Account Token  <<SET>> 
 Ziti Identity  <<SET>> 
```

Excellent... our environment is now fully enabled.

If we return to the _API console_, we'll now see the new environment reflected in the API console visualizer:

![New Environment in Web UI](images/zrok-visualizer-enabled.png)

In my case, the environment is named `michael@testing`, which is the username of my shell and the hostname of the system the shell is running on.

:::note
Should you want to use a non-default name for your environment, you can pass the `-d` option to the `zrok enable` command. See `zrok enable --help` for details.
:::

If you click on the environment node in the explorer in the _web console_, the details panel shown at the bottom of the page will change:

![Empty Environment](images/zrok-visualizer-environment.png)

The visualizer 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 visualizer, click the ![Zoom to Fit](images/zrok-zoom-to-fit.png) _zoom to fit_ icon in the lower right corner of the explorer.

:::note
With your `zrok` account you can `zrok enable` multiple environments. This will allow you to share (and access your shares) from multiple environments simultaneously.
:::

Your environment is fully ready to go. Now we can move on to the fun stuff...

## Sharing

`zrok` is designed to make sharing resources as effortless as possible, while providing a high degree of security and control.

### Ephemeral by Default

Shared resources are _ephemeral_ by default; as soon as you terminate the `zrok share` 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.

### Public Shares and Frontends

Resources that are shared _publicly_ are exposed to any users on the internet who have access to the `zrok` instance's "frontend".

A frontend is an HTTPS listener exposed to the internet, that lets any user with your ephemeral share token access your publicly shared resources.

For example, I might create a public share using the `zrok share public` command, which results in my `zrok` instance exposing a URL like `https://xxr2b7tzfx64.share.zrok.io` to access my resources.

```
$ zrok share public --backend-mode web .
```

In this case, my share was given the "share token" of `xxr2b7tzfx64`. 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.

If we return to the web console, we see our share in the explorer:

![Web Console Share](images/zrok-visualizer-public-share.png)

If we click on the _frontend endpoint_ a new browser tab opens and we see the content of our share:
![Share Frontend](images/zrok_web_console_share_frontend.png)

When we start accessing our share, notice the _sparkline_ graphs showing the activity:

![Environment Spark Line](images/zrok-visualizer-sparklines.png)

And as soon as I terminate the `zrok share` client, the resources are removed from the `zrok` environment.

If we try to reload the frontend endpoint in our web browser, we'll see:

![Not Found](images/zrok-not-found.png)

[More about public shares](/concepts/sharing-public.mdx)

### Private Shares

`zrok` also provides a powerful _private_ sharing model. If I execute the following command:

```buttonless
$ zrok share private http://localhost:8080
```

The `zrok` service will respond with the following:

```buttonless title="Output"
access your share with: zrok access private wvszln4dyz9q
```

Rather than allowing access to your service through a public frontend, a _private_ share is only exposed to the underlying OpenZiti network, and can only be accessed using the `zrok access` command.

The `zrok access private wvszln4dyz9q` command can be run by any `zrok` user, allowing them to create and bind a local HTTP listener, that allows for private access to your shared resources.

[More about private shares](/concepts/sharing-private.mdx)

### Proxy Backend Mode

Without specifying a _backend mode_, the `zrok share` command will assume that you're trying to share a `proxy` resource. A `proxy` 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 `localhost`, or only listening on a private LAN segment behind a firewall. 

For these services a `proxy` share will allow those endpoints to be reached, either _publicly_ or _privately_ through the `zrok` service.

### Web Backend Mode

The `zrok share` command accepts a `--backend-mode` option. Besides `proxy`, the current `v0.3` release (as of this writing) also supports a `web` mode. The `web` mode allows you to specify a local folder on your filesystem, and instantly turns your `zrok` client into a web server, exposing your web content either _publicly_ or _privately_ without having to a configure a web server.

### Reserved Shares

`zrok` shares are _ephemeral_ unless you specifically create a "reserved" share.

A reserved share can be re-used multiple times; it will survive termination of the `zrok share` command, allowing for longer-lasting semi-permanent access to shared resources.

The first step is to create the reserved share:

```txt
$ zrok reserve public --backend-mode web v0.3_getting_started
[   0.275]    INFO main.(*reserveCommand).run: your reserved share token is 'mltwsinym1s2'
[   0.275]    INFO main.(*reserveCommand).run: reserved frontend endpoint: https://mltwsinym1s2.share.zrok.io
```

I'm asking the `zrok` service to reserve a share with a `web` backend mode, pointing at my local `docs` folder.

You'll want to remember the share token (`mltwsinym1s2` in this case), and the frontend endpoint URL. If this were a _private_ reserved share, there would not be a frontend URL.

If we do nothing else, and then point a web browser at the frontend endpoint, we get:

![Not Found](images/zrok-reserved-not-found.png)

This is the `404` error message returned by the `zrok` frontend. We're getting this because we haven't yet started up a `zrok share` for the service. Let's do that:

This command:

```txt
$ zrok share reserved mltwsinym1s2
```

...results in a new share backend starting up and connecting to the existing reserved share:

![zrok share reserved](images/zrok_share_reserved.png)

And now if we refresh the frontend endpoint URL in the web browser, we'll see an index of the `docs` directory:

![zrok docs share](images/zrok_web_console_share_frontend.png)

With the reserved share, we're free to stop and restart the `zrok share reserved` command as many times as we want, without losing the token for our share.

When we're done with the reserved share, we can _release_ it using this command:

```txt
$ zrok release mltwsinym1s2
[   0.230]    INFO main.(*releaseCommand).run: reserved share 'mltwsinym1s2' released
```

[More about reserved shares](/concepts/sharing-reserved.md)

## Concepts Review

In summary, `zrok` lets you easily and securely share resources with both general internet users (through _public_ sharing) and also with other `zrok` users (through _private_ sharing).

Here's a quick review of the `zrok` mental model and the vocabulary.

### Instance and Account

You create an _account_ with a `zrok` _instance_. Your account is identified by a username and a password, which you use to log into the _web console_. Your account also has a _secret token_, which you will use to authenticate from the `zrok` command-line to interact with the _instance_.

You create a new _account_ with NetFoundry's `zrok` _instance_ by subscribing in [myzrok.io](https://myzrok.io) or in a self-hosted `zrok` _instance_ by running [the `zrok invite` command](/guides/self-hosting/self-service-invite.mdx) or the `zrok admin create account` command.

### Environment

Using your _secret token_ you use the `zrok` command-line interface to create an _environment_. An _environment_ corresponds to a single command-line user on a specific _host system_. 

You create a new _environment_ by using the `zrok enable` command.

### Shares

Once you've enabled an _environment_, you then create one or more _shares_. Shares have either a _public_ or _private_ _sharing mode_. _Shares_ share a specific type of resource using a _backend mode_. As of this writing `zrok` supports a `proxy` _backend mode_ to share local HTTP resources as a _reverse proxy_. `zrok` also supports a `web` _backend mode_ to share local file and HTML resources by enabling a basic HTTP server.

Every _share_ is identified by a _share token_. _Public shares_ can be accessed through either a _frontend_ instance offered through the `zrok` _instance_, or through the `zrok access` command. _Private shares_ can only be accessed through the `zrok access` command.

You use the `zrok share` command to create and enable _ephemeral shares_.

### Reserved Shares

`zrok` supports creating _shares_ that have a consistent _share token_ that survives restarts of the `zrok share` command. These are considered _non-ephemeral_, and is callled a _reserved share_.

You use the `zrok reserve` command to create _reserved shares_. Reserved shares last until you use the `zrok release` command to delete them.

## Self-Hosting an Instance

Interested in self-hosting your own `zrok` instance? See the [self-hosting guides](/docs/category/self-hosting/)!

## Resources

- Learn about [OpenZiti](https://openziti.io/)
