Self-Host Kawaii-Player Remotely with Localtonet

Understand the remote-access architecture

Kawaii-Player is an audio and video manager, multimedia player, and portable media server built around mpv and mplayer capabilities. Its project documentation describes SQLite-backed media management, browser access, M3U playlist generation, remote controls, PC-to-PC casting, torrent streaming, and an experimental headless mode. The canonical project information is maintained in the Kawaii-Player repository.

For remote browser access, the important component is Kawaii-Player's built-in HTTP media server. Its documented default address is http://127.0.0.1:9001. The address 127.0.0.1 is IPv4 loopback, so the service can be reached only by software running on the same host unless you deliberately change the listening address.

Localtonet can run on that same host, connect to the loopback service, and establish an outbound connection to one of our relay servers. The resulting HTTP tunnel provides a public HTTPS address without requiring inbound router port forwarding, firewall changes, VPN setup, or a public IP address.

Choose a release and prepare the host

Start by selecting one Kawaii-Player release and using the dependency instructions that belong to it. This matters because Kawaii-Player has crossed a Qt generation boundary. The v8.1.0-1 release page identifies that version as the final PyQt5-based release and says subsequent development will use PyQt6 without continued PyQt5 support.

The current repository README contains separate installation sections, including a PyQt6 section, while the repository itself includes Python packaging metadata such as pyproject.toml and setup.py. Those facts establish that source-based Python packaging is part of the project, but they do not make package names interchangeable across distributions or Qt generations.

Prepare the following before configuring remote access:

• A Linux host that satisfies the dependency instructions for the selected Kawaii-Player revision.
• The matching Python and Qt generation. Do not combine PyQt5 release instructions with current PyQt6 source instructions.
• A supported media backend and the multimedia utilities required by the selected installation path.
• Read access to the intended media directories and write access to Kawaii-Player's own configuration data.
• A graphical desktop for the first configuration run, or Xvfb when following the project's experimental headless workflow.
• A browser for local testing of the media server.
• The Localtonet client on the Kawaii-Player host, or on another private device that can reach the chosen listening address.
• A device-specific Localtonet authentication token obtained from the dashboard.

Choose where the Localtonet client will run

Same-host deployment is the safer default because it allows Kawaii-Player to keep its loopback binding. If Localtonet runs on another device, remember that 127.0.0.1 on that device refers to the Localtonet device itself, not to the Kawaii-Player host.

Install and start Kawaii-Player

Kawaii-Player supports installation from project release material and from its Python source tree. The exact dependency commands are platform-specific and must come from the installation section associated with the selected revision. The available project evidence does not provide a complete, current package list for every supported Linux distribution, so this guide does not substitute guessed apt, dnf, pacman, or Python package commands.

Use one of these supported project paths:

Complete the first run interactively

Start Kawaii-Player using the launcher or executable installed by the selected release procedure. The current captured project documentation confirms normal graphical operation but does not provide one universal executable command for every release asset and installation method. Use the launcher created by that installation rather than assuming that a command from another packaging path is available.

On the first run, verify the application before enabling its HTTP server:

1. Confirm that the main Kawaii-Player interface opens without a Python, Qt, or display error.
2. Add or select the intended local media content.
3. Confirm that the Kawaii-Player account can read representative audio and video files.
4. Play representative files locally so media-backend or codec problems are not mistaken for tunnel failures.
5. Close and reopen the application once to confirm that its configuration remains available.

Kawaii-Player documents ~/.config/kawaii-player/ as its configuration directory for the web administrative password and sessions. Protect that directory with appropriate ownership and permissions. Do not publish it through a file-sharing service, include it in a public repository, or expose it in screenshots.

Configure the Kawaii-Player media server

Kawaii-Player documents the media-server controls in its graphical interface. Configure the listening address, start the server, and set the web password before creating a public tunnel.

Understand the documented routes

Kawaii-Player 7.1.0 added the newer /admin and /browse endpoints. The project also retains legacy browser pages, an M3U endpoint, and a root streaming workflow. These routes share the same HTTP origin when served from the same address and port.

The project states that compatible HTTP-streaming clients such as mpv and VLC can open generated playlists. It also provides these commands for the radio-like root stream when the server uses a private address:

mpv --loop http://192.168.2.2:9001/
mplayer -loop 0 http://192.168.2.2:9001/

Replace the example private address with the address you deliberately configured. These examples describe client playback, not Kawaii-Player installation or startup.

Run the experimental Xvfb workflow carefully

