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 a dedicated setup. Anything else that speaks the S3 API — MinIO, Storj, OVHcloud, Linode Object Storage, Scaleway and so on — works through Any S3-Compatible Storage, where you supply the endpoint and region yourself.

How do I configure Cloudflare R2?

1. In the 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 enable the public r2.dev URL, so your files can be served publicly.
3. Back 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. Copy the bucket’s S3 API endpoint (https://<account-id>.r2.cloudflarestorage.com) from the bucket settings.
5. In OmniOffloader Settings, select Cloudflare R2 and enter the Access Key ID, Secret Access Key, Endpoint URL, Bucket Name and your custom domain, then click Test Connection.

Full guide: omnioffloader.vercel.app/providers/cloudflare-r2/

How do I configure Amazon S3?

1. In the AWS console, create an S3 bucket in your preferred region.
2. In IAM, create a user with programmatic access and a policy that allows reading and writing objects in that bucket. Create an access key and copy the Access Key ID and Secret Access Key.
3. To serve media publicly, allow public s3:GetObject on the bucket with a bucket policy, or put an Amazon CloudFront distribution in front of it.
4. In OmniOffloader Settings, select Amazon S3 and enter the keys, Bucket Name, Region (for example us-east-1) and your CloudFront or CDN URL (or leave it blank to serve directly from S3).

Full guide: omnioffloader.vercel.app/providers/amazon-s3/

How do I configure DigitalOcean Spaces?

1. In the DigitalOcean control panel, create a Space and, if you want, enable its built-in CDN.
2. Create a Spaces access key and copy the key and secret.
3. Note the region endpoint (for example https://nyc3.digitaloceanspaces.com) and region (nyc3).
4. In OmniOffloader Settings, select DigitalOcean Spaces and enter the keys, Endpoint URL, Region, Space name and your CDN or custom domain.

Full guide: omnioffloader.vercel.app/providers/digitalocean-spaces/

How do I configure Backblaze B2?

1. In the Backblaze B2 console, create a bucket and set Files in Bucket are to Public so media can be viewed in browsers.
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, and copy the keyID and applicationKey.
4. In OmniOffloader Settings, select Backblaze B2 and enter the Application Key ID, Application Key, Endpoint URL, Region and Bucket Name. Leave the CDN URL blank to serve directly from Backblaze, or enter your CDN domain.

Full guide: omnioffloader.vercel.app/providers/backblaze-b2/

How do I configure 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. Make the files publicly readable with a bucket policy, or serve them through a CDN in front of the bucket.
4. In OmniOffloader Settings, select Wasabi and enter the keys, Bucket Name, Region and your CDN or custom domain.

Full guide: omnioffloader.vercel.app/providers/wasabi/

How do I configure Storj or other S3-compatible storage?

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-sharing URL, for example https://link.storjshare.io/s/<KEY>/<BUCKET>. Replace /s/ with /raw/.
3. In OmniOffloader Settings, select Any S3-Compatible Storage.
4. Set the S3 Endpoint URL to https://gateway.storjshare.io, Region to us-east-1, turn on Use Path-Style Endpoint, enter your keys and Bucket Name, and paste the https://link.storjshare.io/raw/... URL as the Custom Domain / CDN URL.

The same fields work for MinIO, OVHcloud, Linode, Scaleway and other S3-compatible services. The optional Provider Label lets you name the provider as it appears in the plugin. Full guide: omnioffloader.vercel.app/providers/s3-compatible/

Which Transfer Speed should I choose?

It matters most when you offload media that is already in your library but not in the cloud yet — with Bulk Offload, Media Library bulk actions or WP-CLI — and when you use Bring Back. New uploads are offloaded in the background as they arrive, so you rarely notice their speed. The setting chooses how many files are uploaded or downloaded at the same time:

• Low — one file at a time. The lightest option 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 — any number from 1 to 10.

All four run in the same single PHP process; a faster setting overlaps the time spent waiting on the network instead of starting more processes. Each extra file only adds a little memory and bandwidth. Bulk Offload, Bring Back, new uploads and WP-CLI all follow this setting. For a one-off WP-CLI run on a VPS, --concurrency=32 (up to 64) on offload, restore, retention or move goes beyond it for that run only.

How long does a bulk offload take, and can I close the browser tab?

It depends mostly on how quickly your server reaches your storage provider, how large your files are, and how many thumbnail sizes your theme creates. A higher Transfer Speed finishes sooner on a server that can handle it.

Jobs run in the background and keep going after you close the tab. On hosts that block WordPress’s internal loopback requests, the admin screen drives the job instead — there, leave the Offload page open until it finishes, or use WP-CLI.

Will offloading break my existing image URLs?

No. URLs are rewritten as pages render, so posts, pages, featured images and responsive srcset attributes all keep working. Nothing in your post content is edited, and no database search-replace is needed.

Can I move my media back to my server later?

Yes — that is what Bring Back is for. It downloads your media from the cloud to its original paths, checks that every file arrived, and then stops rewriting URLs so everything serves locally again. You can restore a single attachment, a set number, or the whole library. The cloud copy is kept unless you turn on deleting it after restore.

What happens to my images if I deactivate the plugin?

That depends on the retention policy you used. With Retain Local Files, every file is still on your server and nothing changes. With Smart Local Cleanup or Full Cloud Migration, some or all local files were deleted after upload, so URLs would point at files that are no longer on disk. Run Bring Back before deactivating if you used either cleanup policy.

I copied my live site to staging or a local dev site. Can it damage the live site’s media?

No. A copy carries the live site’s settings and access keys, so without protection it would upload into the live bucket (a new file with the same name could overwrite one the live site added later) and, with Mirror Delete on, delete files the live site still uses. OmniOffloader recognises a copy automatically and switches to Safe mode:

• the site address changed from the one recorded as live (stored as a fingerprint, so migration tools’ search-and-replace can’t hide the change),
• WordPress reports a staging, development or local environment (WP_ENVIRONMENT_TYPE, set by many managed hosts and local tools), 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 loading from it, and new uploads stay on the copy’s own server. Bring Back is turned off too; to download media from the cloud to the copy, turn on Allow Bring Back on a copy (download only) in Settings — the cloud copy is then always kept. A banner explains why Safe mode is on. If your live site really moved to a new domain, click This is the live site. 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 separate sites share one bucket and one CDN address?

Yes, for example example.com, shop.example.com and blog.example.com. Install OmniOffloader on each site, enter the same bucket, keys and custom domain, and give each site its own folder under Settings → Custom Path Prefix (for example www, shop and blog). Each site’s files then live under their own folder, such as https://cdn.example.com/shop/2026/09/photo.jpg.

Separate sites share no database, so without a folder of their own two sites would store files under the same names. One site’s upload would then overwrite the other’s file, and Mirror Delete on one site would delete files the other still uses. To prevent this, each site marks its folder with a small .omnioffloader-site.json file naming the site. Settings refuses a folder another site already uses. If a site finds another site’s marker in its folder, it switches to Safe mode and a banner explains why. Nothing is uploaded or deleted until you choose a different Path Prefix. If the folder really belongs to this site (for example after a domain change), click This folder belongs to this site.

For a hard guarantee on Amazon S3, give each site its own access key, limited to its own folder.

Do I have to delete my local files?

No. The default policy, Retain Local Files, deletes nothing — the cloud simply becomes a second copy. Choose Smart Local Cleanup to delete only generated thumbnails while keeping every original, or Full Cloud Migration to reclaim the most space. Local files are only removed after the upload has been confirmed in your bucket.

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

A retention policy is applied when a file is offloaded, so a new policy only affects new uploads at first. Go to OmniOffloader → Tools → Apply Retention Policy to Existing Media (or run wp omnioffloader retention) to update media you offloaded earlier. Before a local file is deleted, its cloud copy is checked by size. Files missing from the cloud are uploaded first. A file whose cloud copy differs is uploaded again and checked; if that fails, the local file is kept and reported. Moving to a looser policy (for example from Full Cloud Migration back to Retain Local Files) downloads the local copies again. For a large library on a VPS, wp omnioffloader retention --concurrency=32 --yes checks 32 attachments at once.

Why do I need a custom domain or CDN URL?

Most storage buckets do not serve files publicly by default, and Cloudflare R2 has no public URL at all until you connect one. Pointing a custom domain or CDN hostname at your bucket is what makes your media reachable — and it lets the files be cached at the edge.

Can I offload now and switch to the CDN later?

Yes. With the Retain Local Files policy, turn off Serve Media from Cloud in Settings → Retention Policy. Media is still offloaded to your bucket, but your site keeps loading it from your own server. When your CDN is ready, turn it on: every offloaded file switches over at once, with nothing uploaded again. Clear your page cache after changing it. The cleanup policies delete local files, so with them media always loads from the cloud.

Can I keep my access keys out of the database?

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

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

Constants take priority over saved values, and the settings screen shows those fields as locked. Secrets are never sent back to the browser either way, and stored credentials are kept out of WordPress’s autoloaded options.

Can I run it from WP-CLI?

Yes. OmniOffloader → Tools lists every command and option with copy buttons.

wp omnioffloader offload --all [--limit=<number>] [--dry-run]
wp omnioffloader offload --ids=12,34
wp omnioffloader offload --all --concurrency=32
wp omnioffloader restore --all [--limit=<number>] [--delete-cloud] [--dry-run] [--concurrency=<number>]
wp omnioffloader retention [--policy=<0|1|2>] [--dry-run] [--format=json] [--concurrency=<number>]
wp omnioffloader move --all [--keep-old] [--dry-run]
nohup wp omnioffloader offload --all > ~/offload.log 2>&1 &
wp omnioffloader status
wp omnioffloader stop

Start a long job with nohup … & (as above) to keep it running after you close the terminal; status shows its progress and stop ends it from any terminal. Every write command supports --dry-run, and destructive options ask for confirmation unless you pass --yes. Commands refuse to start while another bulk job is running (--force overrides this), so two jobs never touch the same files. WP-CLI commands use your Transfer Speed setting unless you pass --concurrency.

How can I offload a very large library faster?

Run the offload from WP-CLI on your server with more files at once: wp omnioffloader offload --all --concurrency=32, up to 64. The admin screens stay at 10 at most, because they run inside web requests. Try a short run first (--limit=500) and time it, then start the full run with nohup … & so it keeps going after you close the terminal.

How do I follow a long WP-CLI run?

Start it in the background with a log file in your home folder: nohup wp omnioffloader offload --all > ~/offload.log 2>&1 &. The answer [1] 12345 is the job and process number, not an error. Follow the progress with tail -f ~/offload.log (Ctrl+C only stops watching, not the job) or wp omnioffloader status; the log gets a timestamped line every 25 attachments, so you can work out the speed and the time left. Stop it with wp omnioffloader stop and run the same command again to continue. Step-by-step guide: Long runs and log files.

Who can offload or bring back media?

Only administrators (users with the manage_options capability). Other users keep their normal WordPress rights: they upload and delete their own media, and with Mirror Delete on, deleting an attachment also removes its cloud copy.

What about very large videos or files?

Files above 64 MB are uploaded in parts, so a dropped connection costs one chunk rather than the whole transfer, and files larger than 5 GB are supported. If a transfer is still cut short by your host’s time limit, that attachment is reported with an explanation and the job moves on.

Does it work with caching plugins and object caches?

Yes. The plugin’s own REST requests tell page caches not to store them (including LiteSpeed Cache and Breeze), and bulk progress stays live under Redis or Memcached object caching. On the front end the plugin only rewrites URLs and does not add database queries per image.

Does this plugin work on multisite?

Yes, per site. Each site in a network has its own settings, credentials and background queues. Only a network administrator can point a provider at a private or local endpoint address. Multisite has not had a dedicated test pass yet, so test on a staging network first.

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

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