rao.pics: browsing an Eagle asset library from any device

A remote window onto an Eagle library

rao.pics exists to solve one problem: you keep a large library of images, videos and other assets in the Eagle application on one machine, and you want to look at them from somewhere else.

The project is described as an Electron app that helps you remotely access the Eagle app's asset library, and the application name and the site are rao.pics. The repository is TypeScript, the licence is AGPL-3.0, and the site for the pages is hosted on Vercel.

The design bet is worth naming. Rather than exposing the library folder over the network and letting a browser list directories, the app builds an index of the library and serves that index, and the library files stay where they are. One of the stated guarantees is that you do not need to worry about file modification, because the metadata is read from the generated index, so it stays safe and intact.

The second bet is that the client does not have to be a desktop app. The default theme is called Gallery, the web build supports PWA so the page can be saved as an app, and the feature list claims support for phones, tablets and PCs, with a waterfall layout and a menu on mobile and light and dark modes on the desktop. The screenshots in the repository show the mobile and desktop views side by side.

For a photographer with several thousand reference shots, that is a coherent product: the library stays on the machine that holds it, and the phone gets a fast gallery instead of a file browser.

Index and sync instead of direct file access

The two technical claims in the feature list are incremental update and real-time sync, and the protection against accidental modification.

The incremental part is the difference between a tool you use and a tool you avoid. A viewer that re-reads and re-indexes the whole library on every open gets slower as the library grows, and on a photography library of tens of thousands of files that is minutes of waiting. The project describes incremental updates and real-time sync as fast, with no long wait.

The index is what makes that possible, and it is also the mechanism behind the safety claim. If the app reads a generated index rather than walking the library and touching files, then the risk of a mis-click modifying a source file disappears by construction, and the metadata the app displays comes from the index rather than from re-parsing the originals.

The index has a cost, though, and it is worth understanding before you commit to the approach. Something has to build it, and it has to be rebuilt when the library changes. The feature list says the app can be deployed on a Windows or macOS server, which suggests the index and the library are expected to be near each other rather than on opposite ends of a network.

The rest of the feature list is presentational, and presentational is not where the difficulty is. There are more than thirty curated colour schemes to switch between with custom themes on top, the app is described as simple to use with a few steps on any device, and there is no separate management software to install.

Downloads, the quarantine flag and an alpha lineage

The README links three downloads from the GitHub releases page, one for Apple silicon macOS, one for Intel macOS and one for Windows, and the site is rao.pics.

For macOS there is a specific instruction. If the app will not open after installation and reports that it is not trusted or is moved to the trash, running the following command and starting it again is the fix:

sudo xattr -d com.apple.quarantine /Applications/Rao\ Pics.app

That is the standard consequence of distributing an app outside the App Store, and the command is a one line removal of the quarantine attribute from the application bundle. It is worth knowing that it is needed before you install rather than after, because an app that silently moves itself to the trash on first launch is a confusing first impression.

The release history is where the caveat lives. The published tags are v1.0.0-alpha.13 from 2024-01-02, v1.0.0-alpha.12 from 2023-12-14 and v1.0.0-alpha.11 from 2023-12-12. So the newest published build is an alpha from the start of 2024, while the last push to the repository was on 2026-10-18.

The code is being worked on, and what you can download is a two and a half year old alpha. That does not mean the application is broken, but it does mean you should expect to check the current state of the repository before you plan around it.

Putting it behind your own domain

The documentation explains how to give the app a custom domain, and the example uses Nginx, which is a sensible choice for a self-hosted service.

The instruction is in two steps. In the app settings you enter the domain you want, for example https://desktop.rao.pics, and then you configure Nginx to forward to it. The configuration in the repository looks like this:

