Reference

Environment variables

Variable	Default	Purpose
TRALHA_PORT	8000	Private port
TRALHA_PUBLIC_PORT	8001	Public port
TRALHA_HOST	0.0.0.0	Address both ports listen on
TRALHA_API_URL	http://localhost:<port>	Base URL for upload URLs given to agents; https here makes panel cookies Secure
TRALHA_PUBLIC_URL	http://localhost:<public port>	Base URL for public links
TRALHA_DATA_DIR	./data	Blobs, temporary files, thumbnails and the SQLite database
TRALHA_DATABASE_URL	SQLite in the data dir	Or postgresql+psycopg://user:pass@host/db
TRALHA_MAX_UPLOAD_MB	25	Largest single file
TRALHA_UPLOAD_TTL	600	Seconds an upload URL stays valid
TRALHA_GC_INTERVAL	3600	Seconds between cleanup runs
TRALHA_FORWARDED_ALLOW_IPS	127.0.0.1	Addresses or networks trusted for X-Forwarded-*
TRALHA_ADMIN_ALLOWED_IPS	empty	Addresses or networks allowed to open /admin; empty allows all
TRALHA_API_DOCS	off	Serve OpenAPI docs at /api/docs
TRALHA_API_DOMAIN, TRALHA_FILES_DOMAIN	none	Domains for the bundled Caddy

System settings that change at runtime, without a restart, live in the database instead: compression (off, lossless, lossy), compression_quality (1 to 100) and keep_original.

CLI

The CLI talks to the database directly, so it needs the same environment as the server. In Docker, prefix commands with docker compose exec tralha.

Command	Does
tralha serve [--host] [--port] [--public-port]	Starts both ports
tralha key create NAME --scope S [--scope S…] [--expires 90d]	Creates a key and prints it once
tralha key list	Lists keys with status, last use and last IP
tralha key revoke ID	Revokes a key
tralha bucket create NAME [--public] [--ttl 7d] [--max-size 2GB] [--on-full evict-oldest] [--compression lossless]	Creates a bucket
tralha bucket list	Lists buckets, usage and rules
tralha bucket set NAME [--public/--no-public] [--max-size 0] [--on-full …] [--compression inherit]	Changes a bucket; --max-size 0 removes the quota
tralha rule add BUCKET --expire 7d [--prefix tmp/] [--basis last-access] [--keep-shared]	Adds a cleanup rule
tralha rule rm ID	Removes a rule
tralha settings [name=value …]	Shows or changes system settings
tralha gc [--dry-run]	Runs cleanup now, or lists what it would delete

Durations accept s, m, h and d; sizes accept KB, MB and GB.

REST API

All /api routes need Authorization: Bearer <key> and live on the private port. Request and response bodies are JSON unless noted.

Method and path	Does	Scope
GET /api/buckets	Lists readable buckets	read
POST /api/buckets	Creates a bucket: name, visibility, expire_after, max_bytes, on_full, compression	admin
PATCH /api/buckets/{bucket}	Changes bucket settings	admin
DELETE /api/buckets/{bucket}	Deletes an empty bucket	admin
POST /api/buckets/{bucket}/rules	Adds a rule: expire_after, prefix, basis, keep_shared	admin
DELETE /api/rules/{id}	Removes a rule	admin
GET /api/buckets/{bucket}/objects?prefix=&delimiter=/&limit=	Lists objects and folder prefixes	read
PUT /api/buckets/{bucket}/objects/{key}?ttl=	Uploads raw bytes; optional X-Tralha-Metadata JSON header	write
GET /api/buckets/{bucket}/objects/{key}[?original=1]	Downloads an object or its kept original	read
DELETE /api/buckets/{bucket}/objects/{key}	Deletes an object and its links	delete
POST /api/buckets/{bucket}/shares	Creates a link: key, expires_in	share
DELETE /api/shares/{token}	Revokes a link	share
POST /api/buckets/{bucket}/uploads	Creates an upload URL: key, ttl	write
GET /api/search?q=&bucket=&limit=	Full-text search	read
GET /api/settings, PATCH /api/settings	Reads or changes system settings	admin
GET /api/cleanup	Lists what the next cleanup would delete	admin
PUT /upload/{token}	Sends the file for an upload URL; no key needed	token

Public port:

Method and path	Does
GET /p/{token}	Serves a linked object; markdown is rendered unless ?raw=1
GET /b/{bucket}/{key}	Serves an object from a public-read bucket
GET /healthz	Returns {"ok": true}

Errors return {"detail": "…"} with 400, 401, 403, 404, 409, 413, 422 or 429.