Start Free
OffloadX Plugin Documentation: Complete 2026 Setup Guide

OffloadX Documentation

This WordPress plugin documentation covers everything you need to install, configure, and use every feature of OffloadX — the cloud media offloader for WordPress. New to the plugin? See the full list of OffloadX features, or read the official Cloudflare R2 documentation for bucket setup.

Installation

Install OffloadX like any standard WordPress plugin. No server configuration required.

1

Download the zip

Get offloadx.zip from your purchase confirmation email or your account on offloadx.com.

2

Upload via WP Admin

Go to Plugins → Add New → Upload Plugin. Select the zip, click Install Now, then Activate Plugin.

3

OffloadX appears in the sidebar

After activation, an OffloadX menu item appears in your WP Admin sidebar. A 🔑 License item also appears as a separate menu for entering your license key.

Requirements: WordPress 5.9+, PHP 7.4+, and a supported storage provider account. WP-Cron must be enabled for scheduled and background offload.

First Setup

Get from a fresh install to your first offloaded file in five steps.

1

Enter your storage credentials

Go to OffloadX → Credentials. Select your provider tab, enter the required fields, and click Test Connection to verify everything works.

2

Activate your license

Go to OffloadX → License. Enter your license key and click Activate. Free plan works without a key — skip this step if you're on Free.

3

Configure Behaviour settings

Go to OffloadX → Behaviour. Enable Auto-Offload New Uploads so future uploads go directly to the cloud. Enable WebP Conversion if you want images compressed automatically.

4

Run Bulk Migration

Go to OffloadX → Bulk Migration. Click Start Migration to offload your existing media library. For large libraries, enable Background Mode first.

5

Replace database URLs

Go to OffloadX → URL Replace. Click Replace All URLs so all WordPress content references point to your CDN instead of local file paths.

Dashboard

Your central overview. Live stats, quick action buttons, a CDN coverage chart, and connection status — all updating in real time.

🗂OffloadX›Dashboard

Stat Cards

Four stat cards update live via AJAX polling every 15 seconds during a migration:

Total Media
—
All processable attachments
On CDN
—
Successfully offloaded files
Pending
—
Not yet offloaded
Local Copies
—
Still on your server

Quick Actions

Bulk Migrate
Offload all pending media to the cloud
Replace URLs
Update all database references
Safety Check
Verify CDN before deleting local files
Schedule
Configure daily automatic offload

Connection Status

CDN Coverage Chart
Donut chart showing On CDN, Local copies, and Freed (deleted from server). Shows total DB URLs replaced and coverage percentage.
Scheduled Offload
Shows whether scheduled offload is active, configured time, and next run. Click Configure → to open settings.
Provider Status
Green = credentials valid and last test passed. Red = credentials missing or last test failed.
Background Banner
When background mode is running, a live banner shows progress and updates every 30 seconds from the cron worker.

Credentials

Connect OffloadX to your cloud storage provider. All credentials are encrypted with AES-256-CBC — never stored in plain text.

⚙️OffloadX›Credentials

Provider Tabs

Cloudflare R2
Amazon S3
Wasabi Cloud
DigitalOcean Spaces
Bunny Storage

Delivery Options

Default endpoint
Uses the provider's built-in storage URL. For R2 this requires Public Access to be enabled. For S3/Wasabi/DO it uses the direct storage URL based on your bucket and region.
Custom domain / CDN
Enter a custom domain or CDN URL — e.g. https://cdn.yourdomain.com or your r2.dev URL. Required for Bunny Storage — the Pull Zone URL goes here.
Re-save after salt changes: Credentials are encrypted using your WordPress salts. If you changed salts (e.g. during a migration), re-enter and save your credentials to re-encrypt them correctly.

After saving, always click Test Connection — OffloadX uploads a tiny test file, reads it back, then deletes it. If this passes, all uploads will work.

Behaviour

Control how OffloadX handles uploads, what gets offloaded, file organisation, and notifications. Changes take effect immediately on save.

⚙️OffloadX›Behaviour

Upload Behaviour

