Local Media Proxy

Local Media Proxy is an Amsive add-on for Local that keeps WordPress uploads out of local clones without breaking asset-heavy pages. Existing eligible uploads remain local; only safe missing assets below /wp-content/uploads/ fall back to a configured production, staging, or development site.

Local Media Proxy is open-source, community-supported software released under the Apache License 2.0.

Features

• Enables the fallback independently for each Local site.
• Supports Local sites using Nginx or Apache.
• Auto-populates connected WP Engine environments and supports manual configuration for other hosts.
• Uses public DNS suggestions for Nginx only when provider-specific discovery is unavailable.
• Proxies safe missing upload assets without enumerating media formats, allows only GET and HEAD, and forwards no request body, cookies, or credentials.
• Verifies HTTPS identity and certificate chains against standard public roots and Cloudflare's published Origin CA roots.
• Applies bounded, reversible managed configuration and removes it when the proxy is disabled.
• Stays inactive while Local creates a site, performs an initial pull, or deletes it, with no managed-file access or settings writes until the site is lifecycle-ready and running or halted. During transitions, the UI shows a static unavailable state without proxy controls or an indefinite progress indicator.

Requirements

• Local 10.1.1 or newer
• A Local site using Nginx or Apache
• A standard WordPress uploads path at /wp-content/uploads/
• Network access to the configured remote endpoint
• For Apache HTTPS, a Local Apache bundle that includes mod_ssl

The current official Intel macOS +11 Apache bundle does not include mod_ssl, so that specific bundle supports HTTP origins only. Compatible Apple silicon macOS, Linux, and Windows bundles retain Apache HTTPS support.

Install

1. Download local-media-proxy-v<version>.tgz and its optional .tgz.sha256 file from the matching GitHub release.
2. In Local, open Add-ons → Installed.
3. Choose Install from disk and select the .tgz directly without extracting it.
4. Enable the add-on and restart Local if prompted.

Local cannot overwrite an installed add-on with the same slug. To update manually, first disable and remove the existing Local Media Proxy installation. When upgrading from a release before v0.4.1, the older uninstaller may clear a site's enabled state; enable that site once after installing v0.4.1. Later v0.4.1 disable, uninstall, and reinstall cycles preserve enabled intent.

Configure a site

1. Select a site in Local and open Tools → Media Proxy.
2. Choose a connection:
   • WP Engine: Select the connected environment and choose Auto-populate from WP Engine.
   • Flywheel or another host: Enter a Site URL manually. For Nginx, also enter a trusted remote IP or use Find via public DNS.
   • Apache: Enter the Site URL. Apache resolves that hostname directly and does not use a separate remote IP.
3. Choose Test connection. HTTPS checks verify both the certificate chain and expected identity.
4. Choose Save & apply, then turn on Enable for this site.
5. Load an upload asset that is absent locally. A successful fallback returns 200 with X-Local-Media-Proxy: origin.

Enter only a URL scheme and hostname plus an optional port, such as https://example.com. Do not include credentials, paths, query strings, or fragments. Discovered values are suggestions and are never saved or enabled without an explicit action.

How it works

Browser requests /wp-content/uploads/.../asset.ext
             |
             v
       File exists locally? ---- yes ---> serve local file
             |
             no
             v
Verified remote endpoint ---> stream asset response

Nginx can connect to a selected IP while preserving the Site URL as the HTTP Host. Guarded WP Engine discovery may also preserve a provider-returned direct hostname for TLS verification. Apache uses one validated Site URL hostname for DNS, Host, TLS SNI, and certificate identity.

The add-on supports images, video, audio, captions, PDFs, documents, fonts, archives, generated CSS, and future file formats without maintaining an extension allowlist. It rejects executable, browser-active, hidden, configuration, secret, database, and backup files; browser execution destinations fail closed, and upstream redirect targets are not exposed to the local browser. It never proxies themes, plugins, APIs, arbitrary missing URLs, or non-upload paths. Responses stream without a persistent media cache.

On macOS, if Local loses track of a running site's Nginx or Apache listener, Media Proxy can recover a verified orphaned Local web-server process tree on that exact site port and restart only Local's existing selected-service process. The same bounded repair covers an untracked standard-domain router by restarting only its existing process, without rebuilding routes or changing hosts or routing mode. Stopped sites and unrelated port owners remain untouched.

HTTPS and Cloudflare Origin CA

HTTPS is verified against Node's standard certificate authorities plus Cloudflare's published RSA and ECC Origin CA roots. The two Cloudflare fingerprints and the bundled PEM hash are pinned by automated release checks.

This supports sites that correctly present Cloudflare Origin Certificates without trusting arbitrary self-signed certificates. Hostname mismatches, expired certificates, invalid chains, and unrecognized self-signed certificates remain rejected. There is no certificate-verification bypass or runtime CA download.

See Technical details for the full Nginx/Apache identity model, request filtering, managed files, rollback behavior, Local lifecycle integration, and troubleshooting.

Development

npm install
npm run verify:public-release
npm run verify:third-party
npm run validate
npm run package:addon

The release installer uses npm's single package/ root and contains exactly 29 reviewed runtime files. Source, tests, source maps, dependencies, and repository-only process documents are excluded.

See CONTRIBUTING.md for development and DCO requirements, PUBLIC_RELEASE_SAFETY.md for the blocking public-content review, and RELEASING.md for the draft and promotion workflow.

Support, security, and conduct

• Use the project-specific issue forms for reproducible bugs and focused feature requests.
• Read SUPPORT.md for the best-effort community support policy.
• Report suspected vulnerabilities privately through SECURITY.md.
• Community participation is governed by CODE_OF_CONDUCT.md.

Do not submit client information, production domains or addresses, credentials, cookies, private certificates, proprietary code, or material you are not authorized to contribute.

License and third-party material

Copyright © 2026 Amsive LLC.

Amsive-authored source and packaged files are distributed under the Apache License 2.0. Third-party material and applicable terms are identified in NOTICE and the provenance record. The software is provided on an as-is basis without warranties or conditions of any kind.

The Apache license does not grant rights to use Amsive trademarks beyond customary attribution; see TRADEMARKS.md. References to Local, WP Engine, Flywheel, WordPress, Cloudflare, and other products describe compatibility and do not imply sponsorship or endorsement.

Maintained by Amsive LLC. Developed by Mark Davoli and Boris Hegedis.