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 -X GET -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.

Note: Manael only converts images for GET requests. HEAD requests (and other HTTP methods) are passed through to the upstream server unchanged. When testing from the command line, use curl -sI -X GET to fetch the headers of a converted image.

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 -X GET -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.

On-the-fly image resizing

Manael can resize images on-the-fly using the w, h, and fit query parameters. Resizing is disabled by default and must be enabled with the MANAEL_ENABLE_RESIZE environment variable:

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

When resizing is enabled, clients can request a specific size by appending query parameters to the image URL:

curl -sI -X GET -H "Accept: image/webp" "http://localhost:8080/image.jpg?w=800&h=600&fit=cover"

When MANAEL_ENABLE_RESIZE is not set to true, resize parameters (w, h, fit) are silently ignored and the image is converted without resizing.

Note: Image resizing is a CPU- and memory-intensive operation. Enable it only when needed and consider setting MANAEL_MAX_RESIZE_WIDTH and MANAEL_MAX_RESIZE_HEIGHT to limit resource usage.

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.