#KopiaLens documentation

KopiaLens is an app for exploring, analysing and managing Kopia backup repositories. It runs in its own window or in your browser. It can run your backups the way KopiaUI does, or work alongside KopiaUI and the kopia command line. It never changes how kopia stores your data.

#Getting started

• Installing KopiaLens: Windows installer or portable, the macOS app, Linux AppImage, deb and rpm.
• First-time setup: connecting your repositories, protecting KopiaLens, and building the first index.
• Repositories: adding, renaming, reordering, checking and removing repositories.
• Running in Docker: the container, its folders, running as your own user, and mounting snapshots.
• Home Assistant: the add-on, opening it from the sidebar or its own port, and its folders.
• Backups: who runs a repository's backups, snapshots by hand, pausing, Tasks, snapshot scripts and checking backups.
• Notifications: alerts in the app and tray, KopiaLens's webhook (works with ntfy), and kopia's email, Pushover and webhook profiles.

#Guides

• Start backing up from scratch: new to kopia? Create a repository, set a schedule and back up your first folder.
• Find what's using the most space: from the whole repository down to single files.
• Free up space safely: from the safest steps to the strongest.
• Exclude a folder and remove it from old snapshots: stop backing it up and take it out of the past.
• Restore files: find a file in your backups and get it back.
• Check your backups: are they running, complete and readable?
• Move backups from KopiaUI to KopiaLens: hand over schedules and maintenance without losing history.
• Clean up after a huge accidental backup: remove something big from every snapshot.
• Find files that change every day: the files that cost far more than their size.
• Test a retention policy before using it: see what it keeps and frees first.
• Use KopiaLens with an AI agent: safe access for agents, with your approval for deletes.
• Run KopiaLens behind a reverse proxy: your own address, with HTTPS from the proxy.

#Understanding KopiaLens

• How KopiaLens counts space: logical, physical and reclaimable sizes, deduplication, and why deleting doesn't always free space.
• Why deleting frees space only after maintenance: what kopia does with deleted data, and when the space comes back.
• How indexing works: what the index holds, how it's built, and what it costs your computer.
• KopiaLens alongside KopiaUI: sharing repositories with KopiaUI safely.
• Using KopiaLens with BlinkDisk: connecting a vault, who runs backups and maintenance, the computer name, and merging split histories.
• Hardware and memory: memory, disk space and the setups KopiaLens is measured on.
• Glossary: every term KopiaLens uses, in one place.

#Security

• Sign-in and your account: the KopiaLens password, staying signed in, signing out other devices, and resetting a forgotten password.
• Encryption: encrypting what KopiaLens stores on disk, the recovery key, and unlocking after a restart.
• Remote access and HTTPS: who can open KopiaLens, HTTPS certificates, and running it behind a reverse proxy.
• API tokens: access for scripts, the command line and AI agents, what a token can and can't do, and revoking one.

#For scripts and agents

• Command line: klens for scripts and AI agents, signing in once, removing files safely, and approvals.
• API: calling KopiaLens over HTTP, the stable routes, refusals, and approvals.

#Help and privacy

• FAQ and troubleshooting: common questions, and what to do when something doesn't work.
• Getting help: reporting a problem, the diagnostics bundle, checking for updates, and the desktop app's zoom.
• Update checks and usage stats: what the daily check sends, what's never sent, and how to turn it off.

#Pro

• Free and Pro: what Pro adds, adding your licence, renewals, and licences in Docker.

#Screens

• Dashboard: every source, what it holds and what it costs.
• Snapshots: pin, compare, restore and delete snapshots.
• Simulate: what a retention policy would keep and free.
• Tree: folders and files by size, in any snapshot.
• Search: find files across every snapshot.
• Churn: what keeps adding new data.
• Repository: health, storage, maintenance and settings.
• Excluded: what on your disks no backup covers.
• Policies: every policy, and how they apply.
• Tasks: backups, maintenance and jobs, running and finished.
• Logs: what KopiaLens did, and its own log.
• Backblaze: what Backblaze Personal Backup backs up.
• Indexing: when the index updates, the indexing panel, and index backups.
• Disk scanning: how KopiaLens reads your disks, and checking network shares and other computers.
• Settings: every section and its defaults.
• Tables: columns, alignment, widths, times and rows per page in any table.

#Panels

• File panel: one file's versions, space and copies.
• Folder panel: one folder's contents, space and sources.
• Delete from backups: remove files and folders from your snapshots.
• Deleting snapshots and sources: delete whole snapshots or every snapshot of a folder.
• Prune versions: keep the versions you want and remove the rest.
• Exclude: keep a file or folder out of future snapshots.
• Restore, download and mount: get files back from a snapshot.
• Policy editor: every policy setting.
• Maintenance: run kopia's maintenance by hand.
• New snapshot: back up any folder now.
• Job panel: a running action's progress and result.

#Thanks to Kopia

Thank you to the Kopia team and contributors. KopiaLens wouldn't exist without Kopia. It's one of the best backup engines out there: fast, secure and dependable, and I'm grateful to be able to build on it. KopiaLens is an independent project, not affiliated with or endorsed by the Kopia project.