Environment Variables
Every configuration option can be set via an environment variable or the corresponding CLI flag. CLI flags take precedence over environment variables when both are provided.
Server
| Variable | CLI Flag | Default | Description |
|---|---|---|---|
PORT | --port | 8080 | Server listen port |
APP_ENV | --env | development | Environment: development or production |
MAX_CONCURRENT_REQUESTS | (no flag) | 256 | Max number of concurrent requests |
Security
| Variable | CLI Flag | Default | Description |
|---|---|---|---|
HMAC_KEY | --hmac-key | (none) | HMAC-SHA256 signing key. If unset, all requests are unauthenticated |
ALLOWED_HOSTS | --allowed-hosts | (empty = allow all) | Comma-separated list of allowed upstream hostnames |
Upstream Fetching
| Variable | CLI Flag | Default | Description |
|---|---|---|---|
FETCH_TIMEOUT_SECS | --fetch-timeout-secs | 10 | Upstream fetch timeout in seconds |
MAX_SOURCE_BYTES | --max-source-bytes | 20971520 (20 MB) | Maximum source image size in bytes |
Cache
| Variable | CLI Flag | Default | Description |
|---|---|---|---|
CACHE_MEMORY_MAX_MB | --cache-memory-max-mb | 256 | L1 in-memory cache size in MB |
CACHE_MEMORY_TTL_SECS | --cache-memory-ttl-secs | 3600 | L1 cache TTL in seconds |
CACHE_DIR | --cache-dir | /tmp/previewproxy | L2 disk cache directory |
CACHE_DISK_TTL_SECS | --cache-disk-ttl-secs | 86400 | L2 disk cache TTL in seconds |
CACHE_DISK_MAX_MB | --cache-disk-max-mb | (empty = unlimited) | L2 disk cache max size in MB |
CACHE_CLEANUP_INTERVAL_SECS | --cache-cleanup-interval-secs | 600 | Cache cleanup interval in seconds |
Video
| Variable | CLI Flag | Default | Description |
|---|---|---|---|
FFMPEG_PATH | --ffmpeg-path | ffmpeg | Path to the ffmpeg binary |
FFPROBE_PATH | --ffprobe-path | (same directory as ffmpeg) | Path to the ffprobe binary |
CORS
| Variable | CLI Flag | Default | Description |
|---|---|---|---|
CORS_ALLOW_ORIGIN | --cors-allow-origin | * | Comma-separated allowed CORS origins |
CORS_MAX_AGE_SECS | --cors-max-age-secs | 600 | CORS preflight max-age in seconds |
Disallow Lists
Use disallow lists to block specific input formats, output formats, or transform operations at the server level. Values are comma-separated.
| Variable | CLI Flag | Default | Allowed values |
|---|---|---|---|
INPUT_DISALLOW_LIST | --input-disallow-list | (empty) | jpeg,png,gif,webp,avif,jxl,bmp,tiff,pdf,psd,video |
OUTPUT_DISALLOW_LIST | --output-disallow-list | (empty) | jpeg,png,gif,webp,avif,jxl,bmp,tiff,ico |
TRANSFORM_DISALLOW_LIST | --transform-disallow-list | (empty) | resize,rotate,flip,grayscale,brightness,contrast,blur,watermark,gif_anim |
Example - block PDF input and prevent format conversion to AVIF:
INPUT_DISALLOW_LIST=pdf
OUTPUT_DISALLOW_LIST=avif
S3 Source
| Variable | CLI Flag | Default | Description |
|---|---|---|---|
S3_ENABLED | (no flag) | false | Enable S3 source |
S3_BUCKET | (no flag) | (required if S3_ENABLED) | S3 bucket name |
S3_REGION | (no flag) | us-east-1 | S3 region |
S3_ACCESS_KEY_ID | (no flag) | (required if S3_ENABLED) | S3 access key ID |
S3_SECRET_ACCESS_KEY | (no flag) | (required if S3_ENABLED) | S3 secret access key |
S3_ENDPOINT | (no flag) | (AWS default) | Custom S3 endpoint URL (for Cloudflare R2, etc.) |
Local Filesystem Source
| Variable | CLI Flag | Default | Description |
|---|---|---|---|
LOCAL_ENABLED | (no flag) | false | Enable local filesystem source |
LOCAL_BASE_DIR | (no flag) | (required if LOCAL_ENABLED) | Base directory for local file serving |
URL Aliases
| Variable | CLI Flag | Default | Description |
|---|---|---|---|
URL_ALIASES | --url-aliases | (empty) | Comma-separated alias definitions in the form name=https://base.url |
Example - define an alias so /assets/... resolves to an S3 base URL:
URL_ALIASES=assets=https://s3.amazonaws.com/my-bucket,cdn=https://cdn.example.com
Production checklist
Before going to production, verify the following:
- Set
HMAC_KEY- without a signing key, any caller can request arbitrary transforms against any URL - Set
ALLOWED_HOSTS- without an allowlist, PreviewProxy can be used to proxy any host on the internet (open proxy) - Set
APP_ENV=production- enables production-appropriate logging and disables development defaults - Tune cache sizes - review
CACHE_MEMORY_MAX_MB,CACHE_DISK_MAX_MB, andCACHE_DISK_TTL_SECSfor your expected traffic and available disk space