truss

Resize, convert, blur, and watermark images from the CLI, an HTTP server, or the browser -- written in Rust with signed-URL authentication and SSRF protection built in.

Try the WASM demo in your browser -- no install, no upload, runs 100 % client-side.

Why truss?

• One binary, three interfaces -- the same Rust core powers the CLI, an HTTP image-transform server, and a WASM browser demo.
• Security by default -- signed URLs, SSRF protections, and SVG sanitization are built in.
• Broad format support -- JPEG, PNG, WebP, AVIF, BMP, and SVG; retains EXIF, ICC, and XMP metadata where possible.
• Cross-platform -- Linux, macOS, Windows.
• Tested contracts -- CLI behavior is locked by ShellSpec, HTTP API by runn.

Installation

cargo install truss-image

This installs the truss command.

Quick Start

CLI

Run truss --help to see the full set of options.

# Convert format
truss photo.png -o photo.jpg

# Resize + convert
truss photo.png -o thumb.webp --width 800 --format webp --quality 75

# Convert from a remote URL
truss --url https://example.com/img.png -o out.avif --format avif

# Sanitize SVG (remove scripts and external references)
truss diagram.svg -o safe.svg

# Rasterize SVG
truss diagram.svg -o diagram.png --width 1024

# Inspect metadata
truss inspect photo.jpg

Filter: Before / After

	Original	Gaussian Blur (--blur 5.0)	Watermark (--watermark)

# Blur
truss photo.jpg -o blurred.jpg --blur 5.0

# Watermark
truss photo.jpg -o watermarked.jpg \
  --watermark logo.png --watermark-position bottom-right \
  --watermark-opacity 50 --watermark-margin 10

HTTP Server -- one curl to transform

# Start the server
docker run -p 8080:8080 \
  -e TRUSS_BIND_ADDR=0.0.0.0:8080 \
  -e TRUSS_BEARER_TOKEN=changeme \
  -v ./images:/data:ro \
  -e TRUSS_STORAGE_ROOT=/data \
  ghcr.io/nao1215/truss:latest

# Resize a local image to 400 px wide WebP in one request
curl -X POST http://localhost:8080/images:transform \
  -H "Authorization: Bearer changeme" \
  -F "file=@photo.jpg" \
  -F 'options={"format":"webp","width":400}' \
  -o thumb.webp

# Signed public URL (no Bearer token needed)
truss sign --base-url http://localhost:8080 \
  --path photos/hero.jpg --key-id mykey --secret s3cret \
  --expires 1700000000 --width 800 --format webp
# => http://localhost:8080/images/by-path?path=photos/hero.jpg&width=800&format=webp&keyId=mykey&expires=1700000000&signature=...

Commands

The convert subcommand can be omitted: truss photo.png -o photo.jpg is equivalent to truss convert photo.png -o photo.jpg. Similarly, server flags at the top level imply serve: truss --bind 0.0.0.0:8080 is equivalent to truss serve --bind 0.0.0.0:8080.

Supported Formats

SVG to SVG performs sanitization only, removing scripts and external references.

HTTP Server

By default, the server listens on 127.0.0.1:8080. Configuration can be supplied through environment variables or CLI flags.

truss serve --bind 0.0.0.0:8080 --storage-root /var/images

Key environment variables:

API reference:

• OpenAPI YAML: doc/openapi.yaml
• Swagger UI on GitHub Pages: https://nao1215.github.io/truss/swagger/

Docker

docker compose up

This starts the server from compose.yml. The default configuration mounts ./images as the storage root.

To build and run it directly:

docker build -t truss .
docker run -p 8080:8080 \
  -e TRUSS_BIND_ADDR=0.0.0.0:8080 \
  -e TRUSS_BEARER_TOKEN=changeme \
  -v ./images:/data:ro \
  -e TRUSS_STORAGE_ROOT=/data \
  truss

