Self-Host Zerobyte and Access It with Localtonet

What Zerobyte does and how this deployment works

Zerobyte is an open-source backup automation service built on Restic. Restic remains the underlying backup engine, while Zerobyte provides a web control plane for routine administration. Instead of maintaining separate command-line scripts and cron jobs, an operator can use the interface to connect source volumes, create backup repositories, define schedules and retention policies, monitor runs, browse snapshots, restore data, and perform repository maintenance.

The project supports sources such as local directories, NFS, SMB/CIFS, WebDAV, SFTP, and rclone-backed storage. Backup repositories can use local storage, S3-compatible services, Google Cloud Storage, Azure Blob Storage, REST servers, SFTP targets, and providers available through rclone. The exact source and destination configuration depends on your storage systems, credentials, permissions, and desired recovery design.

Zerobyte runs as a Docker container. Its web interface and API listen on port 4096 by default. Docker Compose describes the container image, port mapping, environment variables, capabilities, devices, and persistent volumes. The application data directory inside the container is /var/lib/zerobyte, and that directory must be mapped to durable local storage on the host.

Localtonet is a separate layer in the deployment. Zerobyte continues running on your own server and remains responsible for backup management and application authentication. Our client establishes an outbound connection from a device that can reach Zerobyte to a Localtonet relay server. An HTTP tunnel then connects a public HTTPS address to the local Zerobyte HTTP endpoint. The tunnel is available only while the selected Localtonet client is connected and the tunnel is running.

Separate the control plane from the backup data

The Zerobyte application directory is not the same thing as a backup repository or a source directory. The application directory contains the state required to operate Zerobyte, including configuration, database content, and encryption-related material. Source directories are the files you want to protect. Repositories are where Restic snapshots are stored. Treat all three as distinct resources when planning permissions, capacity, persistence, and disaster recovery.

A working dashboard is also not proof that a backup is recoverable. A sound deployment includes a successful backup run, snapshot inspection, repository health checks, and a test restore to a safe destination. Remote access makes administration more convenient, but it does not replace backup validation.

Prerequisites and deployment decisions

Zerobyte requires a server with Docker and Docker Compose. Docker Compose is included with Docker Desktop, while Linux server installations may provide it as a separate Compose plugin. This guide uses the modern docker compose command form rather than the legacy standalone docker-compose form.

You also need local host storage for /var/lib/zerobyte, a timezone appropriate for the server, and a way to generate a random application secret. If you plan to back up host directories, identify their exact host paths before creating the Compose file. If you plan to mount NFS, SMB, WebDAV, or SFTP sources from inside Zerobyte, use the standard installation and understand why it grants additional container privileges.

Verify Docker and Docker Compose before continuing:

docker --version
docker compose version

Both commands should return version information. If either command is unavailable, install the missing component using the instructions appropriate for your operating system and Docker distribution. The Zerobyte evidence used for this guide does not establish one universal Docker installation command across all supported host platforms, so we do not recommend copying an unverified package-manager command.

Choose the standard or simplified deployment

Prefer the simplified deployment when local bind-mounted directories meet your requirements. It removes capabilities that are unnecessary for that use case. If a network share is already mounted by the host operating system, you may be able to expose that mounted path to the container as a local bind mount. You still need to evaluate ownership, permissions, ACL behavior, and whether the mounted view preserves the metadata you expect to recover.

Special persistence requirement for TrueNAS

On TrueNAS, the host /var/lib path is ephemeral and can be reset during system upgrades. Create a dedicated ZFS dataset and map that durable dataset to /var/lib/zerobyte inside the container. The documented example uses /mnt/tank/docker/zerobyte, but your pool and dataset path may differ.

volumes:
  - /etc/localtime:/etc/localtime:ro
  - /mnt/tank/docker/zerobyte:/var/lib/zerobyte

This mapping preserves Zerobyte's configuration, database, and keys across TrueNAS upgrades. Confirm that the dataset exists and that Docker can access it before starting the container.

Install Zerobyte with Docker Compose

The official installation sequence has five stages: create the Compose configuration, set the environment variables, configure volume mounts, start the container, and access the web interface. Complete the local installation before creating a public tunnel. This separation makes it much easier to determine whether an error belongs to Zerobyte, Docker, host networking, or the remote-access layer.

Standard Compose configuration for remote mounts

The following configuration follows the documented standard deployment. Replace the timezone and secret before starting it. The example initially binds the application to the host loopback interface because the intended workflow is local access followed by an outbound Localtonet tunnel running on the same machine.

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.42
    container_name: zerobyte
    restart: unless-stopped
    cap_add:
      - SYS_ADMIN
    ports:
      - "127.0.0.1:4096:4096"
    devices:
      - /dev/fuse:/dev/fuse
    environment:
      - TZ=Europe/Zurich
      - BASE_URL=http://localhost:4096
      - APP_SECRET=REPLACE_WITH_YOUR_GENERATED_SECRET
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/lib/zerobyte:/var/lib/zerobyte

