mirror of
https://github.com/openziti/zrok.git
synced 2025-04-15 23:08:21 +02:00
110 lines
3.3 KiB
Plaintext
110 lines
3.3 KiB
Plaintext
---
|
|
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
|