Ikaros: a self-hosted platform for a personal media library

What Ikaros sets out to be

Ikaros describes itself in the README as a self-hosted personal digital content platform, and the repository description says the project is dedicated to ACGMN's content management system. The topic tags reinforce the same focus: acgmn, acgn, bangumi, music and cms. This is a media library for one person's collection, not a general purpose publishing platform.

The feature list is short and worth reading closely, because each entry describes a design commitment rather than a long checklist. The first is unified resource management, the idea that all resources are handled by one platform instead of being scattered across separate tools. The second is metadata support, aimed at the case where a pile of resources is nothing but transliterated titles that identify nothing. The third is search, and here the README makes a specific claim: even with several hundred thousand resources it promises millisecond level search responses. That is the project's own statement, and the README offers no benchmark or measurement behind it.

The fourth and fifth entries define the shape of the system. Plugins carry the additional functionality, because the core is only intended to provide the most basic features, and the client list covers mainstream platforms including Windows and Android.

The disclaimer section sets the intended use even more tightly. The project says the program exists to help individuals manage their resources, that it is similar to a client and server file manager, that it is for personal use only, and that exposing it to the public internet is not advised.

The architecture is visible in the directory names

The top level of the repository is the most honest description of the system available, and it is unusual. Instead of a handful of packages, the tree contains a large set of Maven modules that are named after the kinds of content they handle: music, photo, reading, media, drive, document, game, finance, planning, private-notes, password-manager, backup, sharing, sync, ingestion, search, plugin, console, application, common and asset directories.

Many of those come in a pair. common-api, media-api, resource-api, storage-api, sync-api, operations-api, integration-api, authentication-api and authorization-api all sit beside an implementation directory of the same name. Separating the contract from the implementation is what allows a client on Android or Windows to talk to the server without pulling in server side code, and it is the reason the tree contains so many api directories. The media oriented modules are less consistent about it, with music, photo, reading and game appearing as single directories.

The build itself is Maven. There is a pom.xml at the root, a .mvn-local-settings.xml for local repository configuration, and a .run directory that holds IDE run configurations, which is the kind of detail that tells you a developer is expected to work on this in an IntelliJ based environment rather than only through a packaged distribution. BUILD.md and CHANGELOG.md sit at the top level next to CONTRIBUTING.md, AGENTS.md, SECURITY.md and a docs directory, and the CI workflow file is named ikaros-server-ci.yml, which indicates the server side is the part the pipeline builds and tests.

Why the plugin model and the client apps carry the weight

The division of labour the README describes is unusual and deliberate. The core is only meant to provide the most basic functions, and everything else comes from plugins. For a project at this stage of development, that is a defensible choice: it lets the core stay small and stable while the parts that change often live in extensions.

It also transfers work to the adopter. A plugin written outside the core development team is, in the project's own words, not the responsibility of the development team, and the disclaimer repeats the point that user behaviour relates to the user rather than to the program. Anyone adopting Ikaros is therefore signing up for reading plugin code and maintaining it themselves.

The client side is the other half. The README claims clients for the mainstream platforms, and names Windows and Android explicitly, so a phone or a laptop is the expected way to reach the library rather than only a web page. The Docker Hub image under the ikarosrun namespace and the coverage badge linked from Codecov point to a server that is built, measured and packaged as a service, with the clients as separate pieces that talk to it.

Taken together, the model is: a Java server holding a unified catalogue, plugins adding capability, and native clients for consuming it. A reader who wants a web app to share with other people is looking at a different product than the one described here.

Getting a running Ikaros: the README hands you off to the docs

This is where the project's own documentation does less work than a reader would hope. The README does not contain a single installation command, a configuration file sample, a database requirement or a start command. What it gives you is a pointer to the hosted documentation at docs.ikaros.run, a link to a quick project board on GitHub, and a link to the open issue board, plus the CHANGELOG and CONTRIBUTING files in the repository.

That is a deliberate division of labour rather than an oversight, and it is common in projects with a separate docs repository, which this one has, since a docs directory is present at the top level alongside the linked documentation site. The consequence for an adopter is simple: the README will not get you a running instance, and the documentation site is the actual source for deployment steps.

Two artefacts make that hand off workable. The first is the Docker image published under ikarosrun/ikaros, which means you can obtain a packaged server without building the Maven tree yourself, and a continuous integration workflow named ikaros-server-ci.yml shows the server build is exercised on every change. The second is the .run directory of IDE run configurations, which tells a developer exactly which module and profile to launch when working from source.

If you are evaluating the project, open docs.ikaros.run first and read the deployment pages, then come back to the repository for the module layout. The reverse order leads to a directory listing of forty modules and no idea what to do with them.

Beta 2 of the 2.0 line is the current state of play

The release history shows a project in a transition. Version v1.2.5 was published on 2026-08-22, then v2.0.0-beta-1 on 2026-09-16, and v2.0.0-beta-2 on 2026-10-02. The last push to the default branch was on 2026-10-02, the same day as the second beta, and the repository is not archived, so work is ongoing on the main line.

