Skip to main content
Version: 1.0

Agent

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.

zrok agent

In another terminal, open the console.

zrok agent console

You should see the Agent UI in your default web browser.

Start sharing a public share with the Agent.

zrok share public 8080
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.

zrok reserve private 8080 --closed --unique-name "myshare"
Output
[   1.883]    INFO main.(*reserveCommand).run: your reserved share token is 'myshare'

Start sharing the reserved share with the Agent.

zrok share reserved "myshare"
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.

zrok agent status
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.

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:

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