Technical Walkthrough

From install to protected
in 60 seconds

A lightweight background daemon on every device handles scanning, compressing, encrypting, threat scoring, and uploading — automatically, on schedule, without interrupting your work.

1

Install Agent

macOS, Windows, or Linux. Registers as launchd / systemd daemon automatically.

2

Configure Policy

Set backup paths, schedules, and retention from the cloud dashboard in 60 seconds.

3

Scan, Detect & Encrypt

SHA-256 change detection, zstd compression, 5-layer threat scoring, AES-256-GCM.

4

Upload & Air-Gap

Presigned URLs to Wasabi. B2 air-gap copy every 30 min. AWS S3 for 7-year archive.

Step 1

Install the Agent

The Grovia Vault agent is a small, single-binary daemon. Download it from your dashboard, run the installer, and it registers itself with the OS service manager automatically.

  • macOS: registers as a launchd daemon in /Library/LaunchDaemons/
  • Linux: registers as a systemd unit in /etc/systemd/system/
  • Windows: registers as a Windows Service
  • Auto-starts on boot, runs as low-privilege user
  • Uses less than 0.5% CPU during idle scanning
  • Maximum 50 MB RAM footprint
Enrollment Tokens: MSPs can pre-generate enrollment tokens from the dashboard. Paste the token during install to automatically associate the agent with the correct tenant and apply the pre-configured policy — zero manual configuration.
# macOS — one-liner install curl -sSL https://vault.groviaos.com/install.sh | \ ENROLLMENT_TOKEN="gv_tok_xxxxx" bash # The installer: # 1. Downloads the grovia-vault binary # 2. Verifies SHA-256 checksum # 3. Copies to /usr/local/bin/grovia-vault # 4. Creates /etc/grovia-vault/config.json # 5. Installs and starts the launchd plist # 6. Registers agent with the API using token $ sudo launchctl list | grep grovia 1234 0 com.groviaos.vault.agent # Linux — systemd $ systemctl status grovia-vault ● grovia-vault.service - Grovia Vault Backup Agent Loaded: loaded (/etc/systemd/system/grovia-vault.service) Active: active (running) since ... Main PID: 2847 (grovia-vault) Tasks: 4 (limit: 4915) Memory: 18.2M
# Example policy pushed from dashboard # (agent polls every 60 seconds for updates) { "backup_paths": [ "/Users/jitu/Documents", "/Users/jitu/Desktop", "/var/www/myapp", "C:\\Users\\Finance\\Accounts" ], "schedule": "0 */4 * * *", // every 4 hours "retention_days": 90, "bandwidth_limit_kbps": 2048, // 2 Mbps upload cap "threat_action": "alert_and_pause", "exclude_patterns": [ "*.tmp", "*.log", ".DS_Store", "node_modules/**", ".git/**" ], "compression": "zstd_fast", "encryption": "aes256gcm" }
Step 2

Configure Your Policy

Open the cloud dashboard, define your backup policy, and push it. Agents poll for configuration updates every 60 seconds — no restart required.

  • Select folders and drives to protect
  • Set cron-based schedules (e.g. every 4 hours)
  • Configure bandwidth throttle to avoid saturating your connection
  • Set retention period (7 days to 7 years)
  • Choose threat-response: alert only, alert + pause, or alert + block
  • Exclude patterns for temp files, build artifacts, and large binaries
Push in 60 seconds: Policy changes made in the dashboard propagate to all enrolled agents on their next poll cycle. For urgent changes (e.g. pausing backups during an incident), you can force an immediate push from the agent management console.
Step 3

Scan, Detect & Encrypt

This is where the real work happens. Every backup run executes a pipeline: scan for changes → score for threats → compress → encrypt → prepare for upload.

3a

SHA-256 Change Detection

The agent maintains a local index of every file's SHA-256 hash, last-modified timestamp, and file size. On each backup run, it scans the configured paths and computes hashes only for files that have changed size or modification time (inode check first for performance). Only genuinely changed blocks are added to the backup queue — skipping identical files entirely.

3b

5-Layer Threat Scoring

Before a file enters the encryption pipeline, it passes through the threat scoring engine. Each layer contributes points to a composite threat score (0–100). Files scoring below 30 are safe to back up. Files scoring 30–60 trigger a Watch alert. 60–80 triggers an Alert. Above 80, the backup is paused and an immediate notification is sent.

threat_score = 0 + entropy_score (0–35) # Shannon entropy > 7.5 + mime_mismatch (0–25) # Magic byte vs extension + extension_match (0–30) # Known ransomware extension + ransom_note (0–40) # README/DECRYPT/RECOVER + velocity_score (0–20/pt) # >10x baseline change rate if score >= 80: BLOCK + ALERT if score >= 60: ALERT (email + webhook) if score >= 30: WATCH (log) else: SAFE → continue to compress
3c

zstd Compression

Files that pass threat scoring are compressed using Facebook's zstd algorithm at the "fast" preset. zstd is chosen because it achieves near-LZ4 speeds while delivering compression ratios comparable to zlib — ideal for backup where throughput matters. Files that are already compressed (JPEG, PNG, MP4, ZIP, etc.) are detected by their magic bytes and skipped to avoid wasting CPU on incompressible data.

