Usage

Starting the proxy

Start Manael by specifying the address to listen on and the upstream server URL:

manael -http=:8080 -upstream_url=http://localhost:9000

Converting JPEG to WebP

Manael converts JPEG and PNG images to WebP automatically when the client signals support for WebP via the Accept request header. No configuration is needed beyond starting the proxy.

To request a JPEG image and receive it as WebP, include image/webp in the Accept header:

curl -sI -H "Accept: image/webp" http://localhost:8080/image.jpg

When conversion succeeds, the response includes Content-Type: image/webp:

HTTP/1.1 200 OK
Content-Type: image/webp
Vary: Accept
...

If the client does not include image/webp in the Accept header, the original image is returned unchanged.

Converting images to AVIF

Manael can also convert JPEG images to AVIF. AVIF conversion is disabled by default and must be enabled with the MANAEL_ENABLE_AVIF environment variable:

MANAEL_ENABLE_AVIF=true manael -http=:8080 -upstream_url=http://localhost:9000

When AVIF is enabled and the client includes image/avif in the Accept header, Manael converts eligible images to AVIF:

curl -sI -H "Accept: image/avif" http://localhost:8080/image.jpg

A successful conversion returns Content-Type: image/avif:

HTTP/1.1 200 OK
Content-Type: image/avif
Vary: Accept
...

Note: AVIF conversion is intentionally disabled for PNG source images to prioritize compatibility and performance. PNG images are still converted to WebP when the client supports it.

Animated PNG (APNG) pass-through

Manael automatically detects Animated PNG (APNG) files and passes them through to the client without conversion. This prevents losing animation data that would occur if an APNG were converted to a static WebP or AVIF frame. The original APNG is returned unchanged regardless of the Accept header.

Content-Disposition header updates

When Manael converts an image to a different format, it automatically updates the filename extension in the Content-Disposition response header to match the new format. For example, if an upstream response includes:

Content-Disposition: attachment; filename="photo.jpg"

and the image is converted to WebP, Manael updates the header to:

Content-Disposition: attachment; filename="photo.webp"

The same update applies when converting to AVIF (.avif extension).

Advanced configuration

Environment variables

In addition to command-line flags, Manael supports configuration via environment variables.

The -upstream_url flag takes precedence over MANAEL_UPSTREAM_URL when both are provided.