Skip to main content

​
Quick Start Guide

Get started with ZipDrop in just a few minutes. This guide will walk you through your first upload, both in demo mode and with full R2 cloud storage.

​
Step 1: Install ZipDrop

If you haven’t installed ZipDrop yet, follow the installation guide.
ZipDrop installed and running with menu bar icon visible

​
Step 2: Try Demo Mode

ZipDrop starts in demo mode by default, which saves files locally without requiring any cloud configuration. This is perfect for trying out the app!
1

Click the menu bar icon

Look for the ZipDrop icon in your macOS menu bar (top-right) and click it.You should see:
  • A drop zone window
  • “Demo” badge in the top-right corner
  • Text saying “Drop files here”
2

Drag and drop a file

Drag an image file from your Desktop or Finder and drop it into the ZipDrop window.
Try dragging a .jpg or .png file first to see the WebP conversion in action!
You’ll see:
  • “Processing…” with a spinner
  • Then “Saved to Downloads!” on success
3

Check the output

In demo mode, files are saved to ~/Downloads/ZipDrop/
open ~/Downloads/ZipDrop
If you dropped a JPG or PNG, you’ll see it was converted to .webp format for a smaller file size!
4

Try multiple files

Drag multiple files at once into ZipDrop. They’ll be automatically zipped together!The resulting file will be named something like archive_a1b2c3d4.zip in your Downloads folder.

​
What Files Can You Upload?

ZipDrop supports many file types:
JPG, PNG, GIF, BMP, TIFF, WebP, HEIC, HEIF, SVG, ICO, RAW, CR2, NEF, ARW
Images (except WebP) are automatically converted to WebP format for 30-80% smaller file sizes

​
Step 3: Set Up R2 (Optional)

To upload files to the cloud instead of saving them locally, you’ll need to configure Cloudflare R2.
You need a Cloudflare account with R2 enabled. R2 offers 10 GB free storage per month.

​
Create R2 Bucket

1

Log in to Cloudflare

Go to the Cloudflare Dashboard and log in
2

Navigate to R2

Click R2 in the left sidebar
3

Create a bucket

Click Create bucket and give it a name (e.g., zipdrop-uploads)
Choose a region close to your users for faster uploads and downloads
4

Enable public access (optional)

If you want files to be publicly accessible:
  1. Click on your bucket
  2. Go to Settings → Public access
  3. Click Allow access and set up a custom domain or use the R2.dev subdomain
Without public access, you’ll need to generate signed URLs for sharing files

​
Create API Credentials

1

Go to R2 API Tokens

In the Cloudflare dashboard:
  1. Click R2 in the sidebar
  2. Click Manage R2 API Tokens
2

Create API token

Click Create API token
3

Configure permissions

  • Token name: “ZipDrop”
  • Permissions: Select Object Read & Write
  • TTL: Leave as default (indefinite) or set your preferred expiration
  • Click Create API Token
4

Save credentials

You’ll see:
  • Access Key ID - Something like a1b2c3d4e5f6g7h8i9j0
  • Secret Access Key - Something like 1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0
Save these credentials now! The Secret Access Key is only shown once.

​
Configure ZipDrop

1

Open Settings

Click the ZipDrop menu bar icon, then click the gear icon (⚙️) in the top-right
2

Disable Demo Mode

Toggle off Demo Mode to enable cloud uploads
With demo mode off, the R2 configuration fields become editable
3

Enter R2 credentials

Fill in the fields:
  • Account ID: Find this in your Cloudflare dashboard (e.g., abc123def456)
  • Bucket Name: Your R2 bucket name (e.g., zipdrop-uploads)
  • Access Key ID: From Step 4 above
  • Secret Access Key: From Step 4 above
  • Public URL Base: Your bucket’s public URL (e.g., https://files.yourdomain.com or https://pub-xyz123.r2.dev)
Find your Account ID: Cloudflare Dashboard → R2 → Your bucket → Overview
4

Test credentials

Click Test Credentials to verify your configuration
You should see “Credentials verified for: your-bucket-name”
If you see an error:
  • Double-check all fields for typos
  • Ensure the bucket exists
  • Verify API token has “Object Read & Write” permissions
5

Save configuration

Click Save to store your credentials
Credentials are securely stored in macOS Keychain. Non-secret config is stored in ~/.config/zipdrop/config.json

​
Step 4: Your First Cloud Upload

Now that R2 is configured, let’s upload a file to the cloud:
1

Ensure demo mode is off

The “Demo” badge should no longer appear in the top-right
2

Drop a file

Drag and drop an image file into ZipDrop
3

Wait for processing

You’ll see:
  • “Processing…” (image conversion if applicable)
  • Upload progress
  • “Copied to clipboard!” on success
4

Paste and share

Press Cmd+V anywhere to paste the URL. It’s already in your clipboard!Example URL: https://files.yourdomain.com/u/a1b2c3d4_photo.webp
Your file is now uploaded to R2 and accessible via the URL!

​
Usage Tips

  • Esc - Close the ZipDrop window
  • Cmd+V - Paste the last uploaded URL
  • Single image (JPG, PNG, etc.) → Converted to WebP
  • Single WebP → Uploaded as-is (no conversion)
  • Multiple files → Zipped together automatically
  • Single non-image → Uploaded as-is
The bottom half of the window shows your recent uploads:
  • Click any item to copy its URL/path
  • Click the link icon to copy
  • Click the folder icon (demo) or external icon (R2) to open
  • Click the trash icon to remove from list
  • Shift+Click trash icon on R2 uploads to delete from cloud too!
You can toggle demo mode on/off in Settings at any time:
  • Demo mode ON - Files save to ~/Downloads/ZipDrop
  • Demo mode OFF - Files upload to R2
Your R2 credentials remain saved even when demo mode is on.

​
File Size Limits

Single File

500 MB maximum per file

Total Upload

1 GB maximum total

File Count

50 files maximum per upload

​
Configuration Files

ZipDrop stores configuration in two places:

​
Credentials (Keychain)

Service: com.metalayer.zipdrop
Account: r2_credentials
Stored: Access Key ID + Secret Access Key (JSON)
View/edit in Keychain Access app → Search “zipdrop”

​
Settings & Config (Files)

~/.config/zipdrop/
├── config.json      # Bucket name, account ID, public URL base
└── settings.json    # Demo mode, output directory
Credentials are stored in Keychain (encrypted), while non-sensitive settings are in plain JSON files.

​
Troubleshooting

​
”Invalid R2 credentials” error

  • Verify Access Key ID and Secret Access Key are correct
  • Ensure Account ID matches your Cloudflare account
  • Check that bucket name is spelled correctly
  • Verify API token has “Object Read & Write” permissions

​
Upload fails with timeout

  • Check your internet connection
  • Try a smaller file first
  • Verify Cloudflare R2 status page for outages

​
Files not appearing in R2

  • Check the correct bucket in Cloudflare dashboard
  • Look in the u/ folder (ZipDrop uploads to u/ prefix)
  • Try the “Test Credentials” button in Settings

​
WebP images look wrong

  • ZipDrop uses 80% quality for WebP conversion (configurable in future versions)
  • Some images may lose subtle details
  • If quality is critical, use demo mode or upload already-optimized WebP files

​
Next Steps

Features

Explore all ZipDrop features

Configuration

Advanced configuration options

Developer Guide

Developer documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us