Auto-Offload New Uploads Free
Toggle. When on, every new file added to the Media Library is automatically uploaded to your CDN immediately after WordPress finishes generating thumbnails. Recommended to keep on.
Dynamic URL Rewriting Free
Toggle. Rewrites media URLs on-the-fly via a WordPress filter. Slight performance overhead — run DB Replace instead for a permanent solution.
After Upload — Local File Free
Dropdown. Keep local copy (safe default) or Delete immediately after upload.

Database & URL Settings

Auto DB URL Replacement Starter+
Toggle. After a Bulk Migration completes, automatically runs a database URL replacement — updating all post content, widgets, and options to point to the CDN.
Verify File Exists Before Skipping Pro+
Toggle. Makes a live HEAD request to the CDN before marking a file as already-offloaded. Catches cases where files were uploaded but later deleted from storage.

Image Optimisation

WebP Conversion Starter+
Toggle. Converts JPEG, PNG, static GIF, BMP to WebP before uploading. Requires PHP GD with WebP support. Reduces file sizes by 25–35% on average.
WebP Quality Starter+
Number (1–100). Default is 82 — a good balance of quality and file size. Only applies when WebP Conversion is enabled.
Auto-Delete Local After Pro+
Number (days). Automatically deletes local file copies N days after successful CDN verification. Set to 0 to disable.

File Organisation Business+

Use Site Folder in Storage Business+
Toggle. Prefixes all files with the site name as a folder — e.g. my-site/2024/01/image.jpg. Useful for multiple sites in one bucket.
Storage Site Folder Name Business+
Text field. Auto-populated from your site slug. Leave empty to use the auto-detected site name.
R2 Folder Structure Agency
Dropdown. Agency default (flat), Year/Month (date-based), or Current year.
Selective MIME Types Business+
Text field. Comma-separated MIME types to offload — e.g. image/jpeg,image/webp,image/png. Leave empty to offload all supported types.

Document Offloading