Kawaii-Player's README identifies an experimental headless media-server mode using Xvfb. Xvfb supplies a virtual X display so a graphical application can run on a Linux host without a physical display or normal desktop session.

A complete headless deployment has three process layers:

1. Xvfb or an Xvfb wrapper starts the virtual display.
2. Kawaii-Player starts in that display under the intended unprivileged account.
3. Kawaii-Player's media-server function starts and begins listening on the configured address and port.

The captured current README available for this revision ends immediately after introducing the experimental Xvfb section. It does not include the project's complete Xvfb command, a stable command-line flag for automatically starting the media server, a shutdown command, or a service-manager definition. Supplying a display number or startup flag here would therefore be an invented instruction.

Validated migration sequence

Even when the release provides a complete Xvfb command, move to headless operation only after the graphical setup works:

1. Install the selected release and its matching Qt and media dependencies.
2. Run Kawaii-Player in a normal graphical session.
3. Prepare the media library and test local playback.
4. Configure the media-server address under More > Preferences > Media Server.
5. Start the media server and create the web administrative password.
6. Verify the base URL, /admin, /browse, legacy pages, playlist route, and representative media playback.
7. Stop the application cleanly.
8. Run the release-matched Xvfb sequence from the complete project documentation.
9. Repeat all local HTTP and authentication checks without a physical display.
10. Only after that, add persistence through the host's service manager.

Persistence requirements

No verified service-unit definition is included in the available project documentation, so a universal systemd unit would be inappropriate here. Whatever service manager you use must preserve the following dependency order:

• Media storage must be mounted before Kawaii-Player reads the library.
• The virtual display must be ready before the graphical process connects to it.
• Kawaii-Player must run as the account that owns its configuration.
• The media server must start before Localtonet can successfully forward requests.
• The Localtonet client must remain connected and the tunnel must be running for public access.

Capture standard output and standard error for both Xvfb and Kawaii-Player. Without logs, a missing display, Qt plugin failure, unreadable media directory, or application crash may look like an ordinary tunnel outage.

Verify the complete service locally

Perform same-host checks first when Kawaii-Player is bound to loopback. This isolates application problems from Localtonet configuration.

If the Localtonet client will run on another LAN device, repeat the same tests from that device using the Kawaii-Player host's configured private address. Do not proceed until that exact address and port work from the tunnel client.

Reset the administrative password

Kawaii-Player documents password reset by deleting admin_password.json and admin_sessions.json from ~/.config/kawaii-player/. This removes the stored password and session information so a new password can be created through the web interface.

Stop Kawaii-Player before changing those files. Back up the two files if rollback is required, preserve directory ownership, and do not delete unrelated configuration data. This is a reset procedure, not a way to recover the previous password.

Create the Localtonet HTTP tunnel

Once the Kawaii-Player origin passes local testing, follow the current Localtonet HTTP tunnel documentation. HTTP and File Server tunnels use a Process Type to determine the public HTTPS address. Random Sub Domain, Custom Sub Domain, and Custom Domain all serve the configured target, but availability and domain requirements can vary.

After the documented setup sequence is complete, test the assigned public HTTPS address from a connection outside the server's LAN. Open every route that you tested locally, including unauthenticated legacy or streaming routes. Confirm that /admin and /browse still request credentials and that representative media plays through the public hostname.

Protect the origin before publishing it

A tunnel changes reachability, not Kawaii-Player's authorization model. While the tunnel is active, requests arriving at the public hostname are forwarded to the configured origin. Any route served by that origin may therefore become remotely reachable.

Test without an existing session

Browser sessions can hide security problems. A page that appears protected in one browser may be relying on a cookie obtained earlier. Repeat route checks in a private window or separate browser profile. Test the base path, legacy interfaces, playlist URL, browse page, and administrative page independently.

Do not treat an unlisted path as private

An obscure path is not access control. If legacy pages, playlists, or media streams respond without authentication, assume that anyone who can reach the public hostname may request them. Localtonet does not provide verified path-level filtering in this workflow.

When the application's access controls do not match the intended audience, place a properly configured authentication layer in front of the entire Kawaii-Player origin. Verify that the layer covers every route and media request, including direct playlist and stream URLs, before starting the tunnel.

Keep loopback when possible

With Kawaii-Player and Localtonet on the same host, 127.0.0.1 avoids exposing port 9001 independently to the LAN. Change the listening address only when a separate authorized device needs direct network access.

Protect tokens, sessions, and media