# Compression logic (simplified) if file.mime_type in PRECOMPRESSED_TYPES: skip compression (passthrough) else: compressed = zstd.compress(data, level=1) # fast preset # Only use compressed version if it's actually smaller if len(compressed) < len(data) * 0.95: data = compressed
3d

AES-256-GCM Encryption

Every (compressed) file chunk is encrypted with AES-256-GCM. The encryption key is derived from your backup passphrase using SHA-256 — this happens locally on your device. The server never receives your passphrase or the derived key. GCM mode also provides authenticated encryption, meaning any tampering with the ciphertext will be detected on decryption. A unique 12-byte nonce is generated for every chunk.

# Key derivation (on device, never transmitted) key = SHA256(passphrase) # 32-byte key # Per-chunk encryption nonce = os.urandom(12) # 96-bit unique nonce cipher = AES.new(key, AES.MODE_GCM, nonce=nonce) ciphertext, tag = cipher.encrypt_and_digest(plaintext) # Chunk stored as: nonce + tag + ciphertext chunk = nonce + tag + ciphertext # server sees only this
Step 4

Upload & Air-Gap

Encrypted chunks are uploaded directly to object storage via presigned URLs. Your cloud credentials never touch the agent — eliminating the most common attack vector for backup systems.

  • Agent requests a presigned PUT URL from the API
  • URL has a 15-minute expiry — limited blast radius if intercepted
  • Agent uploads chunk directly to Wasabi via HTTPS
  • API records the chunk manifest in PostgreSQL
  • Every 30 minutes, a server-side job copies new objects from Wasabi to B2
  • Nightly job archives to AWS S3 Glacier for long-term retention
Why presigned URLs? If your device is compromised, the attacker cannot access, delete, or modify your backup storage — they only have a 15-minute window to upload to a specific path. They don't have list, delete, or download permissions.
# Upload flow (simplified) # 1. Request presigned URL from API POST /api/v1/backup/presign Authorization: Bearer <jwt_token> { "chunk_id": "sha256:abc123...", "size_bytes": 524288, "agent_id": "agt_xyz" } # Response { "upload_url": "https://s3.wasabisys.com/...", "expires_in": 900, // 15 minutes "chunk_path": "tenants/t_001/2025/07/chunk_abc123" } # 2. Agent PUTs directly to Wasabi (no API in path) PUT https://s3.wasabisys.com/gv-backups/tenants/... Content-Type: application/octet-stream [encrypted chunk bytes] # 3. Confirm upload to API (records manifest) POST /api/v1/backup/confirm { "chunk_id": "sha256:abc123...", "etag": "abc..." } # --- Every 30 minutes (server-side) --- # B2 air-gap copy job for chunk in new_chunks_since_last_run(): b2_client.copy(chunk.wasabi_path, chunk.b2_path)
FAQ

Common questions

How long does the first backup take?
The initial backup is a full scan of all configured paths. Time depends on data volume and your upload bandwidth. At a 10 Mbps upload, expect roughly 4 GB per hour. Subsequent backups are incremental — only changed blocks are uploaded — which typically completes in minutes. You can also configure a bandwidth throttle to avoid saturating your connection during business hours.
Does the agent slow down my computer?
No perceptibly. The agent is designed to run at the lowest OS scheduling priority. During idle periods (no active keyboard/mouse input), it may use up to 2–3% CPU for scanning. During active use, it backs off to near zero. The agent maintains under 50 MB of RAM and uses a configurable bandwidth cap (default: 2 Mbps upload, adjustable in your policy).
What happens if my computer is off when a backup is scheduled?
The agent uses a "catch-up" model. When your device comes back online, it checks whether a scheduled backup was missed and runs it immediately. If multiple scheduled windows were missed, it runs a single catch-up backup covering all changes since the last successful run. You won't have gaps in your backup history.
Can I back up network drives or external disks?
Yes. Any path that is accessible from the filesystem can be added to the backup paths — including mounted network drives (SMB/NFS), external USB disks, and NAS volumes. The agent will handle them identically to local paths. Note that network paths may be slower to scan depending on your network speed.
What if the ransomware detection fires incorrectly (false positive)?
False positives can occur with legitimately encrypted files (e.g., a VeraCrypt container, a PGP-encrypted archive) or software that renames files with unusual extensions. When a threat alert fires, backups pause but your data is not deleted. You can review the flagged files in the dashboard, mark them as safe, and resume. You can also whitelist specific paths or extensions that are known-good in your environment.
How do I restore files?
Log into the Grovia Vault dashboard, navigate to Restore, choose the device and backup point-in-time, then browse or search for the files you want. You can restore individual files, folders, or a full backup snapshot. The download is decrypted client-side using your passphrase before the files are written to disk. Alternatively, the agent CLI supports headless restore: grovia-vault restore --snapshot 2025-07-20T06:00 --path /Users/jitu/Documents
Ready to deploy?

Your first device is protected in 60 seconds

Free plan — 1 device, 10 GB, full encryption and ransomware detection. No credit card.

Start for free Talk to an engineer