Remote agents

A remote agent lets Zerobyte back up files on another machine without mounting its folders on the Zerobyte server. The agent runs Restic on that machine and sends backups directly to your repository. You manage the sources and backup schedules from Zerobyte as usual.

The agent connects to Zerobyte, so you don't need to open an inbound port on the remote machine. It must be able to reach both your Zerobyte server and the backup repository.

Before you startCopy Anchor Link

On the machine you want to back up, you'll need:

• Linux on x64 or ARM64, with glibc and systemd.
• Restic 0.18.0 or newer, installed on the service's PATH, such as /usr/bin/restic or /usr/local/bin/restic.
• Sudo access to install and manage the agent service.

The agent is a standalone executable. You don't need to install Bun. The installer doesn't support Alpine Linux, macOS, or Windows.

Your Zerobyte server must have an HTTPS address that the remote machine can reach. Remote agents are available in the server version of Zerobyte, not the desktop app.

Enable remote agentsCopy Anchor Link

Add the following environment variable to your Zerobyte service and restart it:

environment:
  ENABLE_REMOTE_AGENTS: "true"

Set BASE_URL to the HTTPS address you use to access Zerobyte. If a reverse proxy handles HTTPS, also set TRUST_PROXY=true and enable WebSocket forwarding. See the reverse proxy guide for configuration examples.

Connect a machineCopy Anchor Link

1. Open Settings, choose your organization, and find Machines.
2. Click Connect machine and give the machine a name.
3. Copy the installation command and run it in a terminal on that machine.

The command downloads the agent, checks its checksum and Restic installation, then installs a systemd service. The agent starts immediately and starts again after a reboot. Once it connects, its status in Zerobyte changes to Online.

The connection code in the command can be used once and expires after 15 minutes. If it expires, get a new command from the machine's Actions menu.

Choose folders to back upCopy Anchor Link

A newly connected agent doesn't share any folders. On the remote machine, run:

sudo zerobyte-agent folders add

Use the folder picker to select the directories you want Zerobyte to access. You can choose several folders and run the command again later to add more. The agent restarts after you add folders, so do this between backup runs.

The selected folders appear as Allowed locations on the machine's card in Zerobyte. You can also list them from the terminal:

sudo zerobyte-agent folders list

Zerobyte can browse and back up files inside these locations. Files outside them aren't available through the agent.

Create a backupCopy Anchor Link

In Sources, create a source and choose Another machine. Select your connected machine and an allowed location. You can back up the whole location or browse to a folder inside it.

Save the source, then create a backup job using it. Choose a repository that the remote machine can reach and set your schedule. Local and rclone repositories aren't available for remote sources because they rely on paths or configuration on the Zerobyte server.

Restores currently run on the Zerobyte server. To recover files from a remote backup, restore them to a custom location on the server or download them, then copy them back to the remote machine.

Check the agentCopy Anchor Link

The machine's card shows its status, last contact, hostname, platform, and allowed locations. Agents that report version information also show their agent and Restic versions.

On the remote machine, use these commands to check the service and follow its logs:

sudo zerobyte-agent status
sudo zerobyte-agent logs --follow

Press Ctrl+C to stop following the logs. The agent keeps running in the background. You can also use start, stop, and restart to manage the service.

If the connection drops, the agent retries automatically. The delay increases between failed attempts, up to roughly 30 seconds.

Update the agentCopy Anchor Link

To install the latest stable agent release:

sudo zerobyte-agent update

To install a specific release:

sudo zerobyte-agent update --version vX.Y.Z

Updates preserve the machine's connection and allowed locations, then restart the service. Run them between backup runs. Agents don't update automatically.

If you've downloaded a new agent executable yourself, run its install command without a connection code to update the existing installation. A connection code is only needed for first-time setup or reconnection.

Reconnect or revoke a machineCopy Anchor Link

To replace a machine's credential, open its Actions menu in Zerobyte and choose Reconnect machine. Run the new command on the same machine. It includes --reconnect and preserves the allowed locations and existing sources.

Generating that command disconnects the current agent and invalidates its old credential. Do this between backup runs, and keep the saved configuration at /var/lib/zerobyte-agent/agent.json so the new command can reconnect the existing installation.

Choose Revoke connection to prevent a machine from connecting. Its sources and backup schedules remain saved. To use the machine again, reconnect it from the same machine card.

TroubleshootingCopy Anchor Link

The installer says the machine is already enrolledCopy Anchor Link

The machine already has a saved identity. For an update, run sudo zerobyte-agent update or run the downloaded executable's install command without enrollment options.

If you need to replace the credential, use Reconnect machine on the existing machine card and run its new command. Keep agent.json; deleting it also loses the saved folder selection.

Enrollment fails with “TLS required”Copy Anchor Link

Check that the controller URL uses HTTPS. When a trusted proxy terminates HTTPS and forwards to Zerobyte over HTTP, set TRUST_PROXY=true on Zerobyte and make sure the proxy forwards the original secure protocol.

The machine stays offline after installationCopy Anchor Link

Check sudo zerobyte-agent logs --follow. Your proxy must allow WebSocket upgrades to /api/v1/agents/connect and preserve the Authorization header. With TRUST_PROXY=true, Zerobyte accepts X-Forwarded-Proto: https and X-Forwarded-Proto: wss for secure connections.

If the logs report a Restic or configuration error, fix it and run sudo zerobyte-agent restart. These errors stop the service until you restart it.

The machine is online but has no allowed locationsCopy Anchor Link

Run sudo zerobyte-agent folders add on the remote machine. Registering a machine doesn't share its filesystem automatically.