ClearML Server: self-hosting the backend for ClearML experiment tracking

The problem ClearML Server solves: keeping experiment data on your own machines

ClearML, the client library, logs experiments, statistics and results. Those records need somewhere to go. The README states that ClearML offers a free hosted service at app.clear.ml, maintained by ClearML and open to anyone. ClearML Server is the alternative for teams that cannot or will not send that data to a third party: it is the backend service infrastructure for ClearML, and the README describes its purpose as allowing multiple users to collaborate and manage their experiments. The audience is therefore narrow and specific. It is not individual researchers trying out tracking for the first time; the hosted service covers that. It is platform or infrastructure engineers who have been told that run metadata, logged images and model files must stay inside a private network, and who are prepared to run the storage and query layer themselves. A useful side effect of self-hosting is that the same server becomes the collaboration point for a group: every user points their local ClearML client at one address, and the web app becomes the shared view of what has been run.

Three services, two supported topologies, and the ports they occupy

ClearML Server is not a single process. The README lists three components: a single-page web app for experiment management and browsing, a RESTful API for logging and querying experiment information, statistics, results and logs, and a locally hosted file server that stores images and models so the web app can serve them. The README documents two supported configurations. In the single IP configuration the web application listens on 8080, the API service on 8008 and the file storage service on 8081. In the sub-domain configuration the three services sit behind default HTTP or HTTPS ports (80 or 443) on app.*, api.* and files.* sub-domains. That choice is not cosmetic: it determines what you write into the client configuration later. The README also notes that as of version 0.15 the dockerized deployment includes a ClearML-Agent Services container. That container is an extension of ClearML-Agent which spins any task enqueued into a dedicated services queue, registering each launched task as a new node in the system. The README is explicit that it is the user's responsibility to make sure the proper tasks are pushed into that queue, and warns against enqueueing training or inference tasks there because it puts unnecessary load on the server. Treat that queue as infrastructure, not as a general worker pool.

Getting it running: deployment paths, port checks and the client config keys

Before launching anything, the README requires that ports 8080, 8081 and 8008 be available. It gives two checks. On Linux or macOS, sudo lsof -Pn -i4 | grep :8080 | grep LISTEN. On Windows, netstat -an |find /i "8080". Deployment itself is offered in several forms: a pre-built AWS EC2 AMI, a pre-built GCP custom image, pre-built Docker images for Linux, macOS and Windows 10, and Kubernetes either through a Helm chart or a manual installation. Once the server is up, the client side is configured either by running clearml-init for an interactive setup or by editing ~/clearml.conf directly. The README gives the manual form with three keys inside an api block: api_server set to http://localhost:8008, web_server to http://localhost:8080 and files_server to http://localhost:8081. It adds a note that in a sub-domain configuration no port number is needed, because the port is inferred from the http or https scheme. That is the whole connection story: the client writes to the API server, the browser opens the web server, and model and image files resolve through the file server. Restarting is a two-step operation the README spells out: docker-compose down, then docker-compose -f docker-compose.yml up.

The services queue is a footgun, and the README says so

Most self-hosted tooling hides its sharp edges in an FAQ. ClearML Server puts one in the main README. The ClearML-Agent Services container will spin any task enqueued into the services queue, and the README's note is blunt: do not enqueue training or inference tasks into the services queue, as it will put unnecessary load on the server. This matters because the queue accepts anything. There is no filtering described in the material, only a documented convention that users must respect. In a shared deployment, one person enqueueing a training job into the wrong queue is enough to load the server with work that was meant for a worker. If you deploy the dockerized stack, decide before the first day who can write to that queue, and consider whether the services container should be part of your deployment at all if you have no long-running jobs. The README lists the intended uses: an auto-scaler that spins instances when need and budget allow, controllers implementing pipelines, optimizers for hyperparameter search, and applications such as interactive Bokeh apps.

What the README does not cover, and where the licence picture is unclear

Two advanced features are mentioned but not explained in the README: web login authentication and a non-responsive experiments watchdog. Both are described as manually enabled, and both link out to a server configuration page. That means a default deployment is not necessarily authenticated, and you should read that configuration page before exposing the web app beyond a trusted network. The material also does not state which database or storage backends the components use, what resource requirements a server needs, or how large a deployment the single-IP topology can carry. The upgrading section is truncated in the supplied text, though it does say that releases are reflected in the docker compose configuration file and that the project encourages keeping the server current. On licensing, the two signals conflict: the repository metadata reports NOASSERTION, while the README badge and link say SSPL. This is not a detail to skim past, because SSPL is not a permissive licence and its obligations differ substantially from MIT or Apache-2.0. Read the actual licence file in the repository before you build a product around this server. Nothing here is legal advice, and the discrepancy is exactly the kind of thing that should be resolved by the licence text rather than by a badge.

Compared with MLflow: one server with a UI and file store versus a tracking library you host yourself

The obvious alternative for a team that wants experiment tracking on its own hardware is MLflow, whose tracking server and artifact store are the closest functional match. The difference in approach is packaging. ClearML Server arrives as a defined stack: a web app, an API and a file server, with documented ports, Docker images, Kubernetes manifests and cloud images, plus the ClearML-Agent Services container for long-running jobs. MLflow's tracking server is a smaller component that you typically place behind your own artifact storage and database, which gives you more freedom in how storage is arranged and less out-of-the-box UI and queue behaviour. The trade is control against assembly. If you want a single deployment that already includes the model and image store, the web UI and a services queue, ClearML Server removes that assembly work. If you already have a storage and database convention you must follow, or you only need run and metric logging, the smaller server is easier to reason about. What you cannot get from the README is a comparison of resource usage or throughput between the two, so treat any such claim, including from this article, as unverified.

Upgrade and maintenance cost of running your own ClearML Server

Self-hosting moves the operational burden onto you, and the material is clear about the shape of that burden. Releases are reflected in the Docker Compose configuration file, which means an upgrade involves changing that file and recreating containers. The README states the project strongly encourages keeping the server up to date with the current release. The release cadence visible in the repository is roughly every four months, with v2.4.0 in March 2026, v2.3.0 in November 2025 and v2.2.0 in July 2025, so the upgrade work arrives a few times a year rather than continuously. Restarts are not graceful in the sense of a single command: the documented procedure stops the containers with docker-compose down and then brings them back with docker-compose -f docker-compose.yml up, which means downtime unless you have arranged otherwise. That, plus the licence question, is the real cost of this path. A team that cannot schedule a short maintenance window, or that has no one who will edit the compose file and read release notes, will get more value from the hosted service than from a server they deploy once and forget.

Editorial conclusion

Adopt ClearML Server if experiment metadata, images and models must live on infrastructure you control, and you are willing to run the web app, API and file server as separate services on ports 8080, 8008 and 8081. Do not adopt it if a hosted service is acceptable, or if nobody on the team will own upgrades. Verify first that those three ports are free, that your chosen deployment path (Docker, Kubernetes, EC2 AMI or GCP image) matches the configuration you want, and read the licence text yourself because the repository reports NOASSERTION while the README badge says SSPL.

Official sources

1. clearml/clearml-server on GitHub
2. Issues
3. Project website
4. README
5. Releases