zerobyte Documentation

The simpler rule is: if file contents matter most, mounted shares are often great. If you want the closest possible replica of the original filesystem, a local Directory volume is still the best option.

Apps Docs Content Docs Guides Notifications (`apps/docs/content/docs/guides/notifications.mdx`) Copy Section

title: Notifications Copy Chapter

Zerobyte's notification system has two layers:

1. A destination is a reusable delivery channel such as Slack, SMTP, ntfy, or a webhook.
2. A backup schedule assignment decides which events should be sent to which destination.

You create destinations under Notifications. You route them per backup schedule from the backup details page.

How notifications work in Zerobyte Copy Chapter

• Destinations are organization-scoped.
• Sensitive destination fields are encrypted before storage.
• Disabled destinations stay saved, but Zerobyte skips them when sending notifications.
• The Test button sends a generic test message for that destination.
• Per-schedule routing supports four events: start, success, warning, and failure.

Supported destination types Copy Chapter

Which type should I use? Copy Chapter

• Choose Email when you already trust an SMTP relay and want easy fan-out to multiple recipients.
• Choose Slack or Discord when backup events belong in a shared team room.
• Choose Gotify or ntfy when you prefer self-hosted push.
• Choose Pushover or Telegram when you want fast personal alerts on a phone.
• Choose Generic Webhook when another system expects a normal HTTP request.
• Choose Custom (Shoutrrr URL) when the built-in types are close but not flexible enough, or when you need a different Shoutrrr-supported service entirely.

Create a destination Copy Chapter

1. Open Notifications in the sidebar.
2. Click Create Destination.
3. Pick the notification type.
4. Fill in the type-specific settings.
5. Save the destination.
6. Open the destination and use Test before attaching it to production schedules.

The type is effectively fixed after creation in the current UI, so create a new destination instead of trying to repurpose an existing one from Slack to Email or similar.

Route notifications per backup schedule Copy Chapter

1. Open the backup schedule you want to configure.
2. In the Notifications section, click Add notification.
3. Select an existing destination.
4. Choose which events should trigger that destination.
5. Save the backup schedule notification settings.

Each assignment is independent. One schedule can send failures to Email, warnings to Slack, and successes nowhere.

Backup event meanings Copy Chapter

Type reference Copy Chapter

<Tabs
items={[
"Email (SMTP)",
"Slack",
"Discord",
"Gotify",
"ntfy",
"Pushover",
"Telegram",
"Generic Webhook",
"Custom",
]}

**Fields**

- `SMTP Host`
- `SMTP Port`
- `Username` and `Password` (optional)
- `From Address`
- `From Name` (optional)
- `To Addresses`
- `Use TLS`

**Notes**

- `To Addresses` is a comma-separated list in the UI.
- TLS is a simple yes or no toggle.
- SMTP authentication is optional because some relays accept trusted network senders.

**Example**

```text
Type: Email (SMTP)
SMTP Host: smtp.example.com
SMTP Port: 587
Username: [email protected]
Password: <smtp-password>
From Address: [email protected]
From Name: Zerobyte Alerts
To Addresses: [email protected], [email protected]
Use TLS: On
```

**Fields**

- `Webhook URL`
- `Bot Username` (optional)
- `Icon Emoji` (optional)

**Example**

```text
Type: Slack
Webhook URL: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX
Bot Username: Zerobyte
Icon Emoji: :floppy_disk:
```

**Fields**

- `Webhook URL`
- `Bot Username` (optional)
- `Avatar URL` (optional)
- `Thread ID` (optional)

**Fields**

- `Server URL`
- `App Token`
- `Priority` from `0` to `10`
- `Path` (optional)

**Notes**

- Add the Gotify server origin, such as `https://gotify.example.com`, to `WEBHOOK_ALLOWED_ORIGINS`.

**Fields**

- `Server URL` (optional, leave empty for `ntfy.sh`)
- `Topic`
- `Username` and `Password` (optional)
- `Access token` (optional)
- `Priority`

**Notes**

- Leave `Server URL` empty to use `ntfy.sh`.
- Add self-hosted ntfy origins, such as `https://ntfy.example.com`, to `WEBHOOK_ALLOWED_ORIGINS`.
- If you set an access token, it takes precedence over username and password.
- Priority values are `max`, `high`, `default`, `low`, and `min`.

**Example**

```text
Type: Ntfy
Server URL: https://ntfy.example.com
Topic: zerobyte-backups
Access token: <token>
Priority: high
```

**Fields**

- `User Key`
- `API Token`
- `Devices` (optional)
- `Priority` as `-1`, `0`, or `1`

**Fields**

- `Bot Token`
- `Chat ID`
- `Thread ID` (optional)

**Example**

```text
Type: Telegram
Bot Token: 123456789:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
Chat ID: -1231234567890
Thread ID: 3
```

**Fields**

