Merge branch 'main' into upgrade_doc

docs/_attic/sharing/sharing_modes.md

@@ -48,6 +48,6 @@ The following illustration shows the possibilities available.
 
 ![Frontend Selection](../../images/zrok_frontends_v0.3.png)
 
-The `*.in.zrok.io` frontend is a "public" frontend, available to all `zrok` users. Most `zrok` installations will want to have at least one public, global frontend for all public, internet-facing ingress traffic for private backend instances. In the underlying data store, the public frontend will have a `name` set to `public` (or some other representative name), allowing users to reference that `frontend` using a friendly label.
+The `*.share.zrok.io` frontend is a "public" frontend, available to all `zrok` users. Most `zrok` installations will want to have at least one public, global frontend for all public, internet-facing ingress traffic for private backend instances. In the underlying data store, the public frontend will have a `name` set to `public` (or some other representative name), allowing users to reference that `frontend` using a friendly label.
 
 The other two "private" frontends are configured with no `name` label (the lack of a `name` label signifies that these are "private" frontends). The ephemeral environment is allocated when a `zrok` frontend request is made without an account on behalf of a private share.

docs/concepts/sharing-reserved.md

@@ -16,16 +16,16 @@ To delete your `reserved` share use the `zrok release` command or click the dele
 
 ## Unique Names
 
-The default is to generate a random _share token_ and you may specify a _unique name_.
+The default is to generate a random _share token_ and you may instead specify a _unique name_. The unique name must be lowercase alphanumeric, between 4 and 32 characters in length.
 
-This reserves public share token "myshare."
+This reserves public share token "toaster".
 
 ```bash title="Reserve with the Command Line"
-zrok reserve public 80 --unique-name "myshare"
+zrok reserve public 80 --unique-name "toaster"
 ```
 
-This shares `127.0.0.1:80` as `https://myshare.zrok.example.com` where `https://{token}.zrok.example.com` is the frontend's template.
+This shares `127.0.0.1:80` as `https://toaster.zrok.example.com` where `https://{token}.zrok.example.com` is the frontend's template.
 
 ```bash title="Share a Reserved Token"
-zrok share reserved "myshare"
+zrok share reserved "toaster"
 ```

docs/getting-started.mdx

@@ -25,6 +25,16 @@ Use the command `zrok rebase apiEndpoint https://api-v1.zrok.io/` to update your
 `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
@@ -47,7 +57,7 @@ There's a hardened zrok-as-a-service offering available at [myzrok.io](https://m
     <Column style={{paddingBottom: 20}}>
         <Card shadow='tl'>
             <CardHeader>
-                <h3>Self-Hosted zrok</h3>
+               <h3>Self-Hosted zrok</h3>
             </CardHeader>
             <CardBody>
                 Run a zrok instance on Linux, Docker, or Kubernetes.
@@ -62,7 +72,7 @@ There's a hardened zrok-as-a-service offering available at [myzrok.io](https://m
 </Columns>
 
 2. [Download the zrok binary](#installing-the-zrok-command)
-3. Enable zrok for your [user environment](#enabling-your-zrok-environment)
+3. Enable zrok for your [environment](#enabling-your-zrok-environment)
 
     ```bash
     zrok enable <your_account_token>
@@ -76,41 +86,11 @@ There's a hardened zrok-as-a-service offering available at [myzrok.io](https://m
 
 5. Visit the public URL displayed in your terminal
 
-    ![zrok share public](images/zrok_share_public.png)
+    ![zrok share public](images/zrok-share-public.png)
 
-## Share Backend Modes
+# A Deeper Look at Getting Started
 
