Install VuIO on Ubuntu or Debian with Remote Access

How VuIO and Localtonet fit together

VuIO is a media server rather than only a static file browser. It indexes a media directory and can serve compatible media to local DLNA/UPnP renderers, Chromecast or Google TV devices, and compatible AirPlay video receivers. Its documented media support includes formats such as MKV, MP4, AVI, WebM, MP3, FLAC, WAV, AAC, OGG, JPEG, and PNG. It also provides HTTP Range streaming, which allows compatible clients to seek within large media files, and HLS streaming for browser playback.

The project provides two browser interfaces. The lightweight built-in dashboard listens on port 8080 by default, while the modern Svelte web interface is available on port 8090. The port 8080 service is also the default command-line HTTP listener unless the documented --port option is used to change it. Because both interfaces are HTTP services, either can be an appropriate Localtonet HTTP tunnel target after it has been tested locally.

This HTTP workflow is separate from local media-device discovery. DLNA/UPnP discovery uses SSDP, and VuIO also documents mDNS or Bonjour discovery. Those mechanisms depend on local multicast behavior. An ordinary HTTP tunnel publishes an HTTP endpoint; it is not evidence that SSDP or mDNS multicast discovery will cross the internet. Remote users should therefore open the selected VuIO web interface through the Localtonet public URL rather than expect a television on a remote network to discover the server automatically.

Prerequisites for Ubuntu or Debian

Start with an Ubuntu or Debian machine on which you have permission to install packages and run a media service. The official installation command uses sudo, so the account must have administrative privileges. The host must also be able to reach the VuIO APT repository and normal package repositories over the internet during installation.

Decide which directory VuIO will index. The process that runs VuIO needs read access to the directory and its media files. If the service only needs to stream existing content, avoid granting unnecessary write access. This guide uses $HOME/media as a clearly labeled example because it avoids assuming that every machine has the same storage layout. Replace it with your actual directory.

mkdir -p "$HOME/media"

Place a small, known-good media file in that directory before verification. A small test file makes it easier to distinguish an indexing or permission problem from an issue caused by a very large library. Confirm that the Linux account that will launch VuIO can list and read the content:

ls -la "$HOME/media"

For remote access, install the Localtonet client on the VuIO host or another device that can reach the chosen VuIO IP address and port. Keeping both applications on the same machine usually allows the tunnel target to use a loopback address such as 127.0.0.1. If the Localtonet client runs on another device, use a private address through which that device can actually reach VuIO, and keep normal firewall and network policy requirements in mind.

Install VuIO from the official APT repository

VuIO publishes an APT repository for Ubuntu and Debian. The documented quick-start sequence creates a repository entry, refreshes the package index, and installs the vuio package. Run the commands exactly as shown, without adding unverified repository names or package options.

echo "deb [trusted=yes] https://vuiodev.github.io/vuio/apt stable main" | sudo tee /etc/apt/sources.list.d/vuio.list

sudo apt update && sudo apt install vuio

After APT finishes, confirm that the executable is available and inspect its built-in command-line help. This verifies that the shell can find the installed binary and gives you the options supported by the exact version on your machine:

command -v vuio
vuio --help

VuIO documents a positional MEDIA_DIR argument and a -p or --port option. The default port is 8080. Start with the default rather than changing multiple variables before the first successful test:

vuio "$HOME/media"

Keep that terminal open during the initial check. This makes startup messages and errors immediately visible. The available evidence does not establish whether every current APT package automatically creates, enables, or starts a system service, so this guide does not assume that it does. Running the documented executable directly is the clearest first verification path.

If you need to move the built-in dashboard away from port 8080 because another program already uses it, select a known-free port with the documented option. The following example uses port 8081 only as an example:

vuio --port 8081 "$HOME/media"

When changing this port, use the same value in your browser checks and in the Localtonet local target. Do not assume that changing the built-in dashboard port also changes every other VuIO endpoint. In particular, the modern interface is separately documented on port 8090, so verify the behavior of your installed version before building automation around custom ports.

Configure VuIO and choose a web interface

Open the built-in dashboard locally at http://127.0.0.1:8080. If you selected a different port with --port, substitute that value. Open the modern interface at http://127.0.0.1:8090. Testing through loopback first avoids interference from LAN routing, host firewall rules, DNS, or tunnel configuration.

VuIO supports an optional administrative token, secure session management, and CIDR-based network restrictions through its allowed_networks capability. Configure access controls before publishing an administrative interface. Exact configuration keys, file locations, and screen labels can change by release and are not fully established by the supplied evidence, so this guide does not guess their syntax. Use the controls exposed by the installed web interface and the configuration guidance bundled for your exact VuIO release.

