Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Pachanga12/Kopia_Desk_Beta_1/llms.txt

Use this file to discover all available pages before exploring further.

Kopia Desk is a Windows desktop application built on Electron that backs up your folders — Pictures, Documents, Downloads, and more — to an external drive or USB stick. Instead of copying everything every time, it compares the current state of each folder against a manifest saved from the last session and copies only what is new or changed. Deleted files are noted in the manifest but left untouched in the backup, so nothing is silently lost. The result is a plain folder structure on your drive that any Windows PC can read without special software.

​
Key Features

Incremental Scanning

Recursively scans source folders and diffs them against the saved manifest. Uses a fast header+tail hash (64 KB each end) to skip files that only had their timestamp touched, falling back to a full SHA-256 stream when deep verification is enabled.

Adaptive Concurrency

Detects whether the destination is an SSD, HDD, or USB drive via PowerShell and tunes copy parallelism accordingly — up to 8 concurrent writes on NVMe/SSD for small files, down to 1–2 on spinning HDDs to avoid seek thrashing.

Content Deduplication

Maintains a content index (content-index.json) keyed by SHA-256 hash. When a file already exists in the backup under any name or folder, Kopia Desk creates an NTFS hardlink instead of a second physical copy, saving space without any external tool.

Versioning with Gzip

When versioning is enabled (default on), the previous copy of a changed file is compressed with gzip and stored in .kopia-data\versions\<date>\ before it is overwritten. Old versions are preserved across sessions.

Operation Journal

Every backup run writes an append-only JSONL journal. If a power cut or accidental disconnection interrupts the copy, Kopia Desk detects the leftover partial files on the next launch and offers to clean them up before starting a new run.

Full SHA-256 Verification

An optional deep-hash toggle computes a full SHA-256 over every file in the scan phase, not just the quick header+tail hash. Use it for a thorough integrity check when storage reliability matters more than speed.

Compare & Restore Tabs

The Compare tab finds files present in the backup but missing from your PC and lets you restore only those. The Restore tab copies an entire backup folder to any location you choose — useful when the original PC profile no longer exists.

Light / Dark Theme

A theme toggle in the top bar switches between light and dark modes. The preference is persisted in localStorage across sessions without touching the main process.

​
Configurable Exclusion Filters

Kopia Desk ships with a default set of exclusion patterns that are applied during every recursive scan. These patterns are loaded automatically at startup and passed to every scan; they keep metadata noise out of your backup without any manual configuration.
Default patternWhat it skips
Thumbs.dbWindows thumbnail cache
desktop.iniFolder metadata files
$RECYCLE.BINRecycle bin directories
System Volume InformationProtected system folder
.gitGit repository internals
node_modulesnpm dependency trees
*.tmpTemporary files
~$*Office lock files

​
Technology Stack

Kopia Desk is intentionally lean — there are no production npm dependencies. Everything runs on Node.js built-in modules.
LayerTechnology
Desktop shellElectron 43
RuntimeNode.js ≥ 20
UIVanilla HTML / CSS / JS (no framework)
File I/O & cryptoNode.js fs, crypto, zlib
Drive detectionchild_process → PowerShell Get-Volume / Get-PhysicalDisk
Test runnernode --test (native, no Jest)

​
Architecture Overview

Kopia Desk follows Electron’s three-layer security model strictly — the renderer process never touches the filesystem directly. 
┌─────────────────────────────────────────────────────────┐
│  main.js  (Node.js — full OS access)                    │
│  ├── lib/core.js  (scan, hash, drives, journal)         │
│  └── IPC handlers (24 channels via ipcMain.handle)      │
├─────────────────────────────────────────────────────────┤
│  preload.js  (contextBridge — isolated context)         │
│  └── window.kopiaAPI  (explicit allow-list only)        │
├─────────────────────────────────────────────────────────┤
│  renderer/  (no Node access, no nodeIntegration)        │
│  ├── index.html                                         │
│  ├── app.js   (UI logic, calls window.kopiaAPI)         │
│  └── styles.css                                         │
└─────────────────────────────────────────────────────────┘
  • Main process (main.js) runs with full Node.js access. It imports lib/core.js for all scan, hash, drive-detection, and journal logic, then wires each function to an IPC channel.
  • Renderer process (renderer/app.js) has nodeIntegration: false and contextIsolation: true. It can only call the functions explicitly listed in preload.js.
  • Preload bridge (preload.js) uses contextBridge.exposeInMainWorld to expose window.kopiaAPI — the only surface the renderer can reach.
  • lib/core.js is a pure Node.js module with no Electron dependency, making it directly testable with node --test.

​
Backup Storage Layout

All backup data lives under a single root on the destination drive. The metadata directory is hidden with Windows attrib +h +s so it stays out of the way during normal browsing. 
D:\KopiaDesk_Backup\
├── Pictures\               ← copied files (original structure preserved)
├── Documents\              ← copied files
└── .kopia-data\            ← hidden (attrib +h +s)
    ├── manifests\
    │   ├── Pictures.json       ← current state
    │   ├── Pictures.prev.json  ← previous state (one version back)
    │   └── Documents.json
    ├── versions\           ← gzip-compressed previous versions
    ├── journal\            ← append-only JSONL crash-recovery logs
    └── logs\               ← JSON operation reports

Installation

Clone the repo, install dependencies with npm, and run the app on Windows.

Quickstart

Back up your first folder in five minutes with a step-by-step walkthrough.

Backup Features

Deep dive into incremental diffing, deduplication, versioning, and concurrency.

API Overview

Reference for every IPC channel exposed by the main process.

Build docs developers (and LLMs) love

Get started for freeTalk to us