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.

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

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.