Offload Documents & PDFs Pro+
Toggle. By default only image/video/audio files are offloaded. Enable to also offload application/* types — PDFs, DOCX, ZIP, and all other document formats.

Integrations

WooCommerce Support Business+
Toggle. Offloads WooCommerce product images and downloadable files alongside regular media.
Require Safety Check Before Deletion Free
Toggle. Prevents the Delete Local Files button from being clicked until a Safety Check has passed. Recommended to keep on.

Email Notifications

Email Notifications Pro+
Toggle. Sends an HTML summary email after each Scheduled Offload run and when Background Mode completes.
Notification Email Pro+
Email field. Address to send reports to. Leave empty to use the WordPress admin email.

Bulk Migration

Offload your entire existing media library to cloud storage. Resumable, registry-aware, and adaptive — handles libraries of any size.

🗂OffloadX›Bulk Migration

Already Offloaded

Verify N Files on CDN
Makes HEAD requests to each CDN URL to confirm files are publicly accessible. Required before deleting local copies.
Delete N Local Copies
Permanently removes local file copies. Only appears after Verify passes. Irreversible.

Migration Controls

▶ Start Migration
Begins processing all pending files. Terminal log shows each file — green for success, red for failure. Progress bar and counters update live.
⏸ Pause
Pauses after the current batch finishes. Progress is saved — click Resume to continue from where it stopped.
▶ Resume
Resumes a paused migration from the exact file it stopped at. No files are re-processed.
■ Stop
Stops completely and resets the cursor. Already-offloaded files are skipped on the next run.

Speed Selector

Fast

Agency: 6 lanes × 50 files/batch. Pro/Business: 2 lanes × 10 files. Use when server load is low.

Normal

Balanced speed. Recommended for most sites. Adaptive delay between batches.

Gentle

Reduced parallelism. Good for live sites during peak traffic hours.

Slow

Minimum load — sequential with long delays. For resource-constrained hosting.

Background Mode

Starter / Pro / Business
Runs every 60 seconds via WP-Cron. Processes 30 files per run sequentially.
AgencyAgency
Runs every 30 seconds. Processes 50 files using curl_multi concurrent uploads for maximum throughput.
Free plan limit: Free plan processes up to 50 files total. The counter stops at 50 and shows a limit message. Upgrade to Starter or higher for unlimited file processing.

URL Replace

Rewrite all references to local media URLs across your entire WordPress database — posts, pages, Elementor data, widgets, options, and theme mods.

🗂OffloadX›URL Replace

Database URL Replacement

Dry Run Preview
Scans the database and counts how many URLs would be replaced without making any changes. Run this first.
Replace All URLs
Performs the actual replacement across all tables — posts, postmeta, options, Elementor CSS/JSON data, widget settings, and theme mods. A backup is saved for rollback.
Scan Remaining
Re-scans after a replacement run to count remaining local URLs. Run to confirm replacement was complete.

Revert to Local URLs

Scan — Preview Revert
Shows how many files can be reverted (those with a local copy still on disk) before committing.
Revert to Local URLs
Rewrites CDN URLs back to local paths and removes offload metadata, making files available for re-migration to a different provider.

Rollback History

Every URL Replace batch is logged. Each entry shows date, number of URLs replaced, and a Rollback button — full undo without any backup plugin needed.

When to run URL Replace: After Bulk Migration completes. After switching CDN domains. After enabling a custom domain. If Dynamic URL Rewriting is off and images load from local paths.

Scheduled Offload

Run offload automatically every day at a time you choose. Designed for sites that receive regular uploads and want hands-off media management.

🗂OffloadX›Scheduled Offload

Controls

Enable Scheduled Offload Starter+
Toggle. Registers a daily WP-Cron event. Self-healing — if the cron is cleared, it re-registers on the next page load.
Daily Time
Time picker. The time (in your site's timezone) when the job runs. Default is 02:00. Save settings after changing to reschedule.
▶ Run Now
Triggers the scheduled job immediately without waiting for cron. Useful for testing. Processes all pending files exactly like the daily run.

How it works

Unlike a simple cron that processes a fixed batch, the scheduled run loops continuously until every pending file is processed — up to a 2-hour maximum. It processes 50 files per loop iteration and stops only when no pending files remain or time runs out.

WP-Cron note: WP-Cron only fires when your site receives a page visit. On low-traffic sites, add a real server cron:
* * * * * curl -s https://yoursite.com/wp-cron.php?doing_wp_cron > /dev/null

Safety Check

Verify that every offloaded file is publicly accessible via its CDN URL before permanently deleting local copies. Prevents data loss from broken uploads.

🗂OffloadX›Safety Check
Run Safety Check
Makes HTTP HEAD requests to each CDN URL and checks for a 200 response. Files returning 404 or other errors are flagged as unsafe. Results shown inline with total checked, passed, and failed.
Delete All Local Files
Unlocked only after Safety Check passes. Permanently removes local file copies from your server. Irreversible — run verification first.
Warning: Deleting local copies is permanent. Always run Safety Check first. Keep a server backup before running bulk deletions. Deleted files cannot be restored except from a backup.

Cache Tools

After migration and URL replacement, flush your site's caches so visitors see the new CDN URLs instead of cached local paths.

🗂OffloadX›Cache
Clear All Caches
Detects and flushes all installed caching plugins simultaneously. Supports: WP Rocket, W3 Total Cache, WP Super Cache, LiteSpeed Cache, WP Fastest Cache, SG Optimizer, and WordPress's built-in object cache.
Regenerate Elementor CSS
Forces Elementor to rebuild its CSS files. Required when generated stylesheets contain references to old local image URLs (e.g. background images set in Elementor widgets).
When to run: After Bulk Migration. After URL Replace. Any time your CDN domain changes. If users report seeing broken or outdated images after migration.

Manage Files

Browse, inspect, search, and delete files directly in your storage bucket from WP Admin — no need to log in to your provider's dashboard.

🗂OffloadX›Manage Files

View Modes

Database View
Shows files recorded as offloaded in the WordPress database. Fast — no network request. May not reflect files deleted directly in your storage dashboard.
Scan Storage
Fetches up to 1,000 objects per page directly from your storage provider. Shows the true state of your bucket — including files not in the WordPress database. Recommended for finding orphans.

File List

File
Thumbnail preview and filename. Shows "unknown" for files not linked to a WordPress attachment.
Path in Storage
Full object key/path within your bucket. Click to open the CDN URL in a new tab.
WP Status
In Library — linked to a WordPress attachment. Orphan — exists in storage but has no corresponding attachment. Orphans can be safely deleted if unneeded.
Permanent operation: Files deleted from storage cannot be recovered. The WordPress attachment record is not deleted — only the file in the bucket.

AI Advisor

An AI-powered chat assistant inside your dashboard that answers questions about your media setup, migration strategy, provider selection, and cost optimisation.

🗂OffloadX›AI Advisor

Quick Prompts

Analyze my setup

Reviews your current provider, file counts, and coverage to give specific improvement recommendations.

Migration plan

Generates a step-by-step plan to safely move all remaining local media to cloud storage.

Recommend a provider

Based on your site stats, recommends the best storage provider for your use case.

Reduce costs

Suggests ways to reduce storage and bandwidth costs while maintaining performance.

Free-form Chat

Type any question and click Ask AI. The advisor has context about your site's stats — total media, offloaded count, pending files — so answers are specific to your situation.

Powered by: Uses GPT-4o mini via the API key configured in your license server settings. Requires a Pro license or higher.

License

Manage your OffloadX license key, view your plan details, and access the version history for rollbacks.

🔑WP Admin sidebar›OffloadX → License

Activating a License

1

Paste your license key

Enter the license key from your purchase email. Keys are in the format XXXX-XXXX-XXXX-XXXX.

2

Click Activate

OffloadX contacts the license server, validates the key, and registers your site's URL. Features unlock instantly — no page reload required.

3

Status updates

The card updates to show your plan tier, expiry date, active sites vs allowed, and a green "Active" badge.

Plan Information

Plan tier
Free, Starter, Pro, Business, or Agency — shown as a colour-coded badge.
Expiry date
For monthly/annual licenses. Lifetime licenses show "Lifetime".
Sites
Active sites vs allowed — e.g. "1 / 3". Each domain you activate counts as one site.

Version History & Rollback

1

Click "Load versions"

Fetches all available releases from the update server. Each version shows upload date, release notes, and WP/PHP requirements.

2

Click the version button

Newer versions show an Update button; older versions show a Roll back button.

3

Confirm and install

WordPress downloads the zip via a signed URL and installs it using its native upgrader. Settings, license data, and all WP options are untouched.

Signed URLs expire in 1 hour. If an install fails due to an expired URL, reload the version list and try again.

Cloudflare R2 Setup

Zero egress fees, 10 GB free monthly storage, and a global CDN. The most cost-effective option for most WordPress sites.

Free tier: 10 GB storage + 1M Class A ops + 10M Class B ops/month at no cost. Zero egress fees.

1. Create a Bucket

1

Cloudflare Dashboard → R2 Object Storage → Create Bucket

Log in at dash.cloudflare.com. Left sidebar → Storage & Databases → R2 Object Storage → Create Bucket.

2

Name and location

Give it a name e.g. my-wp-media. Location: Automatic is fine. Click Create Bucket.

3

Enable public access

Open the bucket → Settings → Public Access → enable R2.dev subdomain. This gives you a free public URL like pub-xxxx.r2.dev.

2. Create an API Token

1

R2 Overview → Manage R2 API Tokens → Create API Token

2

Set Permissions to "Object Read & Write", select your bucket, no expiry

3

Copy all three values

Access Key ID, Secret Access Key (shown once), and your Account ID from the R2 Overview URL.

3. Fields in OffloadX

Account ID required
Your Cloudflare Account ID. Found in the R2 Overview URL: dash.cloudflare.com/{account_id}/r2
Bucket Name required
Exact bucket name. Case-sensitive. Example: my-wp-media
Access Key ID required
From your R2 API token.
Secret Access Key required
From your R2 API token. Only shown once — copy immediately.
Delivery URL optional
Your pub-xxxx.r2.dev URL or custom domain. Example: https://pub-abc123.r2.dev
R2 buckets are private by default. Files are not publicly accessible until you enable the R2.dev subdomain or connect a custom domain in R2 Settings → Public Access.

Amazon S3 Setup

Industry-standard object storage with broad region coverage. Egress fees apply — consider pairing with CloudFront for CDN delivery.

1. Create a Bucket

1

AWS Console → S3 → Create Bucket

Log in at console.aws.amazon.com. Choose a unique name and the region closest to your server.

2

Configure public access

Uncheck Block all public access and add a bucket policy granting s3:GetObject to Principal: * on all objects.

2. Create IAM Credentials

1

IAM → Users → Create User (e.g. offloadx-wp)

2

Attach policy — minimum: s3:PutObject, s3:GetObject, s3:DeleteObject, s3:ListBucket

3

Security credentials → Create access key → copy Access Key ID and Secret

3. Fields in OffloadX

Bucket Name required
Exact S3 bucket name.
Region required
Must match the region chosen at bucket creation. Example: us-east-1, eu-west-1
Access Key ID required
IAM user Access Key ID. Starts with AKIA...
Secret Access Key required
IAM user Secret Access Key. Only shown once at creation.
Custom CDN Domain optional
CloudFront or custom domain. Example: https://cdn.yourdomain.com

Wasabi Setup

S3-compatible storage with no egress fees and flat-rate pricing. Excellent value for high-bandwidth sites.

1. Create a Bucket & Access Key

1

console.wasabisys.com → Buckets → Create Bucket

Name your bucket, choose a region. Note the exact region code.

2

Access Keys → Create New Access Key

Copy the Access Key and Secret Key immediately.

2. Fields in OffloadX

Bucket Name required
Your Wasabi bucket name.
Region required
Must match bucket region. Example: ap-southeast-1, us-east-1, eu-central-1
Access Key ID required
Wasabi access key.
Secret Access Key required
Wasabi secret key. Only shown once.
Custom CDN Domain optional
If fronting Wasabi with a CDN, enter the CDN URL here.

DigitalOcean Spaces Setup

Simple S3-compatible object storage with a built-in CDN. Ideal for teams already on DigitalOcean infrastructure.

1. Create a Space

1

cloud.digitalocean.com → Spaces → Create a Space

Choose a region (e.g. nyc3, ams3, sgp1). Enable the CDN if desired.

2

API → Spaces Keys → Generate New Key

Not the same as your DigitalOcean API token. Spaces keys are separate. Copy the Key and Secret shown once.

2. Fields in OffloadX

Bucket Name required
Your Space name.
Region required
Your Space's region code. Example: nyc3, ams3, sgp1
Access Key ID required
Spaces Key from API → Spaces Keys.
Secret Access Key required
Spaces Secret. Not recoverable — create new if lost.
CDN Endpoint optional
If CDN is enabled: https://your-space.nyc3.cdn.digitaloceanspaces.com

Bunny Storage Setup

Ultra-low cost storage with no egress fees. Requires a Pull Zone for public file delivery.

1. Create a Storage Zone

1

dash.bunny.net → Storage → Add Storage Zone

Enter a zone name, choose a region. Note the exact zone name.

2

Zone → FTP & API Access → copy the Password (= API key)

3

CDN → Add Pull Zone → set Origin URL to your storage zone

The Pull Zone CDN URL (e.g. https://my-zone.b-cdn.net) is what OffloadX uses for public media URLs.

2. Fields in OffloadX

Storage Zone Name required
Exact Storage Zone name. Case-sensitive.
API Key required
The Password from FTP & API Access. This authenticates uploads.
Storage Region required
Must match the region of your Storage Zone.
Pull Zone CDN URL required
Your Bunny CDN Pull Zone URL. Required — without this, media won't load publicly. Example: https://my-zone.b-cdn.net
Pull Zone is required. Bunny Storage URLs are private. Only the Pull Zone CDN URL is publicly accessible.

Plans & Features

OffloadX is freemium. The Free plan works without any license key. Paid plans unlock features and higher file limits.

FeatureFreeStarterProBusinessAgency
Basic migration & auto offload✓✓✓✓✓
Dashboard & URL rewriting✓✓✓✓✓
File limit50 filesUnlimitedUnlimitedUnlimitedUnlimited
WebP conversion—✓✓✓✓
Scheduled offload—✓✓✓✓
DB URL Replace + rollback—✓✓✓✓
Safety Check—✓✓✓✓
Offload Documents & PDFs——✓✓✓
Email notifications——✓✓✓
Manage Files & CDN scan——✓✓✓
Cache Tools——✓✓✓
Site Folder in Storage———✓✓
Selective MIME Types———✓✓
WooCommerce support———✓✓
6 parallel migration lanes————✓
Background mode (30s cron)————✓

Updates & Rollback

OffloadX is self-hosted — updates come directly from offloadx.com, not WordPress.org. The update system works exactly like a WordPress.org plugin.

Automatic updates
The plugin checks for updates every 12 hours. When available, the standard yellow "Update Available" banner appears in Plugins → Installed Plugins.
Manual update check
In Plugins → Installed Plugins, find OffloadX and click Check for Updates. Clears the 12-hour cache and forces an immediate check.
Version rollback
Go to OffloadX → License → Version History. Click Load versions, then select any previous release. Settings are preserved.
License required: A valid active license is required to download updates. Free plan users see the notice but cannot download — upgrade at offloadx.com/pricing.

Beyond This WordPress Plugin Documentation

Step-by-step guides and official references that go further than this WordPress plugin documentation.

Provider setup guides

Each guide covers the provider side in detail, with costs, limits and troubleshooting: Cloudflare R2, Amazon S3, Wasabi, Bunny Storage, DigitalOcean Spaces and Backblaze B2.

Official provider documentation

For bucket settings, keys and permissions, the providers' own docs are the final word: Cloudflare R2 docs, Amazon S3 user guide and WordPress.org's guide to managing plugins.

Planning your setup

Not sure which provider to pick, or moving from another plugin? Start with our cloud storage cost comparison, the media offload vs CDN guide and the WP Offload Media migration guide. If something in this WordPress plugin documentation is unclear, email support and we will help.

Troubleshooting

Solutions to the most common issues.

SignatureDoesNotMatch error

The Secret Access Key stored in the database doesn't match what the provider expects.

Fix: Go to Credentials, re-enter your Secret Access Key (even without changing it), and click Save Settings. This re-encrypts against your current WordPress salts. Then click Test Connection.

"2 Pending" but all images look fine

PDFs, DOCX, ZIP, or other document files are in your media library. OffloadX only counts image/video/audio by default. Enable Offload Documents & PDFs under Behaviour (Pro+) to include them.

Files uploading but not loading publicly

Cloudflare R2

Enable the R2.dev subdomain in your bucket's Settings → Public Access, or connect a custom domain.

Amazon S3

Disable Block Public Access and add a bucket policy granting s3:GetObject to all principals.

Bunny Storage

Create a Pull Zone and enter its CDN URL in the Pull Zone field. Storage Zone URLs are never public.

Wrong delivery URL

Check the Delivery section in Credentials. The URL must match where files are actually accessible. Run URL Replace after correcting.

Test Connection fails

1

Re-save credentials

Re-type the Secret Access Key and save. Salts may have changed since first save.

2

Check permissions

Your API key needs PutObject + GetObject + DeleteObject + ListBucket permissions on the bucket.

3

Check region

For S3/Wasabi/DO: region in OffloadX must exactly match the region chosen when creating the bucket.

4

Check CORS / bucket policy

Some providers block all access by default. Check your bucket's access policy and ensure it allows the required operations from your server's IP.

Need more help?

Email [email protected] with your provider name, the exact error message, and the result of Test Connection.