Configuration - API - Troubleshooting - License

AIOFiles is a self-hosted media toolkit for downloading videos, converting and compressing files, and processing images.
It runs as a web app backed by background workers, stores its data on disk, and exposes the same functionality through an HTTP API.

Quick Start

The fastest way to run AIOFiles is with Docker Compose:

1. Copy .env.example to .env.
2. Get docker-compose.yml
3. Set PUID and PGID to match your host user if you want the files in ./data to be owned by you.
4. Set AUTH_USERNAME and either AUTH_PASSWORD_HASH or AUTH_PASSWORD if you want login enabled.
5. Start the stack with docker compose up -d.
6. Open http://localhost:1144.

To generate a password hash:

docker compose run --rm --entrypoint aiofiles aiofiles -hash-password 'your password'

What It Does

• Downloads media with yt-dlp.
• Converts and compresses files with ffmpeg.
• Processes images with ImageMagick.
• Queues work, tracks progress, and streams updates over SSE.
• Persists jobs, uploads, and sessions in SQLite.

Everything is driven by environment variables. The defaults and the rules that are easy to miss are documented here:

• Configuration
• .env.example
• docker-compose.yml

Information

• The app stores persistent data under ./data by default.
• Authentication is optional, but when it is enabled you need both a username and a password hash.
• Behind a reverse proxy, set TRUSTED_PROXIES so login rate limiting and Secure cookies see the real client. ALLOWED_HOSTS and PROXY_ONLY=1 restrict the instance to the name your proxy answers to, so http://<lan-ip>:1144 stops working while https://aio.example.com keeps working.
• Large uploads, retention, and worker concurrency are all controlled through environment variables rather than a settings screen.