Skip to main content
This guide walks you through setting up Cloudstic and creating your first encrypted backup, from installation to verification.
In a hurry to back up your whole machine? cloudstic setup workstation is a guided flow that discovers your folders and portable drives and scaffolds profiles for you, as an alternative to the manual steps below.

​
Prerequisites

Before you begin, ensure you have:
  • Cloudstic CLI installed (installation instructions)
  • A directory you want to back up
  • A storage location (local directory, S3 bucket, B2 bucket, or SFTP server)

​
Step 1: Initialize Your Repository

First, create an encrypted repository. Encryption is required by default in Cloudstic.
1

Choose your storage location

Decide where to store your backups. For this example, we’ll use a local directory, but you can also use S3, B2, or SFTP.
2

Initialize the repository

Create the repository with password-based encryption. We strongly recommend also creating a recovery key.
Write down your recovery key immediately! It will only be displayed once. If you lose your password, this 24-word phrase is your only way to recover your backups.
You’ll see output like this:
3

Store your credentials safely

Save your encryption password in a secure location:
  • Use a password manager (1Password, Bitwarden, etc.)
  • Write down your recovery key phrase on paper and store it in a safe place
  • Never commit passwords to version control
For convenience, save your password as an environment variable:
This way, you won’t need to provide -password with every command.

​
Step 2: Create Your First Backup

Now that your repository is initialized, let’s back up a directory.
1

Back up a local directory

Start with a simple backup of a local folder:
You’ll see progress output:
2

Exclude unwanted files (optional)

If you want to skip certain files or directories, use exclude patterns:
Or create a .backupignore file:
Then reference it:
3

Add tags (optional)

Tags help organize your backups:
4

Dry run first (optional)

Preview what will be backed up without actually writing data:

​
Step 3: Verify Your Backup

After creating a backup, verify it was successful.
1

List snapshots

View all backups in your repository:
Output:
2

List files in the snapshot

Browse the contents of your backup:
Or for a specific snapshot:
3

Verify integrity (optional)

Run a full integrity check to ensure all data is readable:
Output:
Run cloudstic check -read-data for a deeper verification that re-hashes all chunk data. This takes longer but detects silent corruption.

​
Step 4: Create Incremental Backups

Subsequent backups are incremental. Only new or changed files are uploaded.
Output:
Cloudstic uses content-addressable storage with deduplication. Identical files across snapshots are stored only once, saving significant space.

​
Common Patterns

​
Backing Up Multiple Sources

You can back up different sources into the same repository:

​
Using Configuration Files

For complex setups, use environment variables:
~/.bashrc
Then commands become simpler:

​
Troubleshooting

​
”Repository not initialized” Error

Make sure you’ve run cloudstic init first and are pointing to the correct storage location.

​
Authentication Errors

For cloud storage (S3, B2), verify your credentials are set:

​
Slow First Backup

The first backup is always slower because all files must be uploaded. Subsequent backups are much faster due to incremental processing and deduplication.

​
Next Steps

Retention Policies

Learn how to automatically manage snapshot lifecycle

Restoring Files

Recover files from your backups

Encryption Keys

Manage passwords and recovery keys

Automation

Schedule automatic backups with cron