Two beta builds two weeks apart is a fast start to a major version. It suggests that the 2.0 line is being shaped in public, and the tag naming makes the status unambiguous: these are pre-releases, not a stable 2.0. If you deploy the beta, the tag can move to a new beta under you, and the 2.0 API surface may still shift between beta-1 and beta-2.

The CHANGELOG.md file in the repository is where a serious evaluation should start, precisely because the README carries no release notes of its own. For a 1.x to 2.0 move, the interesting questions are whether the storage and resource modules changed shape, whether plugin interfaces moved with them, and whether the 1.2.5 install path still works for a short term. The README does not answer any of these, and the release notes are the place to look.

One small oddity in the module list is worth a second look if your interests are broad: the tree includes finance, planning and password-manager directories alongside the media ones, which suggests a broader personal data platform was intended even though the current description centres on ACGMN content.

Where Ikaros is the wrong choice

The project states its own limits, and they are not small.

It is for personal use, and the README advises against exposing it to the public internet. A shared or multi user deployment, a service offered to paying customers, or anything that puts a login form on the open web falls outside what the project claims to support. The security file and the SECURITY.md file exist, but a project that disclaims public exposure has not made the threat model of an internet facing service its priority.

The beta status is the second limit. Two pre-releases of a major version means the schema, the plugin API and the client protocol are all plausibly in motion. Anyone who needs a stable installation with a predictable upgrade path should stay on the 1.2.5 line, if that line is still maintained, and read the changelog before moving.

The third limit is the scope of what the core does. The core deliberately provides only the most basic functions, so the feature set you see on day one is small unless you also find or write plugins. A user who expects a complete media manager out of the box will be disappointed, and the metadata and search claims depend partly on plugins to be useful at scale.

Finally, the search promise is unverified. The README says milliseconds across several hundred thousand resources, which is the sort of number that depends on the database, the index configuration and the query. The documentation site is where any detail on that would live, and the README gives no measurement.

AGPL-3.0 and what it means for a self-hosted tool

Ikaros is licensed under AGPL-v3.0, and the README states plainly that the project is open sourced under that licence and asks users to comply with it. The repository root holds the LICENSE file and a SECURITY.md file alongside a CONTRIBUTING guide.

The practical point about AGPL for a self-hosted piece of software is the network clause, and I am not offering legal advice on how it applies to your situation. What it means in practice for an adopter is that the licence is the strictest of the common open source licences, so any modification you distribute, and any modified version you make available to other users over a network, comes with the same obligation to publish the corresponding source. For a private installation used only by you or your own team, the obligations are not triggered by ordinary use.

That is a different position from a permissive licence such as MIT or Apache, where a company can fork the code, close it, and ship it inside a product without publishing changes. If Ikaros is one component of a product you intend to distribute, the licence choice needs legal review before anything else. If it is a personal tool on your own machine, the choice is a smaller question.

The choice also shapes the plugin story. Because the core is AGPL and plugins are the main extension path, a business that wants to build proprietary plugins on top of Ikaros has a compatibility question to answer, and the project disclaims responsibility for third party plugins, which is a statement about support rather than about licensing.

How Ikaros compares to a plain file manager over a share

The disclaimer says it plainly: Ikaros is a client and server file manager for a person, with more around it. So the honest comparison is with the obvious alternative, a shared folder reachable from a phone and a laptop over your own network, backed by whatever file browser the platform provides.

The difference is metadata and search. A share gives you files named after whatever you named them, and the transliterated title problem the README describes is exactly what happens when a media collection has no structured naming. Ikaros stores metadata as a first class idea and makes the collection searchable, and it claims that search stays fast at a scale where a file listing is no longer usable. Against that, a share has none of the operational surface: no server to run, no database to migrate, no plugin interface to understand, and no version to track.

The other half of the difference is the client story. Ikaros ships dedicated clients for mainstream platforms, Windows and Android among them, so a phone is a first class way to browse and play the collection rather than a file browser pointed at a share. If your collection is media that you want to browse on a phone with proper metadata, that is the argument for it. If you need to move a folder of files to a colleague's machine, a share is faster and there is nothing to install.

For a single curator, the decision is simple enough. Ikaros is worth the setup cost when the collection is large enough that search and metadata change how you use it, and it is overkill when the library is small enough to remember.

Editorial conclusion

Ikaros fits a single user or a small group who wants to catalogue a personal ACGMN media library on their own hardware, with metadata, search and client access, and who is comfortable running a Java service and a database of their own. It does not fit a multi tenant service, a public facing site, or a team that needs a permissive licence, because the project states it is meant for personal use, discourages exposing it to the public internet, and is licensed under AGPL-3.0. Before adopting, read the documentation at docs.ikaros.run for the deployment steps the README omits, check the 2.0 beta release notes for breaking changes, and confirm the plugin interface is stable enough for the extensions you intend to write.

Frequently asked questions

Official sources

1. ikaros-dev/ikaros on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases