Build a browser-based 3D video store, verify it locally, and then make the working web interface available outside your LAN
Halcyon Video turns a Jellyfin or Plex library into a walkable video rental store rendered in the browser. This guide takes an installation-first approach: prepare the media-server connection, deploy Halcyon Video with its documented Docker Compose workflow, connect a library, and verify the application locally. After the local service works, we explain how to publish its web endpoint through a Localtonet HTTP tunnel. Exact ports and container parameters must come from the current Halcyon Video quick-start documentation because they are not fixed by the evidence available for this draft.
What Halcyon Video is and how the deployment fits together
Halcyon Video is a self-hosted, browser-based frontend that presents a media library as a three-dimensional video rental store. Instead of navigating a conventional poster grid, viewers can walk through aisles, inspect cases, browse sections, and use a themed living-room experience. The project is built with Vite, TypeScript, and three.js, with an optional Tauri wrapper for application-style deployments.
Halcyon Video is not itself a general-purpose media scanner. Shelving your own media files requires a supported library provider, specifically Jellyfin or Plex in the supplied project documentation. The application obtains catalog information and artwork through that connection, then constructs the store experience in the browser. A synthetic demo catalog is available for testing the interface without a media server, but that demonstration does not replace a Jellyfin or Plex connection when the goal is to browse your own collection.
This distinction affects the correct installation order. Jellyfin or Plex should already be running and reachable from the system or browser that will use Halcyon Video. Halcyon Video is then deployed as its own web application and configured to communicate with the selected media server. Only after both pieces work locally should remote access be introduced.
Prerequisites and decisions to make before installation
Begin with a working Jellyfin or Plex deployment if you plan to use your own library. For Jellyfin, have the server address and the user credentials needed for the intended account. For Plex, Halcyon Video documents a plex.tv authorization-code flow that displays available servers after authorization. Do not place passwords, authentication tokens, or private server details in shell history, screenshots, public issue reports, or tunnel descriptions.
You also need a host capable of running the selected Halcyon Video deployment method. This tutorial focuses on Docker Compose because the project explicitly documents starting a cloned repository with docker compose up -d. Docker and the Docker Compose functionality must therefore be installed and operational on the host. The supplied project evidence mentions npm and an HTPC kiosk option, but it does not provide their complete procedures, so this article does not invent those commands.
Check the complete current Halcyon Video quick-start instructions before deployment. In particular, obtain the authoritative repository acquisition procedure, Compose configuration, exposed local port, supported overrides, and any required environment settings from the project documentation. The extracted evidence confirms that a docker-compose.yml file exists, but it does not establish the port, local hostname, volume mappings, environment variables, or the full standalone docker run command.
A Localtonet HTTP tunnel needs the actual local IP address and port where Halcyon Video is listening. Copy those values from the current Halcyon Video quick start, its Compose file, or the verified container output. Substituting a common development port or an assumed Docker mapping can expose the wrong service or produce a tunnel that cannot connect.
Install Halcyon Video with Docker Compose
The following process deliberately separates confirmed instructions from details that must be checked in the current project documentation. That keeps the deployment reproducible without presenting assumptions as defaults.
Prepare Jellyfin or Plex
Confirm that the chosen media server is running and that its normal web interface is reachable. For Jellyfin, prepare the server address and an appropriately scoped user account. For Plex, be ready to complete the documented plex.tv code authorization flow. Halcyon Video needs one of these providers to shelve your own media.
Install and verify Docker
Install Docker with Docker Compose support using the instructions appropriate to the host operating system. Verify that Docker can start containers before continuing. The exact Docker installation procedure is platform-specific and is not defined by the supplied Halcyon Video evidence.
Obtain the Halcyon Video repository
Follow the current official project quick start to clone or otherwise obtain the repository, then enter the repository directory containing docker-compose.yml. Use the project’s documented branch or release guidance rather than guessing a repository command or automatically assuming that a particular tag is appropriate.
Review the Compose configuration
Read the supplied Compose file and current quick-start notes before starting the service. Record the published local port and review any documented environment settings, storage mappings, or upgrade requirements. Do not add unverified variables or volume paths merely because another Vite or Docker application uses them.
Start the deployment
From the cloned repository directory, run the Docker Compose command documented by the project:
docker compose up -dThe detached mode returns control to the terminal while the Compose deployment continues running. Use Docker’s normal inspection facilities and the project documentation to determine whether the service started successfully.
Open the verified local endpoint
Open the hostname and HTTP port established by the current Compose configuration. Test from the host first, then from another device on the LAN if LAN access is part of the intended deployment. Do not proceed to tunneling until the Halcyon Video interface loads reliably at this local address.
Halcyon Video provides a synthetic demo store that works without a media server. It can help confirm that a browser can load and render the interface, but it does not verify connectivity to your Jellyfin or Plex server. The project notes that the full demo can use several gigabytes of memory and meaningful GPU resources, so a plugged-in and graphics-capable system is preferable for testing.
Connect Halcyon Video to Jellyfin or Plex
After the web interface loads, use the application’s HTPC Connection Center to configure the primary media provider. The visible connection workflow distinguishes Jellyfin from Plex, so follow the branch that matches your server rather than trying to reuse one provider’s authentication method for the other.
Connect Jellyfin
Select Jellyfin as the server type, enter the server address, and provide the username and password for the account intended to use the store. Confirm that the address is reachable from the relevant runtime context. If Halcyon Video or the browser cannot reach that address, the public tunnel will not repair the underlying media-server connection.
Connect Plex
Select Plex and request the plex.tv sign-in code shown by Halcyon Video. Enter that code through the documented Plex linking process on an authorized device, wait for Halcyon Video to detect authorization, and then select the appropriate server or servers from the list presented by the application.
Optional integrations
The connection interface also identifies optional integrations such as Jellyseerr or Overseerr for a requests wall and RomM for a video-game section. These are not required for the core Jellyfin or Plex setup. Configure them only from their respective current documentation, and treat their API keys or credentials as secrets.
| Connection option | Purpose | Verified configuration behavior |
|---|---|---|
| Jellyfin | Primary movie library provider | Uses a server address, username, and password entered through the connection interface. |
| Plex | Primary movie library provider | Uses a plex.tv code authorization flow and then presents available servers for selection. |
| Jellyseerr or Overseerr | Optional requests wall | Accepts an optional server address and API key. It is not required for the main library connection. |
| RomM | Optional video-game department | Can supply game and ROM shelves when the video-game section is enabled and the integration is configured. |
| Synthetic demo | Interface testing without a server | Loads a bundled demonstration catalog but does not scan or shelve personal media files. |
Verify the local deployment before remote access
Local verification should cover more than seeing an initial page. Confirm that the connection completes, library content appears, posters or cases load, and navigation works. Open at least one media item and verify that the application can communicate with the selected library provider. If the interface fails locally, keep troubleshooting the container, browser, or media-server connection before creating a public endpoint.
Also verify which local address should become the tunnel target. When the Localtonet client runs on the same host as the published Docker port, the target may be a local interface on that host. When the client runs on a different device, the target must be an IP address and port reachable from that client device. Use the actual published port from the Compose configuration, not an internal container-only port unless the networking setup explicitly makes it reachable.
Review Halcyon Video, Jellyfin, and Plex authentication behavior before sharing a public address. Use a least-privilege media account, protect credentials, remove optional integrations that are not needed, and do not publish management interfaces unintentionally. A tunnel provides connectivity, not a substitute for application authorization.
Access the Halcyon Video web app with Localtonet
Once Halcyon Video works at a confirmed local HTTP endpoint, an HTTP tunnel is the appropriate Localtonet tunnel family for its browser-facing web application. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, a public IP address, firewall changes, or VPN setup. The resulting public HTTPS address forwards requests to the local IP address and port you configure.
This is distinct from Halcyon Video’s own Remote Play feature. The project describes Remote Play as streaming the live store to another browser with its own TURN relay for off-LAN viewers. A Localtonet HTTP tunnel instead exposes the locally running Halcyon Video web endpoint. Choose the workflow that matches whether you want direct access to the hosted web application or the project’s separate Remote Play experience.
Install and run the Localtonet client
Install our client on the Halcyon Video host or on another device that can reach the verified local web endpoint. Keep the client running because the tunnel is available only while the selected device is connected and the tunnel is running.
Select the authenticated device
In the Localtonet dashboard, use the device-specific authentication token associated with the client that will carry the tunnel. Never copy the token into public documentation, support screenshots, source repositories, or configuration examples.
Select an available relay server
Choose an available server or region from the current dashboard. Availability can vary, so obtain the valid selection from the product rather than using a hardcoded server code from an article.
Create the HTTP tunnel configuration
Create an HTTP tunnel and set its local target to the confirmed IP address and published port for Halcyon Video. HTTP process types can provide a random subdomain, a supported selected subdomain, or a custom domain, with the same local content served at a public HTTPS address. Check current documentation before configuring custom-domain DNS.
Start the tunnel
Use the Start button after reviewing the target. Creating a tunnel does not automatically make it run. When the client is connected and the tunnel has started, the dashboard provides the public address.
Test the public address and stop it when finished
Open the assigned address from a network outside the local LAN and verify that the expected Halcyon Video interface appears. Confirm that authentication and playback behavior match your intended access model. Stop or delete the tunnel when public access is no longer required.
For the current product workflow and available settings, consult the Localtonet HTTP tunnel documentation. Avoid hardcoding relay selections, domains, or dashboard values into automation unless they have been obtained from the current dashboard or REST API.
Frequently asked questions
Does Halcyon Video replace Jellyfin or Plex?
No. Halcyon Video is a frontend that connects to Jellyfin or Plex for personal media libraries. It does not include a built-in folder scanner. Its synthetic demo can run without a media server, but that demo does not catalog your own files.
Which port should I use for the Localtonet HTTP tunnel?
Use the published local port established by the current Halcyon Video Compose configuration or quick-start documentation. The supplied evidence does not establish a fixed port, so this article intentionally does not guess one.
Can I use Plex instead of Jellyfin?
Yes. Halcyon Video supports Plex through a plex.tv code authorization flow. After authorization, the interface presents available Plex servers for selection.
Is a Localtonet tunnel the same as Halcyon Video Remote Play?
No. A Localtonet HTTP tunnel publishes the local browser-facing web endpoint through a public HTTPS address. Halcyon Video’s Remote Play is a separate project feature that streams the live store and uses its own TURN relay for viewers outside the LAN.
Does the tunnel remain available if the Localtonet client stops?
No. The public endpoint is available only while the selected Localtonet client device is connected and the tunnel is running. Creating the tunnel configuration alone does not start it.
Do I need router port forwarding or a public IP address?
No. Our client establishes an outbound connection to a Localtonet relay server. This allows the working local service to receive traffic through the assigned public endpoint without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Make your verified Halcyon Video web app reachable
After Halcyon Video is running locally and connected to Jellyfin or Plex, create a Localtonet HTTP tunnel for its confirmed local IP address and port. Test the public address carefully, keep application authentication enabled, and stop the tunnel whenever remote access is not needed.
Get Started Free →
