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 zrok2 share and zrok2 access commands behave.

Tutorial

Run the Agent in the foreground.

zrok2 agent

In another terminal, open the console.

zrok2 agent console

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

Start sharing a public share with the Agent.

zrok2 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.

zrok2 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.

zrok2 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 zrok2 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.

zrok2 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.

• Windows - set up the Windows system service
• Linux - install the Linux package zrok2-agent

How the Agent Works

Centralized Management

Without the Agent running, each time you execute a zrok2 share or zrok2 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 zrok2 share and zrok2 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:

zrok2 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