Prebuilt container images are published to GHCR:

docker pull ghcr.io/nao1215/truss:latest

The first GHCR package publish is private by default. To allow anonymous pulls from ECS, change the package visibility to Public in GitHub Packages settings once after the first publish.

WASM Demo

A browser demo is available on GitHub Pages:

https://nao1215.github.io/truss/

The demo is a static browser application. Selected image files are processed in the browser, are not sent to a truss backend or any other external system, and are not stored by the demo.

To build the demo locally, use scripts/build-wasm-demo.sh:

rustup target add wasm32-unknown-unknown
# The wasm-bindgen-cli version must match the wasm-bindgen dependency in Cargo.toml.
cargo install wasm-bindgen-cli --version 0.2.114
./scripts/build-wasm-demo.sh

The build output is written to web/dist/.

Shell Completions

# Bash
truss completions bash > ~/.local/share/bash-completion/completions/truss

# Zsh (add ~/.zfunc to your fpath)
truss completions zsh > ~/.zfunc/_truss

# Fish
truss completions fish > ~/.config/fish/completions/truss.fish

# PowerShell
truss completions powershell > truss.ps1

CDN / Reverse-Proxy Integration

truss is an image transformation origin, not a CDN itself. In production, place a CDN such as CloudFront (or a reverse proxy like nginx / Envoy) in front of truss so that transformed images are cached at the edge.

flowchart LR
    Viewer -->|HTTPS request| CloudFront
    CloudFront -->|cache hit| Viewer
    CloudFront -->|cache miss| ALB["ALB / nginx / Envoy"]
    ALB --> truss
    truss -->|read source| Storage["Local storage<br/>or remote URL origin"]

• CloudFront is the cache layer. It serves cached responses directly on cache hits.
• truss is the origin API. Image transformation runs on truss, not on CloudFront.
• An ALB or reverse proxy is recommended between CloudFront and truss because truss does not handle TLS termination or large-scale traffic on its own.
• The truss on-disk cache (TRUSS_CACHE_ROOT) is a single-node auxiliary cache that reduces redundant transforms on the origin; it is not a replacement for the CDN cache.

Public vs. Private Endpoints

Only the public GET endpoints should be exposed through CloudFront:

CDN Cache Key Configuration

CDN cache keys must vary by the signed-URL authentication inputs and any transform query parameters used by the public GET endpoints (GET /images/by-path, GET /images/by-url). Configure your CDN / CloudFront Cache Policy to include the following query string parameters in the cache key (or use a policy that forwards all query strings):

• Authentication: keyId, expires, signature
• Source: path or url, version
• Transform: width, height, fit, position, format, quality, background, rotate, autoOrient, stripMetadata, preserveExif, blur, watermark, watermarkPosition, watermarkOpacity, watermarkMargin

This ensures that a cached response for one signed URL is not served to requests with different or expired signatures, and different transform options produce separate cache entries.

TRUSS_PUBLIC_BASE_URL

When truss runs behind CloudFront, set TRUSS_PUBLIC_BASE_URL to the public CloudFront domain (e.g. https://images.example.com). Signed-URL verification compares the request authority against this value; a mismatch will cause signature validation to fail.

TRUSS_PUBLIC_BASE_URL=https://images.example.com truss serve

Requirements

Benchmark

Measured with doc/img/logo.png (1536 x 1024 PNG, 1.6 MB) on AMD Ryzen 7 5800U. Each operation was run 10 times; the table shows min / avg / max wall-clock time.

Conversion speed

Output file size

Roadmap

See the public roadmap for planned features and milestones.

Contributing

Contributions are welcome. See CONTRIBUTING.md for details.

• Look for good first issue to get started.
• Report bugs and request features via Issues.
• If the project is useful, starring the repository helps.
• Support via GitHub Sponsors is also welcome.
• Sharing the project on social media or in blog posts is appreciated.

License

Released under the MIT License.