-zrok shares can be public or private, with different options for backend modes, including:
-
-* [Public shares](./concepts/sharing-public.mdx) for [web services](./concepts/http.md) or [files](./concepts/files.md)
-* [Private shares for web services or files](./concepts/sharing-private.mdx)
-* [TCP Tunnels](./concepts/tunnels.md)
-* [UDP Tunnels](./concepts/tunnels.md)
-* [File Drives](./guides/drives.mdx)
-* [VPN](./guides/vpn/vpn.md)
-
-
-## Open Source
-
-`zrok` is licensed under Apache 2.0.
-
-Check [the roadmap](https://github.com/orgs/openziti/projects/16) if you're thinking about the future. We would love to hear your ideas for `zrok`!
-
-The best ways to engage are [Discourse](https://openziti.discourse.group/) for questions and [GitHub Issues](https://github.com/openziti/zrok/issues) for documenting problems.
-
-[Read more about zrok open source](/concepts/opensource.md).
-
-### Ziti native
-
-`zrok` is a _Ziti Native Application_, built on the [OpenZiti](https://openziti.io) platform, and supported by the OpenZiti community and NetFoundry team.
-
-## 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.
-
-If [sharing publicly](./concepts/sharing-public.mdx), you can reserve a subdomain, 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 can access your share. In addition to what you can share publicly, private shares can include TCP and UDP services.
+Here's a deeper, more thorough look at getting started with `zrok`:
 
 ## Installing the zrok Command
 
@@ -122,56 +102,64 @@ After you have [an account](#your-first-share), you can enable your `zrok` envir
 
 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 a _secret token_ 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 _secret_, protect it.
+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` environment. In order to use that environment with your account, you'll need to `enable` it. Enabling an environment generates a secure identity and the necessary underlying security policies with the OpenZiti network hosting the `zrok` service.
+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.
 
-From the web console, click on your email address in the upper right corner of the header. That drop down menu contains an `Enable Your Environment` link. Click that link and a modal dialog will be shown like this:
+Log into the API console at:
 
-![Enable Modal Dialog](images/zrok_enable_modal.png)
+[https://api-v1.zrok.io/](https://api-v1.zrok.io/)
 
-This dialog box shows you the `zrok enable` command that you can use to enable any shell to work with your `zrok` account with a single command.
+When you first log into your account on the API console, your interface will look like this:
 
-Let's copy that command and paste it into your shell:
+![zrok API console, empty](images/zrok-getting-started-button.png)
 
-```buttonless title="Example"
-$ zrok enable klFEoIi0QAg7 
+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:
 
-```buttonless title="Example"
-$ zrok enable klFEoIi0QAg7 
+```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
-```
+$ zrok status
 
-```buttonless title="Output"
 Config:
 
- CONFIG       VALUE                        SOURCE
- apiEndpoint  https://api.staging.zrok.io  env
+ CONFIG           VALUE                   SOURCE 
+ apiEndpoint      https://api-v1.zrok.io  env    
+ defaultFrontend  public                  binary 
+ headless         false                   binary 
 
 Environment:
 
- PROPERTY       VALUE
- Secret Token   <<SET>>
- Ziti Identity  <<SET>>
+ PROPERTY       VALUE   
+ Account Token  <<SET>> 
+ Ziti Identity  <<SET>> 
 ```
 
 Excellent... our environment is now fully enabled.
 
-If we return to the _web console_, we'll now see the new environment reflected in the explorer view:
+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_web_ui_new_environment.png)
+![New Environment in Web UI](images/zrok-visualizer-enabled.png)
 
-In my case, the environment is named `michael@ziti-lx`, which is the username of my shell and the hostname of the system the shell is running on.
+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.
@@ -179,16 +167,12 @@ Should you want to use a non-default name for your environment, you can pass the
 
 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_web_ui_empty_shares.png)
+![Empty Environment](images/zrok-visualizer-environment.png)
 
-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 ![Zoom to Fit](images/zrok_zoom_to_fit.png) _zoom to fit_ icon in the lower right corner of the explorer.
-
-If we click on the `Detail` tab for our environment, we'll see something like:
-
-![Environment Detail](images/zrok_web_ui_empty_environment_detail.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 run `zrok share` in one environment, and `zrok access` in other environments.
+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...
@@ -207,63 +191,30 @@ Resources that are shared _publicly_ are exposed to any users on the internet wh
 
 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://2ptgbr8tlfvk.share.zrok.io` to access my 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.
 
-In this case, my share was given the "share token" of `2ptgbr8tlfvk`. 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.
-
-:::note
-Here is the `--help` output from `zrok share public`:
-
-```text
-zrok share public
+```
+$ zrok share public --backend-mode web .
 ```
 
-```buttonless title="Output"
-Error: accepts 1 arg(s), received 0
-Usage:
-  zrok share public <target> [flags]
-
-Flags:
-      --backend-mode string      The backend mode {proxy, web, caddy, drive} (default "proxy")
-      --basic-auth stringArray   Basic authentication users (<username:password>,...)
-      --frontends stringArray    Selected frontends to use for the share (default [public])
-      --headless                 Disable TUI and run headless
-  -h, --help                     help for public
-      --insecure                 Enable insecure TLS certificate validation for <target>
-
-Global Flags:
-  -p, --panic     Panic instead of showing pretty errors
-  -v, --verbose   Enable verbose logging
-
-[ERROR]: an error occurred (accepts 1 arg(s), received 0)
-```
-
-`<target>` defines the path to the local resource that you intend to share. The form of `<target>` depends on the `--backend-mode` that you're using. 
-
-In the case of `--backend-mode proxy`, `<target>` should be a URL to an HTTP endpoint.
-
-In the case of `--backend-mode web`, `<target>` is the path to a file on disk that serves as the "root" of the file tree to be shared.
-:::
+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_web_console_explorer_share.png)
-
-If we click on our new share in the explorer, we can see the share details:
-![Share Details](images/zrok_web_console_share_detail.png)
+![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)
 
-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:
+When we start accessing our share, notice the _sparkline_ graphs showing the activity:
 
-![Environment Spark Line](images/zrok_web_console_environment_spark.png)
+![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)
+![Not Found](images/zrok-not-found.png)
 
 [More about public shares](/concepts/sharing-public.mdx)
 
@@ -271,7 +222,7 @@ If we try to reload the frontend endpoint in our web browser, we'll see:
 
 `zrok` also provides a powerful _private_ sharing model. If I execute the following command:
 
-```buttonless title="Example"
+```buttonless
 $ zrok share private http://localhost:8080
 ```
 
@@ -305,7 +256,7 @@ A reserved share can be re-used multiple times; it will survive termination of t
 
 The first step is to create the reserved share:
 
-```txt title="Example"
+```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
@@ -317,13 +268,13 @@ You'll want to remember the share token (`mltwsinym1s2` in this case), and the f
 
 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)
+![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 title="Example"
+```txt
 $ zrok share reserved mltwsinym1s2
 ```
 
@@ -339,7 +290,7 @@ With the reserved share, we're free to stop and restart the `zrok share reserved
 
 When we're done with the reserved share, we can _release_ it using this command:
 
-```txt title="Example"
+```txt
 $ zrok release mltwsinym1s2
 [   0.230]    INFO main.(*releaseCommand).run: reserved share 'mltwsinym1s2' released
 ```

docs/guides/_frontdoor-linux.mdx

@@ -59,10 +59,10 @@ ZROK_ENABLE_TOKEN="14cbfca9772f"
 
 ## Name your Share
 
-This unique name becomes part of the domain name of the share, e.g. `https://my-prod-app.in.zrok.io`. A random name is generated if you don't specify one.
+This unique name becomes part of the domain name of the share, e.g. `https://toaster.share.zrok.io`. A random name is generated if you don't specify one. The name must be lowercase alphanumeric, between 4 and 32 characters in length.
 
 ```bash title="/opt/openziti/etc/zrok/zrok-share.env"
-ZROK_UNIQUE_NAME="my-prod-app"
+ZROK_UNIQUE_NAME="toaster"
 ```
 
 ## Use Cases

docs/guides/_linux-agent-install.mdx

@@ -0,0 +1,17 @@
+
+1. Set up `zrok`'s Linux package repository by following [the Linux install guide](/guides/install/linux.mdx#install-zrok-from-the-repository), or run this one-liner to complete the repo setup and install packages.
+
+    ```bash
+    curl -sSLf https://get.openziti.io/install.bash \
+    | sudo bash -s zrok-agent
+    ```
+
+1. If you set up the repository by following the guide, then also install the `zrok-agent` package. This package provides the systemd service.
+
+    ```bash title="Ubuntu, Debian"
+    sudo apt install zrok-agent
+    ```
+
+    ```bash title="Fedora, Rocky"
+    sudo dnf install zrok-agent
+    ```

docs/guides/agent/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "The zrok Agent",
+  "position": 15,
+  "link": {
+    "type": "doc",
+    "id": "guides/agent/index"
+  }
+}

docs/guides/agent/index.mdx

@@ -0,0 +1,109 @@
+---
+title: Agent
+sidebar_position: 20
+---
+
+The zrok Agent centralizes management of your zrok shares and accesses. It provides both web-based and command-line interfaces, and changes how the `zrok share` and `zrok access` commands behave.
+
+## Tutorial
+
+Run the Agent in the foreground.
+
+```bash
+zrok agent
+```
+
+In another terminal, open the console.
+
+```bash
+zrok agent console
+```
+
+You should see the Agent UI in your default web browser.
+
+Start sharing a public share with the Agent.
+
+```bash
+zrok share public 8080
+```
+
+```buttonless title="Output"
+token:"zje5x8p0k9pi" frontendEndpoints:"https://zje5x8p0k9pi.share.zrok.io"
+```
+
+You will see the new public share in the Agent UI and you can access it at the public share URL.
+
+Reserve a private share for the Agent to share.
+
+```bash
+zrok reserve private 8080 --closed --unique-name "myshare"
+```
+
+```buttonless title="Output"
+[   1.883]    INFO main.(*reserveCommand).run: your reserved share token is 'myshare'
+```
+
+Start sharing the reserved share with the Agent.
+
+```bash
+zrok share reserved "myshare"
+```
+
+```buttonless title="Output"
+[   0.001]    INFO main.(*shareReservedCommand).shareAgent: starting
+token:"myshare" backendMode:"proxy" shareMode:"private" target:"http://127.0.0.1:8080"
+```
+
+You will see the new reserved share in the Agent UI and you can access it by running `zrok access "myshare"` on another device where you have enabled the same zrok account, since the share was reserved with closed permission mode.
+
+Check the status of the Agent's shares and accesses.
+
+```bash
+zrok agent status
+```
+
+```buttonless title="Output"
+ FRONTEND TOKEN  TOKEN  BIND ADDRESS
+0 accesses in agent
+
+ TOKEN         RESERVED  SHARE MODE  BACKEND MODE  TARGET
+ myshare       true      private     tcpTunnel     127.0.0.1:8080
+1 share in agent
+```
+
+### Running the Agent in the background
+
+You can keep the Agent running reliably in the background by installing the Agent service in Windows or Linux.
+
+- Windows - [set up the Windows system service](/guides/agent/windows-service/index.mdx)
+- Linux - [install the Linux package `zrok-agent`](/guides/agent/linux-service.mdx)
+
+## How the Agent Works
+
+### Centralized Management
+
+Without the Agent running, each time you execute a `zrok share` or `zrok access` command, a separate process is created to handle that specific share or access.
+
+When the Agent is running:
+
+- All shares and accesses are managed by a single Agent process.
+- The Agent provides a web UI for monitoring and managing your shares and accesses.
+- The `zrok share` and `zrok access` commands delegate their operations to the running Agent.
+- You can stop and restart individual shares/accesses without terminating the Agent.
+- The Agent will remember and automatically restart your shares started with `share reserved`, and any accesses started with `access private`.
+- The Agent will not restart regular, ephemeral shares started with `share private` or `share public`.
+
+### Agent Console
+
+The Agent provides a web-based console interface that can be accessed with:
+
+```bash
+zrok agent console
+```
+
+This command opens your default web browser to the Agent UI, where you can:
+
+- View the status of all your active shares and accesses
+- Create new shares and accesses using simple UI widgets
+- Stop or restart existing shares and accesses
+- Monitor traffic and connection statistics

docs/guides/agent/linux-service.mdx

@@ -0,0 +1,42 @@
+---
+title: Linux Agent Service
+sidebar_position: 40
+---
+
+import LinuxAgentInstall from '/../docs/guides/_linux-agent-install.mdx'
+
+## Overview
+
+Run the zrok agent as a `systemd --user` service under your Linux user account.
+
+## Install the Package
+
+The package provides the `zrok` executable and the `zrok-agent.service` unit.
+
+<LinuxAgentInstall />
+
+## Enable your Account
+
+This creates a `~/.zrok` directory enabled for your zrok account.
+
+```bash
+zrok enable <your_account_token>
+```
+
+## Start the Service
+
+```bash
+systemctl --user enable --now zrok-agent.service
+```
+
+## Use the agent
+
+Learn more about using the zrok agent in the [agent guide](/guides/agent/index.mdx).
+
+## Troubleshooting
+
+### Check the User Service Log
+
+```bash
+journalctl --user -lfu zrok-agent.service
+```

docs/guides/agent/windows-service/index.mdx

@@ -0,0 +1,144 @@
+---
+title: Configuring a Windows Service
+sidebar_label: Windows Agent Service
+---
+
+In Windows environments, it can be useful to run the zrok Agent as a service, allowing it to automatically restart with your system.
+
+Support for running the zrok Agent as a Windows service is handled through a third party utility, `nssm`, which is available here:
+
+[https://nssm.cc/download](https://nssm.cc/download)
+
+Give the `nssm` documentation a quick review, here:
+
+[https://nssm.cc/usage](https://nssm.cc/usage)
+
+You'll want to install both the `zrok.exe` and `nssm.exe` in a convenient, protected location. In this example, we'll put them in `C:\Program Files\zrok`, as `C:\Program Files\zrok\zrok.exe` and `C:\Program Files\zrok\nssm.exe`.
+
+![C:\\Program Files\\zrok](images/program-files.png)
+
+We're going to use a command prompt to install and configure our Agent service. Open a new command prompt and `cd "\Program Files\zrok"`:
+
+![Empty Command Prompt](images/empty-command-prompt.png)
+
+## Enabling the Service Environment
+
+On Windows, the `USERPROFILE` environment variable controls the "home" where zrok will look for the enabled environment. When running as a service on Windows, the process will be running as the `Local System` user, which uses the directory `C:\Windows\System32\config\systemprofile` directory as the user's "home" directory.
+
+We're going to want to enable a zrok environment for our new Agent service in this directory. First, we'll run:
+
+```cmd
+C:\Program Files\zrok>set USERPROFILE=c:\Windows\System32\config\systemprofile
+```
+
+And with that environment variable set, we'll use the `zrok enable` command to enable an environment for our new Agent service:
+
+```cmd
+C:\Program Files\zrok>zrok enable <accountToken>
+```
+
+![Enabling the Service Environment](images/enable.png)
+
+Now we've got a new, enabled environment to use with our Agent running as a Windows service.
+
+## Installing the Service
+
+In the `C:\Program Files\zrok` directory, execute this command to invoke `nssm` to create the new Windows service for our zrok Agent:
+
+```cmd
+C:\Program Files\zrok>nssm install zrokAgent
+```
+
+Windows might ask you for elevated Administrator privileges and will then show the main `nssm` installation dialog, which we'll use to configure the new Windows service:
+
+![nssm install](images/nssm-install.png)
+
+We'll set "Path" to `C:\Program Files\zrok\zrok.exe` (the zrok executable). We'll set the "Startup directory" to `C:\Windows\System32\config\systemprofile` (the "home" directory for the `Local System` user). The "Arguments" are the command-line parameters that will get added to the command-line when starting the service, in this case, we want the service to start with the command `zrok agent start`.
+
+We'll set the "Service name" to `zrokAgent`.
+
+Next, scroll over to the "I/O" tab in the `nssm` installer:
+
+![I/O Tab](images/nssm-io.png)
+
+Set the "Output (stdout)" to log the standard output from the `zrok agent start` process to the file `C:\Windows\System32\config\systemprofile\.zrok\agent-stdout.log`.
+
+Set the "Error (stderr)" to log the standard error to the file `C:\Windows\System32\config\systemprofile\.zrok\agent-stderr.log`.
+
+Setting the I/O redirection in this way will produce logs from the `zrok agent start` process that could be useful for future troubleshooting.
+
+`nssm` also provides options for automatically rotating these log files:
+
+![File rotation](images/nssm-file-rotation.png)
+
+We'll leave these unset in this example, but if your configuration needs this kind of log file rotation `nssm` makes it available.
+
+Finally, click the `Install service` button to create the service.
+
+If we open the "Services" utility in Windows, we can see our new `zrokAgent` service:
+
+![Service Manager](images/services.png)
+
+If we click the start button in the toolbar, or right-click on the service and select "start", our new zrok Agent service will start:
+
+![Service Running](images/services-running.png)
+
+If we open a Windows Explorer in the folder `C:\Windows\System32\config\systemprofile\.zrok` we can see our logs, and the `agent.socket` which is used by the zrok command-line to interact with our Agent service:
+
+![zrokdir](images/zrokdir.png)
+
+This zrok Agent service is now available for use. Whenever a Windows Command Prompt wants to interact with this environment, it is important that the `USERPROFILE` environment variable is properly set to `C:\Windows\System32\config\systemprofile`, otherwise the zrok commands will attempt to interact with the environment that would be created in the user's default profile directory.
+
+We can access the Agent console using this command:
+
+```cmd
+C:\Program Files\zrok>zrok agent console
+```
+
+And this will open a web interface which allows the Agent to be managed:
+
+![zrok agent console](images/zrok-agent-console.png)
+
+The Agent console can be used to directly create shares and accesses, and the zrok command-line can also be used.
+
+## Non-interactive Service Installation
+
+`nssm` provides a command-line that can do this configuration without interacting with the `nssm` GUI. We would create our service like this:
+
+```cmd
+C:\Program Files\zrok>nssm install zrokAgent "C:\Program Files\zrok\zrok.exe" agent start
+```
+```cmd
+C:\Program Files\zrok>nssm set zrokAgent AppDirectory C:\Windows\System32\config\systemprofile
+```
+```cmd
+C:\Program Files\zrok>nssm set zrokAgent AppStdout C:\Windows\System32\config\systemprofile\.zrok\agent-stdout.log
+```
+```cmd
+C:\Program Files\zrok>nssm set zrokAgent AppStderr C:\Windows\System32\config\systemprofile\.zrok\agent-stderr.log
+```
+
+And we can start our new service using the standard Windows service control utility, `sc`:
+```cmd
+C:\Program Files\zrok>sc start zrokAgent
+```
+
+![nssm CLI installation](images/nssm-cli-installation.png)
+
+## Removing the zrok Agent Service
+
+The following commands (in a Command Prompt running as Administrator) can be used to remove the service from your system:
+
+```cmd
+C:\>sc stop zrokAgent
+```
+```cmd
+C:\>sc delete zrokAgent
+```
+
+And if you have your `USERPROFILE` environment variable properly set to `C:\Windows\System32\config\systemprofile`, you can use this command to remove the environment from your system and from the zrok service:
+
+```cmd
+C:\Program Files\zrok>zrok disable
+```
+

docs/guides/docker-share/docker_public_share_guide.md

@@ -41,10 +41,10 @@ When the project runs it will:
 
 1. Name the Share
 
-    This unique name becomes part of the domain name of the share, e.g. `https://my-prod-app.in.zrok.io`. A random name is generated if you don't specify one.
+    This unique name becomes part of the domain name of the share, e.g. `https://toaster.share.zrok.io`. A random name is generated if you don't specify one.
 
     ```bash title=".env"
-    ZROK_UNIQUE_NAME="my-prod-app"
+    ZROK_UNIQUE_NAME="toaster"
     ```
 
 1. Run the Compose project to start sharing the built-in demo web server. Be sure to `--detach` so the project runs in the background if you want it to auto-restart when your computer reboots.
@@ -60,7 +60,7 @@ When the project runs it will:
     ```
 
     ```buttonless title="Output"
-    zrok-public-share-1  |  https://w6r1vesearkj.in.zrok.io/
+    zrok-public-share-1  |  https://w6r1vesearkj.share.zrok.io/
     ```
 
 This concludes the minimum steps to begin sharing the demo web server. Read on to learn how to pivot to sharing any website or web service by leveraging additional zrok backend modes.
@@ -149,5 +149,5 @@ With Caddy, you can balance the workload for websites or web services or share s
     ```
 
     ```buttonless title="Output"
-    INFO: zrok public URL: https://88s803f2qvao.in.zrok.io/
+    INFO: zrok public URL: https://88s803f2qvao.share.zrok.io/
     ```

docs/guides/docker-share/index.mdx

@@ -14,9 +14,9 @@ This page provides `docker` and `docker compose` examples of mounting the host's
 
 ## Permanent Public Share
 
-Let's say you have a `compose.yml` file that defines a web app known within the project's bridge network as `https://myapp:8080` and you want to publish it as a reliable, public site.
+Let's say you have a `compose.yml` file that defines a web app known within the project's bridge network as `https://toaster:8080` and you want to publish it as a reliable, public site.
 
-1. Reserve a subdomain by running `zrok reserve public --unique-name "myapp" https://myapp:8080` on the Docker host.
+1. Reserve a subdomain by running `zrok reserve public --unique-name "toaster" https:toasterpp:8080` on the Docker host.
 1. Merge this YAML with `compose.yml` or save it in the same directory as `compose.override.yml` to let `docker compose up` merge it for you.
 
     ```yaml
@@ -29,10 +29,10 @@ Let's say you have a `compose.yml` file that defines a web app known within the
           - ${HOME}/.zrok:/home/ziggy/.zrok
         environment:
           PFXLOG_NO_JSON: "true"
-        command: share reserved "myapp" --headless
+        command: share reserved "toaster" --headless
     ```
 
-The reserved share will be available at `https://myapp.share.zrok.io` each time the `zrok` container starts up.
+The reserved share will be available at `https://toaster.share.zrok.io` each time the `zrok` container starts up.
 
 ## Temporary Public Share
 

docs/guides/install/_homebrew.mdx

@@ -1,4 +1,6 @@
 
+This formula is maintained by the Homebrew community.
+
 ```text
 brew install zrok
 ```

docs/guides/install/_install_cards.mdx

@@ -19,7 +19,7 @@ import DownloadCardStyles from '@site/src/css/download-card.module.css';
     <DownloadCard
       osName="Linux"
       osLogo="/img/logo-linux.svg"
-      infoText="RPM/DEB or Homebrew"
+      infoText="RPM/DEB/AUR or Homebrew"
       guideLink="/docs/guides/install/linux"
     />
   </div>

docs/guides/install/linux.mdx

@@ -10,9 +10,9 @@ import AnsibleRepoSetup from './_ansible_repo_setup.yaml'
 import ConcatenateYamlSnippets from '@site/src/components/cat-yaml.jsx'
 import Homebrew from './_homebrew.mdx';
 
-## Install `zrok` from the Repository
+## Package Repository
 
-This will configure the system to receive DEB or RPM package updates.
+The RedHat (RPM) and Debian (DEB) packages are maintained by NetFoundry.
 
 ```text
 curl -sSf https://get.openziti.io/install.bash | sudo bash -s zrok
@@ -43,10 +43,6 @@ Check out [zrok frontdoor](/guides/frontdoor.mdx?os=Linux) for running `zrok` as
 
 </Details>
 
-## Homebrew
-
-<Homebrew />
-
 ## Linux Binary
 
 <AssetsProvider>
@@ -94,7 +90,7 @@ Download the binary distribution for your Linux distribution's architecture or r
      / /| | | (_) |   < 
     /___|_|  \___/|_|\_\
     
-    v0.4.0 [c889005]
+    v1.0.0 [c889005]
     ```
 
 </Details>
@@ -133,4 +129,12 @@ sudo install -o root -g root ./zrok /usr/local/bin/;
 zrok version;
 ```
 
-</Details>
+</Details>
+
+## Arch User Repository
+
+[An Arch User Repository (AUR) package](https://aur.archlinux.org/packages/zrok-bin) is maintained by the Arch community. As of April 2025, the AUR package includes the `zrok` CLI and [the `zrok-agent.service` systemd `--user` service](/guides/agent/linux-service.mdx).
+
+## Homebrew Formula
+
+<Homebrew />

docs/guides/linux-user-share/_category_.json

@@ -1,8 +0,0 @@
-{
-  "label": "Linux User Share",
-  "position": 40,
-  "link": {
-    "type": "doc",
-    "id": "guides/linux-user-share/index"
-  }
-}

docs/guides/linux-user-share/index.mdx

@@ -1,44 +0,0 @@
----
-title: Linux User Share
----
-
-import LinuxShareInstall from '/../docs/guides/_linux-share-install.mdx'
-
-## Overview
-
-You can run any number of zrok share services as `systemd --user` units with your Linux user's zrok environment in `~/.zrok`. This is like [zrok frontdoor](/guides/frontdoor.mdx) except that frontdoor is a system service managed by root separately from your user's login. Linux user shares, Linux system services, and Docker shares all use the same configuration environment variables.
-
-## Install the Linux Package
-
-The package provides the `zrok` executable and service unit template.
-
-<LinuxShareInstall />
-
-## Create a User Share Configuration File
-
-Substitute a name for your instance in place of `my-instance` in the following example. To avoid character escaping problems, use only letters, numbers, hyphens, and underscores in the instance name, not spaces or other special characters.
-
-```bash
-ZROK_INSTANCE="my-instance"
-cp /opt/openziti/etc/zrok/zrok-share.env ~/.zrok/zrok-share@${ZROK_INSTANCE}.env
-```
-
-## Edit the User Share Configuration File
-
-Edit the configuration file in `~/.zrok/zrok-share@${ZROK_INSTANCE}.env` as you would for [zrok frontdoor](/guides/frontdoor.mdx), except ignore the first section "ZROK ENVIRONMENT" because user shares re-use `~/.zrok` and do not need a separate zrok environment.
-
-## Start the User Share Service
-
-```bash
-systemctl --user enable --now zrok-share@${ZROK_INSTANCE}.service
-```
-
-## Check the User Share Journal
-
-```bash
-journalctl --user -lfu zrok-share@${ZROK_INSTANCE}.service
-```
-
-## Add Another User Share
-
-To create another user share, choose another instance name, copy the `zrok-share.env` file, edit the configuration file, and start the service.

docs/myzrok/custom-domains/index.mdx

@@ -6,7 +6,7 @@ title: Custom Domains
 [myzrok.io](https://myzrok.io) is a hosted zrok-as-a-service offering that provides a way for you bring a custom DNS name for zrok shares.
 For example, let's say you own the domain `foo.example.io`, you can leverage zrok custom domains to
 create ephemeral shares such as: `https://vw8jbg4ijz5g.foo.example.io`
-or [reserved shares](/concepts/sharing-reserved.md) such as `https://myshare.foo.example.io`.
+or [reserved shares](/concepts/sharing-reserved.md) such as `https://toaster.foo.example.io`.
 
 Custom domains require a Pro subscription with [myzrok.io](https://myzrok.io).
 If you don't already have an account, you can sign up for one [here](https://myzrok.io).