Documentation

Latchbox 0.6.4 — configuration backups and local file backups for a home network. MIT licensed. No cloud involved.

Installation

Latchbox ships as a single static binary plus a companion service unit. Two ways to get it: a prebuilt package, or building from source.

Prebuilt package

$ tar -xzf latchbox-0.6.4-linux-amd64.tar.gz
$ sudo install -m 755 latchbox /usr/local/bin/latchbox
$ latchbox --version
latchbox 0.6.4

Build from source

Requires a recent Go toolchain (1.21+) and make.

$ tar -xzf latchbox-0.6.4-src.tar.gz
$ cd latchbox-0.6.4
$ make build
$ ./bin/latchbox --version
latchbox 0.6.4

The build target produces a single self-contained binary. There are no runtime dependencies beyond the config file.

Configuration — latchbox.toml

Latchbox reads exactly one configuration file, latchbox.toml, resolved in this order: --config flag, ./latchbox.toml, ~/.config/latchbox/latchbox.toml.

[storage]
path = "/srv/latchbox"
retention = 14

[schedule]
interval = "6h"
jitter = "10m"

[web]
listen = "127.0.0.1:7788"
api_key = "change-me"

[[targets]]
name = "core-router"
type = "keenetic"
address = "192.168.1.1"
username = "admin"
password_env = "LATCHBOX_CORE_ROUTER_PASSWORD"

[[targets]]
name = "photos"
type = "filesystem"
source = "/home/user/Pictures"

Section	Key	Meaning
`storage`	`path`	Directory where all snapshots are written.
`storage`	`retention`	Number of snapshots to keep per target before pruning the oldest.
`schedule`	`interval`	How often the scheduler runs each target (e.g. `6h`, `30m`, `1d`).
`schedule`	`jitter`	Random delay added to each run to avoid fixed-time spikes.
`web`	`listen`	Address and port the local web interface binds to.
`web`	`api_key`	Key required in the `X-Latchbox-Key` header for API requests.
`targets`	`name`	Unique identifier for the target, used in snapshot paths and CLI output.
`targets`	`type`	One of `keenetic`, `mikrotik`, `openwrt`, `tplink`, `filesystem`.
`targets`	`address`	Router IP address, for router-type targets.
`targets`	`source`	Local path to back up, for `filesystem` targets.
`targets`	`password_env`	Name of the environment variable holding the router credential. Never stored in the file itself.

CLI commands

Command	Description
`latchbox init`	Writes a starter `latchbox.toml` in the current directory.
`latchbox run [target]`	Runs a backup immediately. With no target given, runs all configured targets.
`latchbox list`	Lists targets and their snapshots.
`latchbox restore <snapshot-id>`	Restores a snapshot to its original location, or to a path given with `--out`.
`latchbox verify [snapshot-id]`	Checks stored snapshots against their recorded checksums.
`latchbox serve`	Starts the scheduler and the local web interface, using the settings from `[web]`.

$ latchbox run core-router
core-router: snapshot 2026-08-24T09:00:00Z written, 41 KiB, checksum ok

$ latchbox list
TARGET        SNAPSHOTS   LAST RUN              SIZE
core-router   14          2026-08-24T09:00:00Z  41 KiB
photos        3           2026-08-23T02:00:00Z  2.1 GiB

Scheduling

When Latchbox runs as latchbox serve, each target is backed up on the interval set in [schedule]. The jitter value spreads runs out so multiple targets don't fire at the exact same second. Manual runs via latchbox run do not affect the schedule and can be issued at any time, including while serve is active.

Router targets

Keenetic

Connects over the router's local management interface using the credentials in username / password_env. Pulls the exported system configuration.

MikroTik

Uses the RouterOS API to request an export of the running configuration. Requires an API-enabled user account on the router.

OpenWrt

Reads /etc/config over the management connection and archives it as a single snapshot.

TP-Link

Uses the router's configuration export function through its local admin interface.

All router types are polled over the local network only. Latchbox does not reach outside 192.168.x.x for any target.

Storage and versioning

Snapshots are written under storage.path, one subdirectory per target, one file per run. Each snapshot is named by its UTC timestamp and given a short id used by restore and verify. A checksum is recorded alongside every snapshot at write time.

Once storage.retention is exceeded for a target, the oldest snapshot is deleted after the new one is confirmed written and verified — Latchbox never removes a snapshot before its replacement exists on disk.

Troubleshooting

target unreachable

Check that the router's address in latchbox.toml matches its current LAN IP and that the management interface is reachable from the host running Latchbox.

verify fails

A checksum mismatch means the stored snapshot no longer matches what was written. Run latchbox verify to identify which snapshot is affected, then re-run a fresh backup for that target.

web interface not reachable

The web interface listens on web.listen, which defaults to 127.0.0.1 and is not reachable from other machines by design. Confirm latchbox serve is running.

api key rejected

The key sent in the X-Latchbox-Key header must match web.api_key exactly. Changing the value in latchbox.toml requires restarting latchbox serve.