truss

Resize, crop, convert, optimize, blur, sharpen, 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.

Comparison

Feature comparison with imgproxy and imagor as of March 2026.

Architecture

flowchart TB
    CLI["CLI<br/>(truss convert)"] --> Core
    Server["HTTP Server<br/>(truss serve)"] --> Core
    WASM["WASM<br/>(browser)"] --> Core

    subgraph Core["Shared Rust core"]
        direction LR
        Sniff["Detect format"] --> Transform["Crop / resize / blur / sharpen / watermark"]
        Transform --> Encode["Encode output"]
    end

    Server --> Storage

    subgraph Storage["Storage backends"]
        FS["Local filesystem"]
        S3["S3"]
        GCS["GCS"]
        Azure["Azure Blob"]
    end

CLI reads local files or fetches remote URLs directly. The HTTP server resolves images from storage backends or client uploads. The WASM build processes files selected in the browser.

Installation

cargo install truss-image

Prebuilt binaries are available on the GitHub Releases page. See Deployment Guide for details on all targets and Docker images.

Quick Start

CLI

The convert subcommand can be omitted: truss photo.png -o photo.jpg is equivalent to truss convert photo.png -o photo.jpg. Run truss convert --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

# Optimize in place with the shared pipeline
truss optimize photo.jpg -o photo-optimized.jpg --mode auto

# 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

# Inspect metadata
truss inspect photo.jpg

Format conversion & quality

truss supports JPEG, PNG, WebP, AVIF, BMP, TIFF, and SVG. The output format is inferred from the file extension, or you can specify it explicitly with --format.

# JPEG → WebP (smaller file, same visual quality)
truss photo.jpg -o photo.webp --quality 80

# JPEG → AVIF (best compression)
truss photo.jpg -o photo.avif --quality 50

# Explicit format override (ignore extension)
truss photo.jpg -o output.bin --format png

Use --quality <1-100> to control lossy encoding. Lower values produce smaller files at the cost of visual quality.

Use --optimize auto|lossless|lossy on truss convert, or the dedicated truss optimize subcommand, to reduce output size with format-aware encoding choices. Add --target-quality ssim:0.98 or --target-quality psnr:42 when you want lossy optimization to aim for a specific perceptual threshold.

Quality 90 (95 KB)	Original (80 KB)	Quality 30 (27 KB)

Resize & fit modes

Specify --width and/or --height to resize. When both are given, --fit controls how the image fits the target box:

Original (640 × 427)	contain 300 × 300	cover 300 × 300	fill 300 × 300	inside 300 × 300

# contain -- fit inside the box, pad with gray background
truss photo.jpg -o out.jpg --width 300 --height 300 --fit contain --background CCCCCC

# cover -- fill the box, crop the excess
truss photo.jpg -o out.jpg --width 300 --height 300 --fit cover

# fill -- stretch to exact dimensions
truss photo.jpg -o out.jpg --width 300 --height 300 --fit fill

# inside -- like contain, but never upscale
truss photo.jpg -o out.jpg --width 300 --height 300 --fit inside

# Width only -- height is calculated to preserve aspect ratio
truss photo.jpg -o out.jpg --width 800

Cover position

When using --fit cover, --position controls which part of the image is kept:

--position top-left	--position center (default)	--position bottom-right

Available positions: center, top, right, bottom, left, top-left, top-right, bottom-left, bottom-right.

truss photo.jpg -o thumb.jpg --width 300 --height 300 --fit cover --position top-left

Crop, rotate & background

# Crop a region (x, y, width, height) -- applied before resize
truss photo.jpg -o cropped.jpg --crop 100,50,400,300

# Rotate 270 degrees clockwise (accepts 0, 90, 180, 270)
truss photo.jpg -o rotated.jpg --rotate 270

# Background color as RRGGBB or RRGGBBAA hex (useful with contain or PNG alpha)
truss photo.jpg -o out.png --width 300 --height 300 --fit contain --background FF6B35FF

Original	Crop (--crop 100,50,400,300)	Rotate (--rotate 270)	Background (--background FF6B35FF)

Blur, sharpen & watermark

Original	Gaussian Blur (--blur 5.0)	Sharpen (--sharpen 3.0)	Watermark

# Gaussian blur (sigma 0.1 - 100.0)
truss photo.jpg -o blurred.jpg --blur 5.0

# Sharpen (sigma 0.1 - 100.0)
truss photo.jpg -o sharpened.jpg --sharpen 3.0

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

Watermark positions are the same as cover positions: center, top, right, bottom, left, top-left, top-right, bottom-left, bottom-right.

Note: --blur, --sharpen, and --watermark are raster-only and not supported for SVG inputs.

Metadata control

By default, truss strips all metadata for smaller and safer output.

# Keep all metadata (useful for archival)
truss photo.jpg -o out.jpg --keep-metadata

# Keep EXIF only (strip ICC profiles)
truss photo.jpg -o out.jpg --preserve-exif

# Disable auto-orientation
truss photo.jpg -o out.jpg --no-auto-orient

Stdin / stdout piping

Use - for input and/or output to integrate truss into shell pipelines. When reading from stdin, --format is required for output.

# Pipe from stdin to stdout
cat photo.png | truss - -o - --format jpeg > photo.jpg

# Download, convert, and upload in one pipeline
curl -s https://example.com/img.png | truss - -o - --format webp --width 800 | \
  aws s3 cp - s3://bucket/thumb.webp

# Optimize after converting
truss photo.jpg -o - --format webp --optimize auto | cat > optimized.webp

SVG handling

truss sanitizes SVG files by removing scripts and external references, making them safe for user-generated content.

# Sanitize SVG (remove scripts, external refs)
truss diagram.svg -o safe.svg

# Rasterize SVG to PNG at a specific width
truss diagram.svg -o diagram.png --width 1024

Filenames starting with -

Use --output= (or --output) to avoid ambiguity with filenames that start with a dash:

# Dash-prefixed output: use --output= to assign the value unambiguously
truss convert input.png --output=-output.jpg

# Dash-prefixed input: use a path prefix
truss convert ./-input.png -o out.jpg

HTTP Server -- one curl to transform

# Start the server
TRUSS_BEARER_TOKEN=changeme truss serve --bind 0.0.0.0:8080 --storage-root ./images

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

See the API Reference for the full endpoint list and CDN integration guide.

Commands

Documentation

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.