Generate the required secret with:

openssl rand -hex 32

Copy the command's output into APP_SECRET. Keep it confidential. Zerobyte uses this random value to encrypt sensitive data in its database, and the required value must be at least 32 characters. Do not paste it into tickets, screenshots, shell transcripts intended for publication, or a public source repository.

Simplified Compose configuration for local directories

If your backup sources are local directories mounted into the container, remove SYS_ADMIN and /dev/fuse. The following example maps one host directory to /mydata as read-only. Replace /path/to/your/directory with a real host path.

services:
  zerobyte:
    image: ghcr.io/nicotsx/zerobyte:v0.42
    container_name: zerobyte
    restart: unless-stopped
    ports:
      - "127.0.0.1:4096:4096"
    environment:
      - TZ=Europe/Zurich
      - BASE_URL=http://localhost:4096
      - APP_SECRET=REPLACE_WITH_YOUR_GENERATED_SECRET
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /var/lib/zerobyte:/var/lib/zerobyte
      - /path/to/your/directory:/mydata:ro

Inside Zerobyte, the source is available as /mydata, not under its original host path. You can add other explicit mappings such as /photos, /documents, or /media. Do not map the entire host filesystem merely for convenience. Give the container access only to directories it needs.

A read-only source is safer when Zerobyte only needs to create backups. It also prevents restoration to the original location. For restore testing, select a separate writable destination rather than weakening source protections without a clear operational need.

Understand the important environment variables

Use an HTTP or IP-based BASE_URL for the initial local check. Zerobyte disables secure cookies for HTTP or IP-address access so local setup can work. An HTTPS domain causes secure cookies to be enabled, which is the appropriate behavior for a production address. When the final Localtonet public HTTPS URL is known, update BASE_URL to that exact public origin and restart the container.

Do not enable TRUST_PROXY automatically just because a tunnel is involved. Its documented function is specifically to trust an existing X-Forwarded-For header from a reverse proxy. Whether it is appropriate depends on your complete request path and the headers reaching Zerobyte. Leave the default in place unless you have verified that your deployment requires a change.

Start the service

From the directory containing compose.yaml, run:

docker compose up -d
docker compose ps

The first command creates and starts the container in detached mode. The second shows its current state. If the container does not remain running, inspect its logs:

docker compose logs -f zerobyte

The -f option follows new log entries. Stop following the output when you have collected the information you need. Never share logs publicly without checking them for private hostnames, filesystem paths, repository addresses, account information, or other sensitive details.

Complete first-run setup and create a backup workflow

Open http://localhost:4096 from the Docker host when using the loopback port mapping. On first access, Zerobyte prompts you to create an administrator account. This account has full access to backup management, so use unique credentials and store them safely. The supplied evidence does not establish a universal default username or password because the operator creates the account during first access.

Zerobyte organizes the backup lifecycle around four practical stages: connect a source volume, create a repository, define a backup schedule, and monitor or restore snapshots. The exact form fields vary with the selected storage protocol, so use values issued by your storage system rather than copying generic examples.

1. Connect a source volume

A volume identifies data that Zerobyte can read. For a local bind mount, use the container-side path from compose.yaml, such as /mydata or /photos. A host path that was not mapped into the container will not become available merely because it exists on the Docker server.

For NFS, SMB, WebDAV, or SFTP mounting inside Zerobyte, use the standard deployment with SYS_ADMIN and /dev/fuse. Remote mounts can expose translated ownership, permissions, and ACL metadata rather than exactly reproducing the source system's native view. If metadata fidelity matters to recovery, validate representative files, ownership behavior, permissions, symlinks, and ACLs through a test restore.

2. Create a backup repository

The repository stores encrypted Restic snapshots. Zerobyte supports local repositories and remote destinations including S3-compatible storage, Google Cloud Storage, Azure Blob Storage, REST servers, SFTP, and rclone-backed providers. Select a destination that fits your failure model. Keeping the repository on the same disk as the source may help with accidental deletion, but it does not protect against failure or loss of that disk.

Repository credentials and recovery information are critical. Preserve any keys or recovery material required to access snapshots independently of the live Zerobyte container. A backup set that exists but cannot be decrypted is not recoverable.

3. Define the backup job

Create a job that connects the chosen volume and repository. Define a schedule appropriate for how quickly your source changes and how much data loss you can tolerate. Zerobyte supports cron-based scheduling, include and exclude rules, manual runs, compression choices, and retention policies.

