Restore Coolify storage safely
after an incident.
Preview changes before touching the disk. Apply only with explicit confirmation. Built for S3-compatible storage with isolated staging, traversal rejection, and atomic replace rollback.
Available via Homebrew, APT, statically linked binaries, or Go.
Predictable, transparent operations
Inspect outputs before executing changes. Every step produces deterministic status codes and structured output.
Engineered for worst-case resilience
Storage recovery is typically executed during high-stress incidents. coolrestore is built with strict defensive constraints to eliminate human error and corrupted archive propagation.
Safe by Default (Preview Plan)
Without the explicit --confirm flag, coolrestore never touches or creates target files. It calculates differences, validates safety, and prints a precise dry-run plan.
Atomic Replace Rollback
In replace mode, the staging directory is switched atomically via filesystem renames. If anything fails mid-switch, prior state is restored without leaving partial changes.
Target Concurrency Lock
A robust target lock prevents simultaneous restore operations on the same directory. Any concurrent attempt is aborted immediately to avoid race conditions and corruption.
Strict Traversal Rejection
Archives containing ../ path traversal, escaping symlinks, hard links, or disallowed file types are rejected completely before any target modification.
Zero Credential Leakage
Secrets are passed exclusively via standard environment variables or explicit --env-file. Command-line flags and output logs never expose credentials or secret tokens.
Pre-Flight Disk Space Check
Before mutation begins, available disk capacity is verified against uncompressed archive sizes plus staging artifacts. Inadequate space aborts the execution cleanly.
How coolrestore handles your archive
Unlike traditional tar extract commands that run directly into destination folders, coolrestore routes all operations through isolated staging, integrity verification, and atomic state switching.
Acquisition & Isolation
Downloads from S3-compatible endpoints (or local path) into an isolated staging area on the target filesystem.
Strict Integrity & Security Scan
Verifies gzip integrity, calculates file sizes, checks against path traversal attacks, and validates entry boundaries.
Target Lock & Space Reservation
Acquires an exclusive lock on the target directory and checks filesystem capacity before proceeding.
Plan Preview or Atomic Application
Outputs diff report by default. If confirmed, commits changes via Merge or atomic Replace with instant rollback safety.
Choose Your Restore Mode
Adds missing files and updates existing files from the archive. Any files already in the target that are not in the archive are completely preserved.
Target becomes an exact replica of the archive. Utilizes atomic filesystem renames on the same filesystem. In case of disruption, rolls back to prior state automatically.
Ecosystem & Storage Compatibility
Works seamlessly with your infrastructure stack
Get coolrestore on your server
Static, zero-dependency binaries ready for production servers and local workstations.
Install directly via one-liner or add the official Replworks tap (macOS & Linux):
Environment File Setup (.env)
coolrestore explicitly avoids auto-discovering dotenv files from cwd for security. Pass your config file securely with --env-file:
AWS_ACCESS_KEY_ID=your-key-id AWS_SECRET_ACCESS_KEY=your-secret-key AWS_REGION=us-east-1 AWS_ENDPOINT_URL=https://rustfs.your-domain.com AWS_S3_FORCE_PATH_STYLE=true
Commands & Options
All command-line arguments and flags supported by coolrestore.
Frequently Asked Questions
Does running coolrestore modify my server immediately?
No. By default, coolrestore runs in preview-only mode. It downloads to an isolated staging area, verifies archive health, calculates what would be added or overwritten, and outputs a plan. It will never write to your target directory without --confirm.
How does atomic replace rollback protect my storage?
In replace mode, staging and target must reside on the same filesystem. The swap is executed through atomic directory renames. If any failure occurs during the switch, the previous state is restored immediately, avoiding partially overwritten volumes.
Can I restore non-Coolify backup archives?
Yes. Any standard gzip-compressed tar archive (.tar.gz) residing in S3-compatible storage or on a local disk can be restored into any valid target directory.