- `Webhook URL`
- `Method` as `GET` or `POST`
- `Content Type`
- `Headers`
- `Use JSON Template`
- `Title Key` and `Message Key` when JSON mode is enabled

**Notes**

- Add the webhook origin, such as `https://hooks.example.com`, to `WEBHOOK_ALLOWED_ORIGINS`.
- Headers are entered one per line as `Key: Value`.
- With JSON mode enabled, Zerobyte sends a body shaped like `{titleKey: "...", messageKey: "..."}`.
- With JSON mode disabled, the request body is plain notification text.

**Example**

```text
Type: Generic Webhook
Webhook URL: https://hooks.example.com/backup-events
Method: POST
Content Type: application/json
Headers:
Authorization: Bearer <token>
X-Source: zerobyte
Use JSON Template: On
Title Key: title
Message Key: message
```

See the [Shoutrrr documentation](https://shoutrrr.nickfedor.com/services/overview) for the supported URL formats and service-specific options.

If the Shoutrrr URL targets a custom HTTP endpoint, add that endpoint origin to `WEBHOOK_ALLOWED_ORIGINS`.

**Fields**

- `Shoutrrr URL`

**Example**

```text
slack://hook:T000-B000-XXX@webhook?username=Zerobyte
```

Practical routing patterns Copy Chapter

Related docs Copy Chapter

• Backups
• Repository maintenance and status

import { Callout } from "fumadocs-ui/components/callout";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";

Apps Docs Content Docs Guides Oidc Sso (`apps/docs/content/docs/guides/oidc-sso.mdx`) Copy Section

title: SSO Copy Chapter

Zerobyte's current SSO implementation is organization-scoped and OIDC-based. You register providers under Settings > Organization > Single Sign-On, or directly at /settings/sso/new.

What Zerobyte supports Copy Chapter

• Each SSO provider belongs to exactly one organization.
• The login page exposes registered providers as Log in with {providerId} buttons.
• Organization owners can register new providers.
• Organization owners and admins can manage invitations, toggle per-provider auto-linking, and delete existing providers.
• Zerobyte currently registers OIDC providers with the openid, email, and profile scopes.

Required values Copy Chapter

Callback URL Copy Chapter

Register this exact redirect URI in your identity provider:

${BASE_URL}/api/auth/sso/callback/${providerId}

Example:

https://backup.example.com/api/auth/sso/callback/acme-oidc

Setup checklist Copy Chapter

1. In your identity provider, create a confidential or web OIDC client for Zerobyte.
2. Register the callback URL above as an allowed redirect URI.
3. Make sure the provider returns email and an email-verification claim.
4. In Zerobyte, open Settings > Organization > Single Sign-On and click Register new.
5. Fill in the provider details and save.
6. Decide whether Link matching emails to existing accounts should be enabled for this provider.
7. Invite users before asking them to sign in, unless their existing local account already belongs to the organization.

How access is decided Copy Chapter

The important rule is that Zerobyte checks organization membership and pending invitations in addition to whatever your identity provider says.

In practice, an eligible local account means an account that already belongs to the organization you are signing into. A matching email plus a pending invitation is not enough to merge an unrelated existing account.

Invitations and membership lifecycle Copy Chapter

• Invitations are email-based, organization-specific, and role-bearing.
• A successful first SSO login for an invited user creates the membership and marks the invitation as accepted.
• Pending invitations must still be unexpired to work.
• Expired, cancelled, or already accepted invitations do not grant first-time access.
• If a user is removed later, create a new invitation before they try SSO again.

The invitation UI lets you assign member, admin, or owner at invite time. The accepted membership is created with that invited role.

Auto-linking semantics Copy Chapter

• Auto-linking is stored per provider, not globally.
• Turning it on for one provider does not affect other providers.
• It only applies when the IdP email matches an existing Zerobyte account.
• It does not grant organization membership by email alone.
• It does not override invite-only access for brand-new users.
• It does not merge a matching account that is outside the organization.
• Leaving it off is the safest default for new rollouts.

Common failure cases Copy Chapter

Related docs Copy Chapter

• Organizations, members, and roles
• Recovery keys and repository passwords

import { Callout } from "fumadocs-ui/components/callout";

Apps Docs Content Docs Guides Performance Tuning (`apps/docs/content/docs/guides/performance-tuning.mdx`) Copy Section

title: Performance Tuning Copy Chapter

import { Callout } from "fumadocs-ui/components/callout";

Most performance tuning is a trade between CPU, network bandwidth, source disk I/O, and repository storage. This guide covers the Zerobyte settings and Restic flags that are safe to adjust.

Change one setting at a time, then compare runtime, CPU, memory, network usage, source disk pressure, and repository behavior. A setting that helps one source can make another source worse.

Quick recipes Copy Chapter

Where to tune Copy Chapter

Some settings apply globally, some apply to one repository, and some apply only to one backup schedule.

Custom Restic parameters are appended to the restic backup command for that schedule only. Enter one flag per line.

Example low-impact schedule:

--read-concurrency 1
--exclude-larger-than 10G
--no-scan

Example faster schedule for a local NVMe source:

--read-concurrency 8

Limit Restic CPU usage with GOMAXPROCS Copy Chapter

The standard Go environment variable GOMAXPROCS limits how many operating system threads can execute Go code at the same time. Add it to the Zerobyte container environment:

services:
  zerobyte:
    environment:
      - GOMAXPROCS=2

Then restart Zerobyte:

docker compose up -d

Use these starting points:

Choose compression mode Copy Chapter

Repository compression mode is configured on the repository form. Zerobyte passes it to Restic backups as --compression.

Good candidates for off include video libraries, JPEG/HEIC photo archives, already-compressed archives such as .zip, .7z, .gz, and .zst, VM images, and application data that is compressed before Zerobyte sees it.

Good candidates for max include text-heavy project directories, logs, and slow or expensive remote storage links where CPU is available.

Compression mode affects new backup data. It does not rewrite or recompress existing packs already stored in the repository.

Limit upload and download bandwidth Copy Chapter

Repository settings include upload and download limits. These map to Restic's --limit-upload and --limit-download options and apply to operations for that repository.

Use bandwidth limits when backups make the internet connection unusable, a remote storage provider throttles or disconnects large transfers, or restores should not starve other services on the same host.

Prefer the repository bandwidth fields over custom Restic parameters. The UI uses Kbps, Mbps, and Gbps; Zerobyte converts those values to the unit Restic expects.

Tune pack size Copy Chapter

Restic stores data in pack files. The --pack-size option changes the target pack size in MiB. Restic's default target is 16 MiB.

Larger pack files can improve performance when the bottleneck is per-file or per-object overhead rather than raw throughput. This is common with very large repositories with many pack files, backends with file count or object count pressure, Google Drive or similar rclone-backed storage, OpenStack Swift-like object storage, and local HDD repositories where creating many small files is expensive.

Suggested starting points:

Example:

--pack-size 64

Do not jump straight to very large values. Larger packs reduce object count, but each pack is a larger unit to upload, retry, rewrite, and cache. If an upload fails near the end of a large pack, more work may need to be repeated.

Tune read concurrency Copy Chapter

--read-concurrency controls how many files Restic reads in parallel during backup. It is one of the most useful knobs for slow machines because it directly changes pressure on the source filesystem.

Use low values when the machine is CPU or disk constrained:

--read-concurrency 1

Use higher values only when the source can keep up:

--read-concurrency 4

If the backup host becomes sluggish, lower --read-concurrency before changing pack size. If Restic is idle waiting on storage, increase it one step and compare the next run.

Keep the cache local Copy Chapter

Restic uses a local cache for repository metadata. Zerobyte places this cache in the configured Restic cache directory, which defaults to /var/lib/zerobyte/restic/cache inside the container.

Keep the cache on local storage. Do not place /var/lib/zerobyte or the Restic cache on a network share. A slow cache can make snapshots, checks, forget operations, and backups feel much slower than the repository itself.

Avoid these flags unless you are diagnosing a cache problem:

If a repository behaves strangely after moving storage or changing credentials, --cleanup-cache can be useful for one diagnostic run. Do not leave it in a normal schedule as a performance tweak.

Skip progress scanning Copy Chapter

By default, Restic scans the source to estimate total work and provide progress information. On very large trees, slow network mounts, or filesystems with high directory traversal cost, that initial scan can be expensive.

Use --no-scan to skip the initial scan:

--no-scan

This can make a backup start doing useful work sooner, but progress reporting may be less complete. It does not reduce the actual file content Restic must read to create the backup.

Baselines Copy Chapter

For a low-power NAS, mini PC, or shared server, start with this conservative setup:

1. Set GOMAXPROCS=1 or GOMAXPROCS=2 on the Zerobyte container.
2. Use repository compression mode auto for mixed data, or off for mostly compressed media.
3. Add --read-concurrency 1 to heavy backup schedules.
4. Keep the Restic cache on local storage.
5. If the repository creates too many small objects or files, test --pack-size 32 on one schedule.

For S3-compatible storage, rclone remotes, and other object stores where each uploaded object has overhead:

1. Keep compression at auto unless CPU is clearly the bottleneck.
2. Test --pack-size 64 on one backup schedule.
3. If object count is still a problem and uploads are reliable, test --pack-size 128.
4. Use repository upload/download limits if the link is shared with other services.
5. Avoid --no-cache; metadata round trips are often the slow part on remote repositories.

Troubleshooting Copy Chapter

For high CPU usage, use this order:

1. Check whether compression mode is max. If yes, switch to auto or off and run the next backup.
2. Set GOMAXPROCS=2 on the Zerobyte container and restart.
3. If the source disk is also busy, add --read-concurrency 1 to the affected backup schedule.
4. If the repository is remote and uploads saturate the host, add a repository upload limit.
5. Watch a few scheduled runs before making further changes.

If backups are still too heavy, reduce the schedule frequency or split very large sources into separate schedules so the heavy work does not run all at once.

For slow backups, use this order:

1. Make sure the source and repository are not on the same slow disk.
2. Use compression mode auto before trying max.
3. If the source is fast SSD/NVMe storage, try --read-concurrency 4.
4. If the bottleneck is network upload, keep compression enabled and remove upload limits during a test window.
5. Check repository storage latency. Cloud, rclone, and network filesystems can be much slower than local disk.

A faster backup that starves the NAS, VM host, or network may be worse than a slower predictable one.

Apps Docs Content Docs Guides Provisioning (`apps/docs/content/docs/guides/provisioning.mdx`) Copy Section

title: Provisioned Resources Copy Chapter

import { Step, Steps } from "fumadocs-ui/components/steps";
import { Callout } from "fumadocs-ui/components/callout";

Zerobyte can sync operator-managed repositories and volumes from a JSON configuration file at startup. This is useful when you want credentials and connection details to live in deployment-time configuration instead of being entered through the UI.

What Provisioning Supports Today Copy Chapter

Provisioning currently supports:

• repositories
• volumes
• secret references through env:// and file://
• updating managed resources in place by keeping the same id
• deleting managed resources with "delete": true

Provisioning does not currently support:

• backup jobs or schedules
• notification destinations
• exporting UI-created resources back into provisioning JSON
• live reloading without restarting the Zerobyte container

Prerequisites Copy Chapter

• A running Zerobyte instance with an organization ID
• The PROVISIONING_PATH environment variable pointing to your JSON file

Find your organization ID Copy Section

1. Sign in to Zerobyte and switch to the organization you want to provision into
2. Open Settings
3. Open the Organization tab
4. Copy the read-only Organization ID value from Organization Details

Quick Start Copy Chapter

{
	"version": 1,
	"repositories": [
		{
			"id": "local-repo",
			"organizationId": "your-organization-id",
			"name": "Primary Local Repository",
			"backend": "local",
			"compressionMode": "auto",
			"config": {
				"backend": "local",
				"path": "/var/lib/zerobyte/repositories/primary",
				"isExistingRepository": false
			}
		}
	],
	"volumes": [
		{
			"id": "documents",
			"organizationId": "your-organization-id",
			"name": "Documents",
			"backend": "directory",
			"autoRemount": true,
			"config": {
				"backend": "directory",
				"path": "/data/documents"
			}
		}
	]
}

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.43
    environment:
      - PROVISIONING_PATH=/config/provisioning.json
    volumes:
      - ./provisioning.json:/config/provisioning.json:ro
      - /var/lib/zerobyte:/var/lib/zerobyte
      - /srv/documents:/data/documents

docker compose up -d

Root File Format Copy Chapter

The root object always has the same shape:

{
	"version": 1,
	"repositories": [],
	"volumes": []
}

Repository Entry Reference Copy Chapter

Each item in repositories uses this top-level shape:

{
	"id": "repo-id",
	"organizationId": "org-id",
	"name": "Repository Name",
	"backend": "local",
	"compressionMode": "auto",
	"delete": false,
	"config": {
		"backend": "local",
		"path": "/var/lib/zerobyte/repositories/repo-id"
	}
}

Repository Shared Config Fields Copy Section

These fields are available inside every repository config object:

Bandwidth limit objects use this shape:

{
	"enabled": true,
	"value": 10,
	"unit": "Mbps"
}

unit must be one of Kbps, Mbps, or Gbps.

Repository Backends Copy Section

<Tabs items={["Local", "S3", "R2", "GCS", "Azure", "Rclone", "REST", "SFTP"]}>

| Field | Required | Notes |
| ------ | -------- | ---------------------------------- |
| path | yes | Path inside the Zerobyte container |

```json
{
	"backend": "local",
	"path": "/var/lib/zerobyte/repositories/primary",
	"isExistingRepository": false
}
```

```json
{
	"backend": "s3",
	"endpoint": "https://s3.amazonaws.com",
	"bucket": "company-backups",
	"accessKeyId": "env://AWS_ACCESS_KEY_ID",
	"secretAccessKey": "file://aws_secret_access_key",
	"isExistingRepository": true
}
```

```json
{
	"backend": "r2",
	"endpoint": "https://<account-id>.r2.cloudflarestorage.com",
	"bucket": "zerobyte-backups",
	"accessKeyId": "env://R2_ACCESS_KEY_ID",
	"secretAccessKey": "env://R2_SECRET_ACCESS_KEY",
	"isExistingRepository": true
}
```

```json
{
	"backend": "gcs",
	"bucket": "zerobyte-backups",
	"projectId": "my-gcp-project",
	"credentialsJson": "file://gcs_credentials_json",
	"isExistingRepository": true
}
```

```json
{
	"backend": "azure",
	"container": "zerobyte-backups",
	"accountName": "storageaccount",
	"accountKey": "env://AZURE_STORAGE_ACCOUNT_KEY",
	"endpointSuffix": "core.windows.net",
	"isExistingRepository": true
}
```

```json
{
	"backend": "rclone",
	"remote": "remote-name",
	"path": "zerobyte/backups",
	"isExistingRepository": true
}
```

```json
{
	"backend": "rest",
	"url": "https://rest-server.example.com",
	"username": "env://REST_USERNAME",
	"password": "file://rest_password",
	"path": "zerobyte",
	"isExistingRepository": true
}
```

```json
{
	"backend": "sftp",
	"host": "backup.example.com",
	"port": 22,
	"user": "backup",
	"path": "/srv/restic",
	"privateKey": "file://sftp_private_key",
	"skipHostKeyCheck": false,
	"knownHosts": "backup.example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
}
```

Volume Entry Reference Copy Chapter

Each item in volumes uses this top-level shape:

{
	"id": "volume-id",
	"organizationId": "org-id",
	"name": "Volume Name",
	"backend": "directory",
	"autoRemount": true,
	"delete": false,
	"config": {
		"backend": "directory",
		"path": "/data/volume"
	}
}

Volume Backends Copy Section

<Tabs items={["Directory", "NFS", "SMB/CIFS", "WebDAV", "SFTP", "Rclone"]}>

| Field | Required | Notes |
| ---------- | -------- | ---------------------------------- |
| path | yes | Path inside the Zerobyte container |
| readOnly | no | If provided, it must be false |

```json
{
	"backend": "directory",
	"path": "/data/documents"
}
```

```json
{
	"backend": "nfs",
	"server": "10.0.0.10",
	"exportPath": "/exports/media",
	"port": 2049,
	"version": "4.1",
	"readOnly": true
}
```

```json
{
	"backend": "smb",
	"server": "fileserver.local",
	"share": "team",
	"username": "backup-user",
	"password": "env://SMB_PASSWORD",
	"vers": "3.0",
	"domain": "WORKGROUP",
	"port": 445,
	"readOnly": false
}
```

```json
{
	"backend": "webdav",
	"server": "cloud.example.com",
	"path": "/team-a",
	"username": "team-a",
	"password": "env://WEBDAV_PASSWORD",
	"port": 443,
	"ssl": true
}
```

```json
{
	"backend": "sftp",
	"host": "files.example.com",
	"port": 22,
	"username": "backup-user",
	"privateKey": "file://volume_sftp_private_key",
	"path": "/srv/data",
	"readOnly": true,
	"skipHostKeyCheck": false,
	"knownHosts": "files.example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI..."
}
```

```json
{
	"backend": "rclone",
	"remote": "remote-name",
	"path": "team-a",
	"readOnly": true
}
```

Secret References Copy Chapter

Supported secret references use one of these prefixes:

Only specific fields are resolved as secret references. Other string fields are treated literally.

Repository fields that support secret references Copy Section

• shared fields: customPassword, cacert
• s3: accessKeyId, secretAccessKey
• r2: accessKeyId, secretAccessKey
• gcs: credentialsJson
• azure: accountKey
• rest: username, password
• sftp: privateKey

Volume fields that support secret references Copy Section

• smb: password
• webdav: password
• sftp: password, privateKey

Resolved secret values are encrypted before Zerobyte stores them in the database.

Rotating Secrets Copy Chapter

To rotate a provisioned secret:

1. Update the environment variable or secret file
2. Restart Zerobyte with docker compose restart

Zerobyte re-resolves supported secret references on each startup.

Updating And Removing Managed Resources Copy Chapter

• Keep the same id to update a managed resource in place
• Changing only name keeps the same underlying resource record
• Setting "delete": true removes the managed resource on the next startup sync

Deletion entries still need the normal entry shape today because the provisioning file is validated before Zerobyte applies the delete flag:

{
	"id": "repo-to-remove",
	"organizationId": "your-organization-id",
	"name": "Repo to remove",
	"backend": "local",
	"delete": true,
	"config": {
		"backend": "local",
		"path": "/var/lib/zerobyte/repositories/old",
		"isExistingRepository": true
	}
}

Troubleshooting Copy Chapter

`No matching discriminator` Copy Section

This error usually means one of these is wrong:

• backend is not a valid value for that resource type
• config.backend does not match the top-level backend
• the config object does not match the required fields for that backend

Secret reference errors Copy Section

• env://NAME requires the environment variable to exist in the Zerobyte container
• file://name requires /run/secrets/name to exist
• Zerobyte stops syncing when it hits a provisioning error, so fix the first reported error and restart again

Important Notes Copy Chapter

• Changes to provisioning.json only apply on container restart
• Provisioned resources appear in the normal UI and are marked as managed
• Editing a provisioned resource in the UI is useful for testing, but the next provisioning sync can overwrite it

import { Tab, Tabs } from "fumadocs-ui/components/tabs";

Apps Docs Content Docs Guides Rclone (`apps/docs/content/docs/guides/rclone.mdx`) Copy Section

title: Rclone Integration Copy Chapter

Rclone is a command-line tool that connects to over 40 cloud storage providers, including Google Drive, Dropbox, OneDrive, Box, pCloud, Mega, and many more. Zerobyte leverages rclone in two ways:

• Repositories, store your encrypted backups on any rclone-supported cloud provider
• Volumes, mount cloud storage as a data source so you can back it up

This guide covers installing rclone, connecting it to Zerobyte, and using it for both repositories and volumes.

Setting up rclone Copy Chapter

Before Zerobyte can use rclone, you need to install and configure it on your host machine.

curl https://rclone.org/install.sh | sudo bash

rclone config

rclone listremotes

rclone lsd myremote:

Mounting rclone config into the container Copy Chapter

Zerobyte needs access to your rclone configuration file to discover and use your remotes. Mount it as a read-only volume in your compose.yaml:

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /var/lib/zerobyte:/var/lib/zerobyte
  - ~/.config/rclone:/root/.config/rclone:ro

Then restart the container to pick up the change:

docker compose down && docker compose up -d

environment:
  - RCLONE_CONFIG_DIR=/home/appuser/.config/rclone
volumes:
  - ~/.config/rclone:/home/appuser/.config/rclone:ro

Using rclone for repositories Copy Chapter

Rclone repositories let you store encrypted backups on any rclone-supported provider.

Using rclone for volumes Copy Chapter

Rclone volumes mount cloud storage as a filesystem inside the container, allowing you to back up data stored in the cloud. This requires elevated container capabilities.

cap_add:
  - SYS_ADMIN
devices:
  - /dev/fuse:/dev/fuse

SFTP remotes with SSH keys Copy Chapter

If your rclone remote uses SFTP with key_file authentication, the path in the rclone config points to a location on the host filesystem, which is not accessible inside the container. There are three ways to solve this.

<Tabs items={["Mount SSH keys", "Embed key in config", "SSH agent"]}>

Recommended. Mount your SSH keys into the container so rclone can find them at the expected path:

volumes:
  - ~/.ssh:/root/.ssh:ro

Make sure the key_file path in your rclone config matches the container path (e.g., /root/.ssh/id_rsa).

environment:
  - SSH_AUTH_SOCK=/ssh-agent
volumes:
  - ${SSH_AUTH_SOCK}:/ssh-agent

Refreshing OAuth tokens Copy Chapter

Rclone remotes that use OAuth (Google Drive, Dropbox, OneDrive, Box, and others) store authentication tokens in the rclone config file. These tokens expire periodically and need to be refreshed.

rclone config reconnect myremote:

docker compose restart

Troubleshooting Copy Chapter

No remotes available Copy Section

If the rclone remote dropdown is empty when creating a repository or volume:

• Verify the rclone config is mounted correctly. Check that ~/.config/rclone/rclone.conf exists on the host.
• Confirm the mount path in compose.yaml matches the expected location inside the container (/root/.config/rclone by default, or the path set in RCLONE_CONFIG_DIR).
• Restart the container after updating the volume mount.

Failed to create file system Copy Section

This usually means rclone cannot authenticate with the remote:

• For OAuth remotes (Google Drive, Dropbox, OneDrive), the token may have expired. Re-authenticate with rclone config reconnect myremote: on the host and restart the container.
• For key-based remotes (S3, SFTP), verify that credentials in the rclone config are correct.
• Test the remote directly on the host: rclone lsd myremote: to isolate whether the issue is with rclone itself or with Zerobyte.

FUSE mount errors for rclone volumes Copy Section

If you see errors related to FUSE when creating rclone volumes:

• Ensure your compose.yaml includes cap_add: [SYS_ADMIN] and devices: [/dev/fuse:/dev/fuse].
• Confirm you are running on a Linux host. FUSE mounts do not work with Docker on macOS or Windows.
• Check that /dev/fuse exists on the host: ls -la /dev/fuse.

import { Step, Steps } from "fumadocs-ui/components/steps";
import { Tab, Tabs } from "fumadocs-ui/components/tabs";

Apps Docs Content Docs Guides Recovery Key And Repository Passwords (`apps/docs/content/docs/guides/recovery-key-and-repository-passwords.mdx`) Copy Section

title: Recovery Keys Copy Chapter

Zerobyte separates account authentication from Restic repository encryption. Your login password, your organization's recovery key, any imported repository password, and APP_SECRET all serve different purposes.

The important secrets in Zerobyte Copy Chapter

What the recovery key actually is Copy Chapter

The downloaded restic.pass file contains the Restic password for the active organization.

That organization-level password is what Zerobyte uses when it:

• Initializes a brand-new repository from the UI
• Accesses a repository that relies on the organization's default password
• Runs normal backup, restore, snapshot, doctor, and stats operations for those repositories

First-run behavior for local users Copy Chapter

During first-run onboarding, the first local admin is created with a flag indicating they have not downloaded the recovery key yet.

Until that flag is cleared, Zerobyte redirects the user to /download-recovery-key instead of the normal app pages.

When the user downloads the file successfully:

• Zerobyte verifies the user's current password
• The response returns the plaintext restic.pass file
• Zerobyte marks that user as having downloaded the recovery key

After that, future logins go straight to the app.

SSO behavior Copy Chapter

SSO-created users are marked as having already downloaded the recovery key, so they are not forced through the recovery-key download screen during first login.

That means SSO rollouts should treat recovery key storage as an organization-admin responsibility. Ordinary SSO users are not individually prompted to save the key.

Who can download the recovery key Copy Chapter

The current download endpoint requires all of the following:

• You are signed in
• Your active organization role is admin or owner
• You re-enter your current account password

The downloaded filename is restic.pass.

New repositories vs imported repositories Copy Chapter

Important limitation Copy Section

The custom password option only exists when Import existing repository is enabled. Brand-new repositories created by Zerobyte always use the active organization's recovery key.

Configuration exports Copy Chapter

Organization owners and admins can download a .zbex file containing the organization's repositories, volumes, schedules, notification destinations, and recovery key. Zerobyte decrypts only those exported values in memory and encrypts the complete file with a dedicated export passphrase.

The export passphrase is separate from your account password, recovery key, and APP_SECRET. Zerobyte does not store it and cannot recover it.

To restore the configuration during onboarding on another instance, you need:

• The .zbex file
• Its export passphrase

The source instance's APP_SECRET is not exported or required. After import, the destination instance encrypts the imported credentials using its own APP_SECRET.

How Zerobyte decides which password to use Copy Chapter

Zerobyte's runtime password selection is simple:

1. If the repository is imported and has a stored custom password, use that custom password.
2. Otherwise, use the active organization's recovery key.

This has an important consequence: downloading the organization recovery key will not help with an imported repository that is configured with its own custom password.

Choosing the right import option Copy Chapter

Choose Use the existing recovery key only when the repository already uses the same Restic password as the active organization.

Typical examples:

• A repository previously created by the same Zerobyte organization
• A migrated environment where the organization password was preserved

Choose Enter password manually when the repository was initialized outside this organization, for example:

• A repository created with the Restic CLI
• A repository created by another Zerobyte organization
• A repository created by another tool that happened to use Restic

Practical guidance Copy Chapter

• Keep a secure inventory of which imported repositories use custom passwords.
• Do not assume all repositories in the same Zerobyte instance share the same password model.
• If you manage multiple organizations, remember that the downloaded recovery key is for the active organization.
• Test restores using the same password model the repository actually uses.
• Treat APP_SECRET and the recovery key as separate operational secrets. Losing one is not the same as losing the other.
• Keep each configuration export passphrase with the same care as the export itself; neither can be recovered from the other.

Related docs Copy Chapter

• Repositories
• Repository maintenance and status

import { Callout } from "fumadocs-ui/components/callout";

Apps Docs Content Docs Guides Remote Agents (`apps/docs/content/docs/guides/remote-agents.mdx`) Copy Section

title: Remote agents Copy Chapter

import { Callout } from "fumadocs-ui/components/callout";

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 start Copy Chapter

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 agents Copy Chapter

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 machine Copy Chapter

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 up Copy Chapter

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 backup Copy Chapter

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 agent Copy Chapter

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 agent Copy Chapter

To install the latest stable agent release, run the installer again without a connection code:

curl -fsSL https://zerobyte.app/install.sh | sudo bash

To install a specific release, set ZEROBYTE_AGENT_VERSION:

curl -fsSL https://zerobyte.app/install.sh | sudo env ZEROBYTE_AGENT_VERSION=vX.Y.Z bash

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 machine Copy Chapter

To replace a machine's credential, open its Actions menu in Zerobyte and choose Get connection command. Run the new command on the same machine. The agent detects its saved identity and reconnects automatically, preserving 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.

Troubleshooting Copy Chapter

The installer says the machine is already enrolled Copy Section

The machine already has a saved identity. To update it, run the installer again without a connection code, as described in Update the agent.

If you need to replace the credential, choose Get connection command from the existing machine's Actions menu and run its new command. Keep agent.json; deleting it also loses the saved folder selection.

Enrollment fails with “TLS required” Copy Section

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 installation Copy Section

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 locations Copy Section

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

Apps Docs Content Docs Guides Repository Maintenance (`apps/docs/content/docs/guides/repository-maintenance.mdx`) Copy Section

title: Repository Maintenance Copy Chapter

The repository details page exposes a small set of maintenance tools, but they do different jobs. This guide explains what each status means and what the built-in actions actually do.

Repository status values Copy Chapter

Repository status is stored metadata inside Zerobyte. It is not a continuous live probe.

What each action really does Copy Chapter

Run doctor in detail Copy Chapter

Doctor is the deepest repository-maintenance action currently exposed in the normal UI.

During a Doctor run, Zerobyte:

1. Sets the repository status to doctor
2. Acquires an exclusive repository lock inside the app
3. Runs an unlock step
4. Runs restic check
5. Runs restic repair-index only if the check output suggests that repair
6. Saves the step-by-step result and updates the final status to healthy, error, or cancelled

Because Doctor holds an exclusive repository lock, it can block other repository operations such as backups, restores, and snapshot mutations while it runs.

When to use Run doctor Copy Chapter

• The repository status is error
• Last Error suggests metadata or index problems
• Operations keep failing after a crash or interrupted run
• You changed repository settings and want a fresh maintenance pass
• You want a stored Doctor Report before or after backend maintenance work

When to use Unlock Copy Chapter

Use Unlock when the problem is specifically stale repository locks, for example after:

• A crashed backup or restore
• A forced container restart
• A cancelled or interrupted maintenance run
• A Restic message that says the repository is locked

If the problem is not a lock issue, Unlock will not fix it.

What stats refresh actually recalculates Copy Chapter

The refresh button in Compression Statistics recalculates repository metrics using restic stats --mode raw-data, including:

• Stored size
• Uncompressed size
• Compression ratio
• Compression progress
• Compression space saving
• Snapshot count

This is useful when:

• The stats card is still empty after connecting an existing repository
• You deleted snapshots and want updated numbers
• Retention cleanup changed repository usage
• You want fresh size numbers without running Doctor

Reading the Doctor Report Copy Chapter

The Doctor Report stores each maintenance step with its output and any error text. In current builds, the steps you will typically see are:

• unlock
• check
• repair_index when suggested by restic

If a Doctor run is cancelled, the report can still contain partial step output from the work that completed before cancellation.

Practical workflows Copy Chapter

Repository is locked after a crash Copy Section

1. Use Unlock.
2. Retry the blocked backup or restore.
3. If problems continue, run Doctor.

Status is `unknown` Copy Section

1. Check whether you recently edited repository settings.
2. Use the stats refresh button if you only need updated size numbers.
3. Run Doctor if you want a fresh maintenance verdict.

Status is `error` Copy Section

1. Read Last Error.
2. Expand the Doctor Report and identify the failing step.
3. Fix the real problem first, such as credentials, backend reachability, or repository corruption.
4. Run Doctor again after the fix.

Related docs Copy Chapter

• Repositories
• Recovery keys and repository passwords

import { Callout } from "fumadocs-ui/components/callout";

Apps Docs Content Docs Guides Restoring (`apps/docs/content/docs/guides/restoring.mdx`) Copy Section

title: Restoring Data Copy Chapter

Zerobyte lets you recover data in two ways:

• Restore, writes files back to a filesystem path
• Download, retrieves the selected contents without restoring them directly into a mounted destination

This guide covers when to use each option, how the restore form works, and what to do when a destination rejects ownership or permission changes.

Before you restore Copy Chapter

Before starting a restore, check these basics:

• the repository is reachable and unlocked
• the target path is writable
• the destination has enough free space

If you are restoring into a path that is bind-mounted into the container, make sure it is not mounted read-only. Read-only mounts can be backed up, but they cannot accept restores back into the original location.

Restore vs Download Copy Chapter

Use Restore when you want Zerobyte to write files back onto a filesystem path.

Use Download when you want to recover the contents without restoring them directly into the current mounted destination.

As a rule of thumb:

• use Restore for normal recovery back to a server path
• use Download for one-off recovery to your workstation, or when a mounted destination keeps failing on permissions or metadata

In the current UI, Download is available when you select a single item, or when you leave the selection empty and download the snapshot contents directly.

Standard restore workflow Copy Chapter

Choosing the restore location Copy Chapter

Original location Copy Section

Original-location restore is convenient when you want to put the snapshot back exactly where it came from.

Use it when:

• the original path still exists
• the path is writable
• you are intentionally restoring back in place

Be careful with it because it targets live paths.

Custom location Copy Section

Custom-location restore writes the recovered data to another path that you choose.

This is the safer default when:

• you want to inspect the recovered files first
• you are restoring onto a different server or container
• the original location is no longer correct
• you expect permission or metadata problems on the final destination

Overwrite modes Copy Chapter

Zerobyte exposes Restic's overwrite behavior in the restore form.

Always overwrite Copy Section

Replace existing files with the snapshot version. This is the most direct in-place restore mode.

Only if content changed Copy Section

Overwrite existing files only when their content differs from the snapshot. This avoids replacing identical files unnecessarily.

Only if snapshot is newer Copy Section

Overwrite existing files only when the snapshot version has a newer modification time.

Never overwrite Copy Section

Restore only missing files. Existing files are left in place.

Advanced option: excluding extended attributes Copy Chapter