Confirm that TZ represents the intended timezone before relying on a schedule. A syntactically correct job can still run at the wrong local time if the container timezone is wrong. Retention rules should reflect both recovery needs and repository capacity. Avoid deleting older recovery points aggressively until you have observed actual change rates and repository growth.

4. Run, monitor, and restore

Trigger an initial backup and watch its status. After it completes, inspect the snapshot history and confirm that expected paths are present. Then perform a restore to a separate test directory. Open several restored files and compare them with their sources. This checks much more than a green job status: it exercises repository access, decryption, snapshot traversal, write permissions, and the practical recovery procedure.

Verify Zerobyte locally before exposing it

Local verification creates a clean troubleshooting boundary. If Zerobyte does not work at the local URL, adding a tunnel cannot repair the container, application configuration, storage permissions, or repository credentials.

Begin with container status:

docker compose ps

Confirm that the zerobyte container remains running. Then inspect its logs:

docker compose logs -f zerobyte

Look for configuration errors involving missing required environment variables, invalid filesystem paths, permission failures, or an inability to use a configured mount. Correct the underlying setting in compose.yaml, recreate the container, and check again.

With the recommended loopback binding, open:

http://localhost:4096

A successful check should display the Zerobyte web interface. Complete the administrator setup if this is the first visit, sign in, and navigate through the interface. If you configured a local source, verify that the container-side path can be selected and that its expected content is visible to the application.

If you intentionally used 4096:4096 rather than a loopback binding, the documented network URL is:

http://<your-server-ip>:4096

Use that form only from a network where the server address is reachable and where access to the port is appropriately restricted. Do not create an internet-facing router port forward for this workflow.

Local readiness checklist

• Docker and Docker Compose report valid versions.
• The Zerobyte container remains running.
• The logs do not show unresolved startup or storage errors.
• The interface loads at the address configured in BASE_URL.
• The initial administrator account has been created securely.
• Persistent application storage maps to a durable local host path.
• Expected source paths are visible inside the container.
• An initial job can produce a snapshot in the selected repository.
• A test restore succeeds to a safe destination.

Access Zerobyte remotely with a Localtonet HTTP tunnel

Once local access works, an HTTP tunnel can publish the web interface through Localtonet. Our client runs on the Zerobyte host or another device that can reach it. The client establishes an outbound connection to a selected relay server, and the running tunnel provides a public HTTPS address.

This does not turn Zerobyte into a VPN service and does not expose unrelated devices automatically. The HTTP tunnel targets the specific local IP address and port you configure. If the client and Zerobyte share a host, the narrowest target is normally 127.0.0.1 on port 4096. If they run on different devices, use an address reachable from the Localtonet client and protect that network path appropriately.

The currently available relay server values, process types, and account-specific options must be taken from the current Localtonet dashboard. We do not hardcode a region, server code, or generated hostname because those values can vary.

HTTP and File Server tunnels can use Random Sub Domain, Custom Sub Domain, or Custom Domain process types, and each serves content at a public HTTPS address. Custom-domain DNS requirements should always be checked against current Localtonet documentation before changing DNS records. For the simplest validation, use an address assigned through the current dashboard.

Update Zerobyte's public base URL

Zerobyte requires BASE_URL and uses it for cookie security and CORS. After Localtonet assigns the public HTTPS address, replace the initial local value with that exact origin. Do not copy the placeholder below literally:

environment:
  - TZ=Europe/Zurich
  - BASE_URL=https://YOUR_ASSIGNED_PUBLIC_HOST
  - APP_SECRET=REPLACE_WITH_YOUR_EXISTING_GENERATED_SECRET

Keep the same application secret. Changing BASE_URL does not require rotating APP_SECRET. After saving the Compose file, recreate the service:

docker compose down
docker compose up -d
docker compose ps

Test the assigned public address after the container is running. An HTTPS domain causes Zerobyte to enable secure cookies. If the login page appears but authentication loops, requests fail CORS checks, or the browser returns to the wrong address, recheck BASE_URL for an exact scheme and hostname match.

Routine operation, security, and performance

Use least privilege for storage access

Mount only the source directories Zerobyte needs. Use :ro when a source should never be modified by the container, and restore to a separate writable location. If remote mount support is unnecessary, use the simplified deployment rather than retaining SYS_ADMIN and /dev/fuse.

Protect compose.yaml because it may contain APP_SECRET and deployment paths. Zerobyte also supports APP_SECRET_FILE as an alternative to an inline secret, and that option is mutually exclusive with APP_SECRET. Secret-file handling depends on your container environment, so verify permissions and mounting behavior before switching.

Monitor the application and backup outcomes

