document the linux agent service

docs/guides/_linux-share-install.mdx

@@ -3,15 +3,15 @@
 
     ```bash
     curl -sSLf https://get.openziti.io/install.bash \
-    | sudo bash -s zrok-share
+    | sudo bash -s zrok-agent
     ```
 
-1. If you set up the repository by following the guide, then also install the `zrok-share` package. This package provides the systemd service.
+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-share
+    sudo apt install zrok-agent
     ```
 
     ```bash title="Fedora, Rocky"
-    sudo dnf install zrok-share
+    sudo dnf install zrok-agent
     ```

docs/guides/agent.mdx

@@ -0,0 +1,87 @@
+---
+title: Agent
+sidebar_position: 20
+---
+
+The zrok agent centralizes management of your public and private zrok shares and private frontends for accessing [private shares](/concepts/sharing-private.mdx). It provides a web-based console interface 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.
+
+### Running the Agent in the background
+
+On Linux, you can [install the Linux package `zrok-agent`](/guides/linux-agent-service.mdx) to keep the agent running in the background after each reboot.
+
+## 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
+- New `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
+
+### 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's 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/linux-agent-service.mdx

@@ -0,0 +1,42 @@
+---
+title: Linux Agent Service
+sidebar_position: 40
+---
+
+import LinuxShareInstall from '/../docs/guides/_linux-share-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.
+
+<LinuxShareInstall />
+
+## 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.mdx).
+
+## Troubleshooting
+
+### Check the User Service Log
+
+```bash
+journalctl --user -lfu zrok-agent.service
+```

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.