truss

truss is a library-first image toolkit that reuses the same transformation core across the CLI, HTTP server, and WASM demo. User-facing behavior is locked down with Docker-based integration tests using ShellSpec and runn, so the CLI and API remain aligned with executable documentation.

• Cross Platform: support Linux, macOS, Windows
• Tested contracts: the CLI is covered by ShellSpec and the HTTP API by runn, keeping user-visible behavior under integration test.
• Security by default: signed URLs, SSRF protections, and SVG sanitization are built in.
• Practical image pipeline: handles JPEG, PNG, WebP, AVIF, BMP, and SVG, with support for retaining metadata such as EXIF, ICC, and XMP where possible.

Requirements

Supported Formats

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

Installation

cargo install truss-image

This installs the truss command.

Usage

CLI

Convert image formats:

truss photo.png -o photo.jpg

Resize and 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 by removing scripts and external references:

truss diagram.svg -o safe.svg

Rasterize SVG:

truss diagram.svg -o diagram.png --width 1024

Inspect image metadata:

truss inspect photo.jpg

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

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.

Shell Completions

Generate completion scripts with the completions subcommand:

# 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

HTTP Server

truss serve

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
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

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

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
cargo install wasm-bindgen-cli --version 0.2.114
./scripts/build-wasm-demo.sh

The build output is written to web/dist/.

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

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

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

Contributing

Contributions are welcome. See CONTRIBUTING.md for details.

• 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.