Use docker compose ps for container state and docker compose logs -f zerobyte when investigating application behavior. Inside Zerobyte, review backup run status, next-run timing, snapshot history, and repository health. Notifications can be configured through supported channels, but notification delivery should be tested rather than assumed.

Treat silent operation as something to verify, not proof of success. A useful operating routine includes reviewing failures, investigating unexpectedly short or long runs, checking repository growth, confirming retention results, and periodically restoring representative data.

Control backup CPU use

If Restic backup processes create excessive CPU pressure, Zerobyte supports GOMAXPROCS. For example:

environment:
  - GOMAXPROCS=2

Restart the container after changing it. The setting applies to Restic processes started after the restart and does not change operations that are already running. Choose a positive integer appropriate for your host rather than assuming that 2 is ideal for every server.

Repository compression also affects CPU use. Zerobyte supports off, auto, and max compression behavior through Restic. Turning compression off can reduce CPU consumption, auto provides the usual balance, and max can save more space at the cost of additional CPU work. Measure using your own files and hardware before selecting a policy.

Plan for maintenance and recovery

Preserve the application data directory, but do not mistake it for the backup repository. Record where repositories live, how they are authenticated, what recovery keys are needed, and how an operator would restore data if the Zerobyte server were unavailable. Zerobyte provides repository maintenance functions such as health checks, stale-lock handling, and repository statistics, but operational documentation is still necessary.

Before changing a 0.x version, read the release notes and identify configuration or data-model changes. Confirm that persistent storage is healthy, record the currently deployed image tag, and test the upgraded system before declaring maintenance complete. This article uses the evidenced v0.42 image configuration. It does not claim that this remains the newest version at the time you deploy, so confirm the desired release rather than changing the tag blindly.

Troubleshooting Zerobyte and Localtonet access

The container exits or repeatedly restarts

Run docker compose ps, followed by docker compose logs -f zerobyte. Check that BASE_URL and either APP_SECRET or APP_SECRET_FILE are configured correctly. Confirm that YAML indentation is valid, the application data host path exists, and Docker has permission to use the configured paths and devices.

If you selected the standard deployment, verify that /dev/fuse exists and can be passed to the container. If you do not need internal remote mounts, switch to the simplified configuration rather than trying to force unsupported capabilities onto the host.

The browser cannot open localhost:4096

Confirm that the browser is running on the Docker host. A loopback address always refers to the machine making the request. If you type localhost on a different computer, it points to that computer, not the Zerobyte server.

Next, confirm the container is running and that Compose maps 127.0.0.1:4096 to container port 4096. If you changed the internal PORT, the mapping and local target must be consistent with that change.

A local source directory is missing

Zerobyte can see only paths available inside its container. Check the bind mount in compose.yaml. For a mapping such as /path/to/your/photos:/photos:ro, Zerobyte must use /photos. It cannot use the original host path unless that same path was deliberately mapped into the container.

After adding or changing mounts, recreate the container:

docker compose down
docker compose up -d

A backup receives permission errors

Check host permissions, ownership, ACL behavior, and the access mode of the bind mount. A read-only source is suitable for backup reads but cannot accept an in-place restore. Network-mounted filesystems can present translated metadata, so reproduce the problem with a representative file and verify access from the container's view rather than relying only on host-side permissions.

The Localtonet public URL does not load

First confirm that Zerobyte still works locally. Then verify that the Localtonet client is connected, the correct device token was selected, and the tunnel was started rather than only created. Confirm that the local target is reachable from the device running our client.

If both services run on the same host, target 127.0.0.1:4096. If the client runs on another device, 127.0.0.1 points to that other device and cannot reach Zerobyte. Use an appropriately protected address reachable from the client and make sure Docker is listening on the required host interface.

The public page loads but login or browser requests fail

Compare Zerobyte's BASE_URL with the exact public HTTPS origin assigned to the tunnel. Scheme, hostname, and any relevant port must match the way users access the service. Recreate the container after changing the environment variable. Do not add speculative values to TRUSTED_ORIGINS or enable TRUST_PROXY without identifying the specific browser or forwarded-header problem they are intended to solve.

Schedules run at the wrong time

Check the container's TZ value. Zerobyte identifies timezone configuration as crucial for accurate scheduling. Set a valid timezone appropriate for your location or use UTC, then restart the container. Review the next scheduled run in the interface after making the change.

Backups consume too much CPU

Consider a positive GOMAXPROCS limit and restart the container so it applies to newly started Restic processes. Review repository compression as well. Use off to reduce compression work, auto for the normal balance, or max when storage reduction is worth more CPU usage. Avoid changing several variables at once because doing so makes the result harder to interpret.

Frequently asked questions