server {
  listen 80;
  server_name desktop.rao.pics;

  location / {
    proxy_pass http://localhost:61121; # App/设置 中的网页端口
    proxy_set_header Host $proxy_host;
    proxy_set_header X-Real-Ip $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }

  location /trpc {
    proxy_pass http://localhost:61122; # App/设置 中的服务端口
    proxy_set_header Host $proxy_host;
    proxy_set_header X-Real-Ip $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Two details in that configuration are the whole integration. The app listens on two local ports, 61121 for the web interface and 61122 for the service, and the service is mounted on a path of its own, /trpc, so the reverse proxy has to route both.

The header handling is the other half. Host, X-Real-Ip and X-Forwarded-For are all forwarded, which means the app sees the original client address rather than the proxy's, and that is what lets an IP based or rate based rule still work when the app is behind Nginx.

The PWA option changes the deployment question slightly. If the library is exposed on a domain, the page can be saved to a home screen on a phone, which removes the need to open a browser and retype the address every time, and the feature list calls that out explicitly as one of the reasons the default theme supports PWA.

An Electron and web monorepo on turbo and pnpm

The repository structure shows how the project is built, and it is a modern TypeScript monorepo.

There are apps and packages directories, a themes directory, tooling, icons, a turbo directory alongside turbo.json, a pnpm workspace with a lock file, a vite.config.ts and a vitest.workspace.ts, and a vercel.json for the pages site. The scripts in the root package manifest drive everything through turbo: build is turbo build, dev runs turbo dev in parallel while filtering out the docs package, typecheck is turbo typecheck, and releases runs pnpm build and then turbo releases filtered to the electron app.

The testing setup is Vitest with coverage enabled through cross-env and NODE_ENV set to development, and there is a test:ui variant. Formatting and linting go through turbo as well, with Prettier and ESLint caches kept inside node_modules.

Two small details in the manifest are worth a mention because they show the project is still moving. The root package is still named create-t3-turbo, which is the name of the template it was scaffolded from, and the tooling versions are from the 2023 to 2024 period, with turbo at 1.x, Vitest at 1.x and pnpm 8.11.0 as the package manager, requiring Node 18.17 or newer.

The environment file shows what the release build needs: Sentry DSN and auth token for error reporting, and the Windows CSC link and key password for the Electron Builder code signing certificates. The release pipeline signs the Windows build, which is why those two variables exist.

AGPL-3.0, plus a commercial licence on top

The licensing section is the part of the project that most affects a decision, and it is a two layer arrangement.

Rao.Pics is described as a free, open source project under the AGPL-3.0 licence, and the licence file is in the repository root. The README then spells out what that permits: if you plan to create an open source application under a licence compatible with GNU GPL v3, you can use the project under the terms of the GPLv3 licence.

On top of that there is an additional agreement for commercial use. If you plan to use the project for commercial purposes, the instruction is to contact the author to buy a commercial licence, so that you have ownership of the source code, and a contact address is given.

That is a stricter position than plain AGPL, and it is worth understanding precisely rather than approximately. AGPL already requires that modifications to a network service be offered to its users under the same terms, so a commercial deployment without publishing the source would be in breach. The additional agreement is a way of selling an exception to that, and the phrase about owning the source code suggests the commercial licence is a grant that goes beyond the copyleft obligations.

This is a note on what the project states, not legal advice, and the practical step for a company is to contact the author before shipping anything commercially.

One more piece of the project page is worth mentioning for context. The author asks for support through the Eagle affiliate programme, and Eagle is the application whose library format this project reads, so the project is explicitly downstream of that ecosystem rather than a general purpose asset server.

Editorial conclusion

rao.pics suits a photographer or designer who keeps a large reference library in Eagle and wants to reach it from a phone while out, or a team that wants to expose an internal asset library on a self-hosted domain. It is the wrong choice if your library does not live in Eagle, because the whole product is built around reading that application's data, and it is the wrong choice for a commercial product you intend to keep closed, because the project is AGPL-3.0 and the author asks commercial users to buy a commercial licence. Verify three things before you rely on it: that the library format on your machine is the one this build reads, that the macOS quarantine workaround is acceptable in your environment, and that the version you install matches the Eagle version you use, since the newest published tags are alpha builds from January 2024.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. meetqy/rao-pics on GitHub
3. Project website
4. README
5. Releases