OmniOffloader — Multi-Cloud Media Offload & CDN

FAQ

Which cloud storage providers are supported?

Amazon S3, Cloudflare R2, DigitalOcean Spaces, Backblaze B2 and Wasabi each have their own setup. Any other S3-compatible storage (MinIO, Storj, OVHcloud, Linode, Scaleway and more) works through Any S3-Compatible Storage, where you enter the address and region from your provider.

How do I set up Cloudflare R2?

1. In your Cloudflare dashboard, go to R2 and create a bucket.
2. In the bucket’s Settings, connect a Custom Domain (for example https://media.yourdomain.com) or turn on the public r2.dev address, so visitors can see your files.
3. On the R2 overview page, open Manage R2 API Tokens. Create a token with Object Read & Write permission, and copy the Access Key ID and Secret Access Key.
4. In the bucket settings, copy the S3 API address (https://<account-id>.r2.cloudflarestorage.com).
5. In OmniOffloader Settings, choose Cloudflare R2. Enter the keys, that address as the Endpoint URL, the bucket name and your custom domain, then click Test Connection.

Full guide with screenshots: Cloudflare R2

How do I set up Amazon S3?

1. In the AWS console, create an S3 bucket in the region you want.
2. In IAM, create a user with an access key, and allow it to read and write files in that bucket. Copy the Access Key ID and Secret Access Key.
3. So visitors can see your files, either allow public reading with a bucket policy, or put Amazon CloudFront in front of the bucket.
4. In OmniOffloader Settings, choose Amazon S3. Enter the keys, bucket name, region (for example us-east-1) and your CloudFront or CDN address. Leave the address empty to serve straight from S3.

Full guide: Amazon S3

How do I set up DigitalOcean Spaces?

1. In the DigitalOcean control panel, create a Space. Turn on its CDN if you want one.
2. Create a Spaces access key and copy the key and secret.
3. Note the region address (for example https://nyc3.digitaloceanspaces.com) and the region (nyc3).
4. In OmniOffloader Settings, choose DigitalOcean Spaces. Enter the keys, that address as the Endpoint URL, the region, the Space name and your CDN or custom domain.

Full guide: DigitalOcean Spaces

How do I set up Backblaze B2?

1. In the Backblaze B2 console, create a bucket and set Files in Bucket are to Public.
2. Note the bucket’s S3 Endpoint (for example https://s3.us-east-005.backblazeb2.com) and its region (us-east-005).
3. Under Application Keys, add a key with Read and Write access to the bucket. Copy the keyID and applicationKey.
4. In OmniOffloader Settings, choose Backblaze B2. Enter the key ID, key, Endpoint URL, region and bucket name. Leave the CDN address empty to serve straight from Backblaze, or enter your CDN domain.

Full guide: Backblaze B2

How do I set up Wasabi?

1. In the Wasabi console, create a bucket and note its region (for example us-east-1).
2. Create an access key and copy the Access Key ID and Secret Access Key.
3. So visitors can see your files, allow public reading with a bucket policy, or put a CDN in front of the bucket.
4. In OmniOffloader Settings, choose Wasabi. Enter the keys, bucket name, region and your CDN or custom domain.

Full guide: Wasabi

How do I set up Storj or another S3-compatible provider?

For Storj:

1. In the Storj console, create a bucket and open Access → Create S3 Credentials. Copy the Access Key and Secret Key.
2. Share the bucket publicly (Objects → your bucket → Share) and copy the link, for example https://link.storjshare.io/s/<KEY>/<BUCKET>. Change /s/ to /raw/.
3. In OmniOffloader Settings, choose Any S3-Compatible Storage.
4. Enter https://gateway.storjshare.io as the Endpoint URL and us-east-1 as the region, and turn on Use Path-Style Endpoint. Add your keys and bucket name, and paste the https://link.storjshare.io/raw/... link as your Custom Domain / CDN URL.

The same fields work for MinIO, OVHcloud, Linode, Scaleway and others. Use Provider Label to give the provider your own name. Full guide: S3-compatible storage

Why do I need a custom domain or CDN address?

Most storage buckets don’t show files to the public by default, and Cloudflare R2 has no public address at all until you add one. Connecting your own domain or a CDN to the bucket lets visitors see your media, and lets the CDN cache it close to them.

Will offloading break my image links?

No. OmniOffloader changes image addresses as each page loads, so posts, pages, featured images and responsive images all keep working. Your post content is never edited, and you don’t need to search and replace anything in your database.

Do I have to delete the files on my server?

No. The default, Retain Local Files, deletes nothing. The cloud simply becomes a second copy. Choose Smart Local Cleanup to remove only the extra sizes WordPress creates and keep every original, or Full Cloud Migration to free the most space. A file is only removed from your server after its cloud copy is confirmed.

Which Transfer Speed should I choose?

It mostly matters when you move a lot of media at once: offloading your existing library, or Bring Back. It sets how many files move at the same time:

• Low: 1 file at a time. Best for small shared hosting plans.
• Balanced: 3 files at a time. The default, and right for most sites.
• Fast: 6 files at a time. For a VPS or dedicated server.
• Custom: your own number, from 1 to 10.

A faster setting doesn’t start extra processes on your server; it just makes better use of the waiting time while files travel.

How long does offloading take? Can I close the browser tab?

It depends on your server’s connection to your storage, the size of your files, and how many image sizes your theme creates. A faster Transfer Speed finishes sooner if your server can handle it.

Yes, you can close the tab: the job keeps running in the background. Only on hosts that block WordPress’s background requests does the job need the Offload page to stay open. There, leave it open until it finishes, or use WP-CLI.

Can I move my media back to my server later?

Yes, that’s what Bring Back is for. It downloads your media to its original place on your server, checks that every file arrived, and then loads everything from your server again. Bring back one item, a set number, or your whole library. Your cloud copy is kept unless you choose to delete it.

What happens to my images if I deactivate the plugin?

It depends on what you chose to keep on your server. With Retain Local Files, everything is still on your server, so nothing changes. With Smart Local Cleanup or Full Cloud Migration, some or all files are only in the cloud, and they would stop showing. Run Bring Back before you deactivate in that case.

Some media failed to offload. What do I do?

Go to OmniOffloader → Tools → Failed Items. You’ll see each item with the reason it failed. Fix the cause (for example a lost connection, or a file that is missing on your server), then click Retry Failed Offloads. In Media → Library (list view), the Offload failed filter shows the same items.

How do I check that all my files are really in the cloud?

Run wp omnioffloader verify from WP-CLI. It checks every offloaded file in your cloud storage and on your server, and lists anything missing. Add --repair to fix what it can: it uploads or downloads the missing files and never deletes anything.

I changed the retention policy. Why are old files still on my server?

A new policy only applies to new uploads at first. To apply it to media you already offloaded, go to OmniOffloader → Tools → Apply Retention Policy to Existing Media. Before any file is deleted from your server, its cloud copy is checked, and missing files are uploaded first. Switching to a policy that keeps more files downloads them to your server again.

Can I offload now and switch to the CDN later?

Yes. With Retain Local Files, turn off Serve Media from Cloud in Settings. Your media is still copied to the cloud, but your site keeps loading it from your server. When your CDN is ready, turn it on and everything switches at once, with nothing uploaded again. Clear your page cache after the switch. (With the other two policies, files are removed from your server, so media always loads from the cloud.)

I copied my site to staging or my computer. Can the copy damage my live site’s media?

No. A copy has your live site’s settings and keys, so without protection it could upload into your live bucket or delete files your live site still uses. OmniOffloader notices a copy and turns on Safe mode. It notices when:

• the site address changed,
• WordPress is set to a staging, development or local environment, or
• the site runs on a local address such as localhost, .local or .test.

In Safe mode, nothing is uploaded to or deleted from your cloud storage. Media already in the cloud keeps showing, and new uploads stay on the copy. A banner explains why Safe mode is on.

• Moved your live site to a new domain? Click This is the live site.
• Want to bring media down to a copy? Turn on Allow Bring Back on a copy (download only) in Settings. The cloud copy is always kept.
• Want to decide yourself? Add define( 'OMNIOFFLOADER_SAFE_MODE', true ); (or false) to wp-config.php, or turn off Protect the live site when this is a copy in Settings.

Can several sites share one bucket and CDN?

Yes, for example example.com, shop.example.com and blog.example.com. Install OmniOffloader on each site with the same bucket, keys and CDN address, and give each site its own folder in Settings → Custom Path Prefix (such as www, shop and blog).

Each site marks its folder, so two sites can’t overwrite or delete each other’s files. Settings won’t let you pick a folder another site already uses. If the folder really belongs to this site (for example after a domain change), click This folder belongs to this site.

On Amazon S3, you can also give each site its own access key that only works in its own folder.

I changed the folder (Path Prefix). What happens to media I already offloaded?

It stays in the old folder and keeps working. To move it into the new folder, use Tools → Move Media to the Current Folder, or run wp omnioffloader move --all. Within the same bucket, your storage provider copies the files itself, so nothing is downloaded to your server.

Can I keep my access keys out of the database?

Yes. Add them to wp-config.php as constants named OMNIOFFLOADER_{PROVIDER}_{FIELD}, for example:

define( 'OMNIOFFLOADER_CLOUDFLARE_R2_KEY', '...' );
define( 'OMNIOFFLOADER_CLOUDFLARE_R2_SECRET', '...' );

These always win over saved settings, and the settings screen shows those fields as locked. Either way, your secret key is never sent back to the browser.

Who can offload or bring back media?

Only administrators. Other users upload and delete their own media as usual. With Mirror Delete on, deleting media also deletes its cloud copy.

What about very large videos or files?

Files over 64 MB are uploaded in parts, so a dropped connection only costs one part, and files over 5 GB work too. If your host still cuts a transfer short, that item is reported with the reason and the job moves on.

Does it work with caching plugins?

Yes. Progress stays live with LiteSpeed Cache, Breeze, Redis and Memcached. On your public pages, OmniOffloader only changes image addresses, and doesn’t slow them down with extra database work.

Does it work on multisite?

Yes, site by site. Each site in the network has its own settings, keys and jobs. Only a network administrator can point a site at a private or local storage address. Multisite hasn’t had a dedicated test pass yet, so please try it on a staging network first.

Can I use it from WP-CLI?

Yes. OmniOffloader → Tools lists every command with examples and copy buttons. The main ones:

wp omnioffloader offload --all offloads every local item.
wp omnioffloader restore --all brings everything back.
wp omnioffloader retention applies a changed retention policy to existing media.
wp omnioffloader move --all moves media into the current folder.
wp omnioffloader verify --repair checks every file and fixes what it can.
wp omnioffloader errors --retry retries failed offloads.
wp omnioffloader status shows what is running and your media counts.
wp omnioffloader stop stops the running job.

Every command that changes something supports --dry-run, so you can see what it would do first. Only one job runs at a time, so two jobs never touch the same files.

Does it work for a very large media library?

Yes. The first offload takes a while on a big library, since every existing file is copied to the cloud once. After that, new uploads are offloaded automatically, so there’s nothing more to do. Jobs run in small steps, so memory use stays low however big your library is, and a stopped job continues where it left off. For the fastest results on a big library, use WP-CLI (see the next question).

How can I offload a very large library faster?

Use WP-CLI on your server and move more files at once, for example wp omnioffloader offload --all --concurrency=32 (up to 64). Try a short run first with --limit=500. To keep a long job running after you close the terminal, start it like this:

nohup wp omnioffloader offload --all > ~/offload.log 2>&1 &

Check on it any time with wp omnioffloader status, and stop it with wp omnioffloader stop. Run the same command again to continue where it stopped. Step by step: Long runs and log files.