ConvertX: A Self-Hosted Converter That Wraps Twenty CLI Tools Behind One API

What ConvertX Actually Solves

The project is written in TypeScript and runs on Bun with the Elysia framework, which is a modern stack but also a signal that the project is young and may have a smaller ecosystem than a Node.js or Python alternative. The core value is the aggregation: instead of installing and scripting fifteen separate tools, you get one container that exposes them all. That is the problem it solves, and it solves it well for a single-user or small-team scenario.

The Converter Stack: Twenty Tools, One Container

The README lists twenty converters, each with a table of input and output counts. The counts are indicative, not exhaustive: FFmpeg alone is listed as converting from about 472 formats to about 199, and the note says many FFmpeg file formats are duplicates. That means the actual format coverage is less than the sum of the numbers, but the range is still broad. The tool selection reveals design choices: Inkscape and dvisvgm handle vector images, libjxl and libheif cover modern image codecs, Calibre manages e-books, and LibreOffice and Pandoc cover documents. There is also Assimp for 3D assets, which is an unusual inclusion and shows the author aimed for breadth. The use of Dasel for data files (like JSON to YAML) and a VCF to CSV converter for contacts shows attention to non-media formats. The key point is that ConvertX does not implement any conversion logic itself; it orchestrates external binaries. This means the quality of output depends on the underlying tools, and the format coverage is only as good as those tools' support. For example, converting a complex PDF to DOCX via LibreOffice will inherit LibreOffice's rendering fidelity, which can be imperfect. The README does not describe any pre-processing or post-processing beyond passing files to these tools, so users should expect raw tool behavior.

Deployment: Docker First, with a Security Warning

The primary deployment method is Docker Compose. The README provides a minimal docker-compose.yml that pulls the image ghcr.io/c4illin/convertx, maps port 3000, and mounts a data volume to /app/data. The environment variables are all optional, but JWT_SECRET is recommended. If unset, the server generates a random UUID, which means tokens will invalidate on restart, breaking sessions. The warning about login is explicit: if you cannot log in, ensure you are accessing over localhost or HTTPS, or set HTTP_ALLOWED=true. That is a realistic constraint: the server refuses to issue tokens over plain HTTP except on localhost. For a home server behind a reverse proxy, you will need to either configure HTTPS or set that flag. The README also warns about first account registration: anyone can register the first account if the server is open, so you should deploy it and create your account immediately. There is also a note about database file permissions: if you get 'unable to open database file', run chown -R $USER:$USER on the volume path. These details are practical and show that the project expects a technically comfortable user. The environment variables include ACCOUNT_REGISTRATION (default false), which means by default new users cannot sign up after the first account, and ALLOW_UNAUTHENTICATED (default false), which locks the service down. That is a sensible default for a private tool.

Configuration and Customization: FFmpeg Args and Webroot

Beyond the basic variables, ConvertX exposes two FFmpeg-related knobs: FFMPEG_ARGS and FFMPEG_OUTPUT_ARGS. These let you pass extra arguments to the input and output of FFmpeg, such as -hwaccel vaapi for hardware acceleration or -preset veryfast for speed. The README links to an issue about hardware acceleration, which suggests that GPU-accelerated conversion is not a built-in feature but can be enabled by setting these variables. That is a significant limitation: without these arguments, video conversion may be CPU-bound and slow. The WEBROOT variable allows serving the app under a subpath like /convert, which is useful behind a reverse proxy that already serves other apps. HIDE_HISTORY hides the history page, which is a privacy feature for shared servers. The configuration surface is small, which is good for simplicity but also means you cannot fine-tune each converter individually. For example, there is no variable to set the DPI for ImageMagick or the profile for Calibre. You get the defaults, and if you need different behavior, you must either modify the container or run the underlying tools separately. That is a trade-off: the aggregation saves setup time but limits control.

Limitations and Failure Modes

The most obvious limitation is that ConvertX is a web service, not a batch processing tool. You upload files through a browser or an HTTP client, and the server processes them. If you need to convert thousands of files in a pipeline, this is not the right tool; you would be better off calling FFmpeg or Pandoc directly. The README does not mention a CLI or an API token for programmatic access, so automation may require reverse-engineering the web endpoints. The auto-delete feature is another potential failure mode: AUTO_DELETE_EVERY_N_HOURS defaults to 24, meaning files older than 24 hours are deleted. If you convert a file and do not download the result within a day, it is gone. The README says set to 0 to disable, but if you forget, you lose data. The account system is minimal: multiple accounts are supported, but there is no mention of roles, quotas, or per-user rate limiting. For a shared deployment, one user could upload a huge video and consume all disk space. The README does not discuss resource limits. The license, AGPL-3.0, is a real constraint for commercial use: if you modify the code and offer it as a network service, you must provide the source to users. That is a common choice for self-hosted apps, but it may be a dealbreaker for companies that want to embed ConvertX in a proprietary product.

Alternatives: What Else Is Out There

The most direct alternative is to use the underlying tools directly, such as FFmpeg, ImageMagick, and LibreOffice, and script them with a simple web framework. That gives you full control over each converter's arguments and avoids the AGPL license, but it requires significant setup and maintenance. Another alternative is a commercial API like CloudConvert, which offers a REST API and handles scaling, but you lose the self-hosted aspect and pay per conversion. For a self-hosted option with a similar approach, there is the open-source project 'FileConverter' or 'Converter' apps on GitHub, but ConvertX's breadth is notable. The key difference is that ConvertX bundles all tools into one Docker image, so you do not need to install dependencies. A more comparable project might be 'LibreOffice Online' for document conversions, but that is focused on office formats. For video, you could use 'FFmpeg.wasm' in a browser, but that is client-side and not suitable for large files. The practical choice is between ConvertX and a scripted solution: if you need a quick, deployable service, ConvertX wins; if you need custom logic or have unusual formats, you will hit its limits.

Maintenance and Upgrade Considerations

The project is actively maintained, with releases in June 2026, January 2026, and December 2025, indicating a steady cadence. The Docker image is published to GitHub Container Registry and Docker Hub, so updates are as simple as pulling a new image. However, the README does not mention a migration path for the data directory or database schema changes. Since the data volume stores files and likely a database, you should back it up before upgrading. The use of Bun and Elysia is a maintenance consideration: these are less established than Node.js and Express, so finding developers or documentation may be harder. The AGPL license also has implications for upgrades: if you modify the code, you must share those modifications if you run it as a service. The README encourages opening issues or pull requests for missing converters, which is a sign of an open contribution model. For a production deployment, you will need to monitor disk usage and the auto-delete behavior, and you should test the FFmpeg hardware acceleration settings if you plan to handle large videos. The project is not a turnkey enterprise solution; it is a solid tool for a technical user who understands the underlying converters.

Editorial conclusion

Adopt ConvertX if you need a self-hosted conversion service with a web UI and an API-like interface, especially if you already run Docker and want to avoid per-file cloud uploads. Do not use it if you require fine-grained per-converter control, a mature multi-tenant user system, or a permissive license, because the AGPL-3.0 and the all-in-one container may conflict with your distribution model. Before deploying, verify that your expected formats are covered by the listed converters, set JWT_SECRET, and decide on ACCOUNT_REGISTRATION and ALLOW_UNAUTHENTICATED based on who will access it. Also test the AUTO_DELETE_EVERY_N_HOURS setting to ensure your workflow tolerates automatic file removal.

Official sources

1. Official README
2. Project repository
3. Release notes