VuIO also documents live configuration behavior: 21 of 25 settings can apply dynamically without a restart. That does not mean every setting is hot-reloadable. If a change does not take effect, consult the feedback shown by the running interface or restart the process during a maintenance window. Avoid assuming that a security-sensitive setting has applied until you test it in a fresh browser session.

Build the first media library conservatively

Begin with one small directory rather than a large storage tree. Confirm that files appear, metadata is readable, and browser playback works. VuIO includes live filesystem monitoring, so library content can update as files change. It also supports media metadata extraction, playlist discovery, sidecar SRT conversion to WebVTT, HLS playback, and HTTP Range requests. Some metadata providers require their own API credentials, but no provider key is required merely to prove that the local HTTP service starts and can see a test file.

Use a directory organization that makes permissions and troubleshooting obvious. If one folder appears while another does not, compare path traversal permissions on every parent directory. A readable file is not sufficient when the runtime account cannot enter one of its parent directories.

Verify the local installation before adding remote access

Local verification is a hard boundary in this workflow. If VuIO does not work over loopback, a tunnel cannot repair the application, its permissions, or its indexing configuration. Complete the following checks while the VuIO process remains visible in its terminal.

curl -i http://127.0.0.1:8080/healthz
curl -i http://127.0.0.1:8080/readyz

If the browser works on the host but not from another LAN device, the installation itself may be healthy. Check whether VuIO is listening only on loopback, whether the host firewall permits LAN access, and whether the client is using the correct private address. Do not weaken the firewall merely to support Localtonet. When our client runs on the same host, it can generally target the loopback service without opening VuIO directly to the LAN or internet.

A readiness probe and an interactive media test answer different questions. The probe can indicate that the application is operational, while the browser test confirms that the interface and content workflow function as expected. Perform both before remote exposure.

Optional Docker installation on Ubuntu or Debian

The native APT package is the most direct route for this guide, but VuIO also publishes the image ghcr.io/vuiodev/vuio:latest. Docker can be useful when you prefer isolated application files and explicit volume mounts. It does not remove the need to understand media permissions, persistent data, networking, authentication, or updates.

The official quick-start command uses host networking, mounts media read-only, and creates separate configuration and data mounts:

docker run -d \
  --name vuio-server \
  --restart unless-stopped \
  --network host \
  -v /path/to/media:/media:ro \
  -v ./vuio-config:/config \
  -v ./vuio-data:/data \
  -e VUIO_IP=192.168.1.100 \
  ghcr.io/vuiodev/vuio:latest

Replace /path/to/media with the real host directory. Replace 192.168.1.100 with the appropriate address for the VuIO host rather than copying the example unchanged. The media mount is read-only, which is a useful least-privilege default when VuIO only needs to index and stream existing files. The configuration and data mounts persist application state outside the container.

Host networking is relevant to local discovery because multicast-oriented media protocols can be difficult to operate through ordinary container port translation. It also means the container shares the host's network namespace, so review port conflicts and exposure carefully. The documented command does not publish individual Docker ports because --network host makes the service use host networking directly.

Verify the container and inspect its logs before testing the two interfaces:

docker ps --filter name=vuio-server
docker logs vuio-server

Then repeat the local browser and probe checks on ports 8080 and 8090. Localtonet does not require a different tunnel type merely because VuIO runs in a container. Our client still targets the reachable local HTTP address and port. With host networking and both applications on the same machine, that will commonly be the host loopback address, subject to the behavior of the installed versions.

Expose the verified VuIO web interface with Localtonet

Once the chosen interface works locally, an HTTP tunnel can make it available through a public HTTPS address. The Localtonet client establishes an outbound connection to our relay server, so this workflow does not require inbound router port forwarding, a public IP address, VPN setup, or a public listener configured directly on the VuIO host.

Creating a tunnel does not start it automatically. You must select the client device, configure the local target, create the tunnel, and press Start. The public endpoint remains available only while the selected Localtonet client is connected and the tunnel is running.

Our HTTP tunnel documentation provides the current dashboard workflow. Use it for current interface details, especially where available regions, plans, subdomain choices, or custom-domain requirements may differ.

Security checklist for remote media access

Treat remote media access as application publishing, not merely convenient connectivity. A media server can reveal filenames, library structure, metadata, artwork, logs, metrics, and administrative controls in addition to media streams. Protect the application according to the sensitivity of the library and the people who are authorized to use it.