• Never publish the Localtonet device authentication token.
• Redact tokens, private hostnames, account details, media titles, and personal directory names from screenshots.
• Use a unique password for the Kawaii-Player web interface.
• Restrict access to ~/.config/kawaii-player/.
• Grant the Kawaii-Player account only the media and configuration permissions it needs.
• Confirm that remote access to the media complies with applicable rights and policies.

Operate, update, and recover the deployment

Use a consistent startup order

1. Confirm that media storage is mounted and readable.
2. Start the graphical session or the release-matched Xvfb process.
3. Start Kawaii-Player under the account that owns its configuration.
4. Start or confirm the Kawaii-Player media server.
5. Verify the local base URL and an authenticated route.
6. Start or confirm the Localtonet client connection.
7. Start the HTTP tunnel.
8. Test the public address from an external connection.

For planned shutdown, stop the Localtonet tunnel first so new public requests no longer arrive. Then stop the Kawaii-Player media server and application. Stop Xvfb last if it exists only for Kawaii-Player.

Inspect logs by layer

Keep Kawaii-Player, Xvfb, and Localtonet diagnostics separate. If the local URL is unavailable, inspect Kawaii-Player and the display environment. If the local URL works but the public URL does not, check the selected Localtonet device, tunnel state, and target address.

For a persistent headless deployment, configure the service manager to retain process output according to the host's normal logging policy. Review logs after reboot instead of assuming that every dependency restarted successfully.

Update without mixing Qt generations

Before updating, record the installed Kawaii-Player version, Qt generation, installation method, configuration directory, media paths, and current listening address. Back up configuration data while the application is stopped.

Review the target release notes and installation section. The move from v8.1.0-1, identified as the final PyQt5 release, to PyQt6-based development is a dependency migration rather than a routine in-place package replacement. After updating, test graphical startup, local playback, web authentication, every required route, playlist generation, and headless startup before restarting the public tunnel.

Recover in dependency order

After a host reboot or failure, check storage first, then the display environment, Kawaii-Player, the media-server listener, the Localtonet client, and finally the tunnel. This order prevents a downstream symptom from hiding the actual failure.

Troubleshoot each layer separately

Kawaii-Player does not start

Check that the installed Qt generation matches the selected release. Review the application output for missing Python modules, Qt platform-plugin failures, display errors, or unavailable media-backend components. If the problem followed an update, compare the previous and current release instructions instead of adding packages from both generations.

The local URL does not respond

Confirm that Kawaii-Player is still running and that More > Start Media Server was selected. Reopen More > Preferences > Media Server and verify the address and port. Do not change the Localtonet tunnel while the local target is unavailable.

The host works, but another LAN device cannot connect

A service bound to 127.0.0.1 is intentionally unavailable to other devices. If remote LAN access is required, configure an appropriate private address and retest. Check host firewall policy without disabling the firewall broadly.

A separate Localtonet device cannot reach Kawaii-Player

Do not use 127.0.0.1 as the target in this topology. It refers to the Localtonet device itself. Use the Kawaii-Player host's tested private address and confirm that exact URL from the Localtonet device before restarting the tunnel.

The public address is unavailable

Confirm that the selected Localtonet device is connected, the correct AuthToken was selected, and the tunnel was started. Compare the configured local IP and port with the origin that passed local testing. The endpoint is unavailable whenever the selected client disconnects or the tunnel stops.

The page loads, but media does not play

Test the same item through the local URL. If local playback also fails, check file permissions, mounted storage, collection information, and client codec support. The documented root stream does not transcode, so successful HTTP delivery does not guarantee that every browser or player can decode the media.

Authentication appears inconsistent

Test each path in a private browser session. The project explicitly documents authentication for /admin and /browse, not for every legacy and streaming route. If another route responds anonymously, assume it will also be reachable through the public hostname unless a separate access-control layer blocks it.

The administrative password no longer works

Stop Kawaii-Player, then remove admin_password.json and admin_sessions.json from ~/.config/kawaii-player/ as documented by the project. Start the application and create a new password through the web interface. Do not delete unrelated configuration files.

The application fails only under Xvfb

Return to the working graphical startup and confirm the library and HTTP server. Then compare the headless account, configuration directory, display environment, media mounts, and process order. Use the complete Xvfb command documented for the installed revision rather than improvising a display number or startup flag.

The service does not recover after reboot

Check whether storage mounted before startup, whether Xvfb is ready, whether Kawaii-Player runs under the correct account, and whether the media-server listener resumed. Then check the Localtonet client and tunnel separately. A connected tunnel cannot forward to an application that never resumed listening.

Frequently asked questions