Never publish Localtonet device tokens, VuIO administrative tokens, metadata-provider keys, or private URLs. If a credential is exposed, remove it from public material and rotate it using the relevant application's current credential-management process. Redacting a screenshot after it has already been distributed is not a substitute for rotation.

Also consider the content itself. Make sure you are authorized to store, stream, and share every item in the selected media directory. Use separate directories or operating-system permissions when different users should have access to different libraries. Do not point VuIO at an entire home directory or storage root merely for convenience.

Routine operation and maintenance

For a foreground native installation, stop VuIO by returning to its terminal and sending the normal interrupt with Ctrl+C. Restart it with the same media directory and any intentionally selected options. If you later configure a system service, use only the service unit name and installation procedure provided by your installed VuIO package or current project documentation. This guide does not guess a unit name because the supplied evidence does not establish one for every package version.

For Docker, the container name in the official example supports straightforward lifecycle operations:

docker stop vuio-server
docker start vuio-server
docker logs --tail 100 vuio-server

Before an upgrade, record the currently working configuration, media mounts, selected ports, authentication behavior, and Localtonet target. After upgrading, repeat local health, browser, media playback, and unauthenticated-access tests before declaring the deployment healthy. If you use the Docker latest tag, explicitly pulling and recreating the container may change the running version, so plan rollback and data protection first.

VuIO's live file monitoring should notice library changes, but large imports still deserve observation. Add content in manageable batches, confirm that indexing completes, and inspect application output if newly added files do not appear. Format support does not guarantee that every individual file is valid or playable in every browser or renderer.

Troubleshooting installation, web access, and tunneling

APT cannot retrieve or install the package

Display the repository file and confirm that it contains the documented URL and suite. Then run sudo apt update separately so its complete error remains visible:

cat /etc/apt/sources.list.d/vuio.list
sudo apt update
sudo apt install vuio

DNS failures, TLS errors, repository availability, and unsupported system configuration require different remedies. Do not repeatedly rewrite the repository entry until the actual APT message has been identified. If organizational policy prohibits trusted=yes, stop and use an installation approach approved by that organization rather than silently weakening policy.

The vuio command is not found

Confirm that APT reported a successful installation and ask the shell to locate the binary:

command -v vuio
dpkg -l vuio

If the package is not installed, return to the APT error. If it is installed but cannot be found, inspect the package contents and the current account's PATH rather than inventing a binary location.

Port 8080 is already in use

Inspect the listener before terminating anything:

sudo ss -ltnp | grep ':8080'

Either stop the conflicting application through its normal management process or launch VuIO on another known-free port using --port. Update all local checks and the Localtonet target to match. Never kill an unfamiliar production process merely to reclaim a port.

The interface loads but the media library is empty

Confirm that the command points to the intended directory, that the directory is not empty, and that the runtime account can traverse every parent directory and read the files. With Docker, verify both sides of the media volume mapping and remember that the official example mounts the host directory inside the container at /media. Inspect VuIO logs for indexing or format errors.

Port 8080 works but port 8090 does not

Treat the two interfaces as separate endpoints. Confirm that the installed version includes and starts the modern web interface, inspect startup output, and check whether anything is listening on port 8090:

sudo ss -ltnp | grep ':8090'

Do not point the tunnel at 8090 until a local request to 8090 succeeds. If only the built-in dashboard is available in the current deployment, port 8080 remains the evidence-backed target.

VuIO works locally but the Localtonet URL fails

Confirm that the Localtonet client is connected, the correct device was selected, and the tunnel was started rather than merely created. Recheck the local target from the client device itself. If our client is on the VuIO host, test the exact loopback URL configured in the tunnel. If it is on another machine, 127.0.0.1 refers to that other machine, not the VuIO host, so use a reachable private address instead.

Also confirm that the tunnel targets the intended port. A working dashboard on 8080 does not prove that 8090 is reachable, and the reverse is also true. Available relay servers and server codes should come from the current dashboard rather than a copied value.

The public page opens but playback fails

Test the same media item locally in the same type of browser. If local playback also fails, investigate the file, format, indexing state, and application logs first. If local playback succeeds, compare the public browser's network requests and verify that authentication, media requests, HLS playlists, and ranged requests remain authorized through the selected interface. Avoid making unsupported assumptions about bandwidth, relay performance, or file compatibility without observing the failing request.

A remote television cannot discover VuIO

This is expected when only an HTTP tunnel has been configured. SSDP and mDNS discovery are multicast-oriented local-network mechanisms, while a Localtonet HTTP tunnel publishes the VuIO web interface. Use the public URL from a browser. Do not advertise ordinary HTTP tunneling as a way to extend DLNA discovery to a separate network.

Frequently asked questions