Setup &
configuration.

Your library, served from your computer

HoshiStream keeps a personal media library on your computer and makes it available in your browser, Nuvio, or Stremio. Add a video you already have, or manually add a torrent you are authorized to access. The native app runs the library server and TorrServer, the torrent engine, together. Your computer must remain on and reachable while another device watches.

Choose the right starting point

• Installed Mac users: follow macOS installation if you have an appropriately approved build, or are validating your own local build. No developer tools are needed to run the packaged app.
• Windows users and developers: see Windows and source operation. A running Node server is not the same as an installed native desktop app.
• Existing users: take a stopped, complete backup before replacing an app or changing where its data lives.

What to have ready

• For the macOS candidate: an Apple Silicon Mac with macOS 13.5 or newer, a browser, and enough free space for the app, torrent cache, and any media you choose to upload or keep.
• A trusted home network. Put the host and player on the same non-guest network; use Ethernet for the host when practical.
• An authorized test video. H.264 video with AAC audio in an MP4 container is the initial browser baseline, not a promise for every browser or file. Exact browser/client versions and sustained playback still need acceptance.
• Optionally, Nuvio or Stremio on the device where you want to watch. Start with one direct-play stream. Remote streaming, broader codecs, advanced storage, and companion rollout have separate acceptance requirements.

Privacy and network use

There are no HoshiStream accounts, automatic beta analytics, or in-app reporting service. Library and configuration files stay on your computer. Local-first does not mean offline or anonymous. Only use media you own, public-domain media, or material you have permission to access. There is no in-app torrent search, indexer setup, or automatic discovery of media.

There is no supported switch for entirely offline startup. HOME_SPEED_MBPS is a fallback, not a speed-test opt-out; LAN_REDIRECT=off does not disable measurement. Private add-on and management URLs are credentials. Keep them out of screenshots, public issues, shared clipboards, and online URL checkers. Plain HTTP on the LAN is not end-to-end encrypted.

Further detail: privacy and network boundary and candidate acceptance requirements.

Install the app, not a development environment

The packaged Mac app includes Node, TorrServer, FFmpeg, and ffprobe. It does not include mpv. Compatible browser playback needs neither Homebrew nor a separately installed player. These instructions describe installation; they do not lift the candidate's distribution hold.

1. Check the build's origin. Use the exact app/image and release information approved for your test. Keep its build ID, checksum, and notes. A checksum confirms matching bytes, not publisher identity.
2. If replacing an app, stop first. Close playback, disable Start at Login, take a stopped backup, and choose Quit HoshiStream. Preserve the previous app; do not replace a running bundle.
3. Open the disk image and copy HoshiStream to Applications. Launch the copy in Applications, not the app inside the mounted image. A locally built app can likewise be copied from its build folder with Finder.
4. Find HoshiStream in the menu bar. It does not keep a Dock window open. Wait for the services to become ready; a fresh installation opens Get started in your default browser.
5. Allow only trusted-LAN access when prompted. The firewall may identify the bundled Node or TorrServer executable. Keep macOS protections enabled. Do not forward application ports on your router.

cd "$HOME/Downloads"
shasum -a 256 -c 'HoshiStream-BUILD-ID-darwin-arm64.dmg.sha256'

If macOS blocks the app

The current candidate is ad-hoc signed, not Developer ID signed or notarized. Depending on macOS and device policy, a downloaded copy can be described as unverified or damaged even when its checksum matches. After attempting to open a trusted copy, look in System Settings > Privacy & Security and use Open Anyway only if offered and permitted.

For local build prerequisites, see source workflows. Packaging, provenance, and assisted installation are documented in the macOS distribution guide.

Add one title and choose where to watch

First launch creates your private configuration, a unique access token and pointer push secret, and the app's state folders. You do not need to paste credentials into a setup form. The default Mac state folder is ~/Library/Application Support/HoshiStream; the local media folder defaults to ~/Movies.

1. In Get started, choose Add media and add an authorized title. This step completes only when an entry is actually saved, not when a form opens.
2. Open the title and choose Play to watch in the browser, or choose a file from its Files tab. A source check is separate from saving and playback.
3. To connect a separate device, choose Nuvio or Stremio, copy the private add-on URL, and install it in that player. Follow the player connection steps.
4. Return and choose I can see HoshiStream only after it appears in the player's add-ons. Copying the URL is not confirmation. Recent recognized catalog activity is reported separately.
5. Choose Finish setup once a title is added and player setup is confirmed. For browser-only use, choose Skip for now; no TV-player confirmation is needed to leave onboarding.

Skipping does not remove media or change settings. Reopen the guide from Get Started in the menu bar or Get started in the sidebar. Progress is stored locally in onboarding.json. Changing the selected player clears its earlier confirmation. Existing installations are not forced through a new welcome window.

Know the everyday controls

Library

Add titles, filter by tags, open an entry, and select playback files.

Status

Review service health, build identity, resources, and the speed measurement.

Activity

Review connected-client activity and optional remote pointer setup.

Storage

Manage registered storage folders, disk-copy work, and its download window.

Menu bar

Open HoshiStream, copy URLs, Restart Server, Check Speed, Show Logs, or Quit HoshiStream. Start at Login and magnet-link handling are separate opt-ins; onboarding does not enable them.

Closing the browser does not quit HoshiStream. Keep the host awake and connected while watching; closing a laptop lid or deliberately sleeping it can interrupt service despite the app's sleep-prevention requests.

Save the source, then check the selected file

In Library, choose + Add Media. Select the source type, review the title and movie/series type, add optional tags, and choose Add to library. HoshiStream does not find or scrape torrents for you.

Recognized video extensions are .mp4, .mkv, .webm, .avi, .mov, and .m4v. Recognition makes a file selectable; it does not mean your browser can decode it. Use the native picker instead of typing an arbitrary path. Browser-entered local paths must be absolute and inside the configured media or managed-storage roots.

Understand the result, not just the badge

Inspect and check after saving is enabled by default for interactive adding, with a per-add opt-out. Saving happens first; metadata inspection and a bounded ffprobe sample run afterward. If a check fails, the entry remains saved. Retry its check instead of adding the same title again.

A basic automatic check has a 60-second overall deadline and a 20-second probe limit. An explicit longer retry allows up to 180 seconds overall and is never started automatically. These are time limits, not strict network byte caps: TorrServer may read ahead. Results carry a file/source identity and observation time. An earlier success is historical evidence, not a current availability guarantee.

Series, file selection, and tags

• A linked folder becomes one series. Filenames such as S01E02 or 1x02 provide episode numbers; otherwise files become season 1 in filename order.
• Use the entry's Files tab to review the actual episode or video before playback. Correct selection or episode overrides if automatic identification chooses a sample, extra, or wrong episode.
• A torrent-backed series can have several sources. Use + Add another torrent when adding magnets, or its Source tab afterward, then re-inspect. Filename numbering takes precedence over a season hint. The newest source wins overlapping episodes, so review before replacing coverage.
• A series entry's Episodes tab shows each episode with a title cleaned from its filename; you can type your own title, a short overview and an air date, and mark the show Ongoing so Stremio keeps it on the Board. Generate thumbnails grabs one frame per episode whose file is already on disk (a linked folder or a completed disk copy) with the bundled FFmpeg; nothing is ever fetched from a live torrent for a thumbnail.
• Tags can be selected or created when adding/editing a title. Library tag filters require every selected tag. The Tags page renames/deletes labels across affected titles; Stremio exposes them as catalog genres.
• After moving linked media, use Relink in Finder in the entry's Source controls. Deleting a linked entry does not delete its original file. Managed uploads and explicitly requested disk-copy deletions have different ownership rules.

Browser JSON export is useful for portable metadata, not full recovery: it omits local paths and does not embed .torrent files or media. Keep library state and managed files together in a complete backup. See the media-adding reference for additional API and series details.

Watch here, or connect a player on your LAN

In the management browser

Open a title and choose Play, or choose a file from Files. This opens HoshiStream's browser player, not mpv. Start with authorized H.264/AAC MP4 media. Browser codec/container support, source reachability, and available bandwidth remain separate questions.

If autoplay is blocked, use the player's play control. Slow startup and buffering do not automatically switch quality or format; wait, retry, or explicitly select another offered rendition. Open direct stream opens the raw media URL. It is not a playback test and may still fail in the same browser.

In Nuvio or Stremio

1. Connect the player device and host computer to the same trusted LAN. Keep HoshiStream running and the host awake.
2. In Get started, select your player and copy the private add-on URL. Prefer Copy direct LAN URL for initial setup. The Mac menu also provides Copy Direct LAN URL.
3. In Nuvio, open Addons, choose Add Addon, and paste the URL. In Stremio, open Add-ons, paste the URL into the add-on search field, and install HoshiStream. Client wording may vary.
4. Confirm HoshiStream appears in the installed add-ons, open its catalog, and try your authorized title. Then confirm the connection in Get started.

Stremio's Board shows a HoshiStream row per type for your whole library, Continue Watching, Recently added, Unwatched, and any tag you pin from the Tags page (up to eight). The add-on tile carries the HoshiStream logo; a contact address is optional and set on the same page.

If copying is unavailable, expand Show private URL and copy locally. Do not send it to someone else to test. The following are URL shapes only: PRIVATE_TOKEN is a placeholder, and 192.168.1.50 must be replaced with your host's address.

Local management, on the host:
http://127.0.0.1:7001/manage/PRIVATE_TOKEN

Private add-on, for another LAN device:
http://192.168.1.50:7001/addon/PRIVATE_TOKEN/manifest.json

127.0.0.1 and localhost mean the device opening the URL, not your Mac when entered on a TV. Native mode detects a LAN address; if it reports a computer-only address, reconnect to the trusted network and restart. After an address change, copy/reinstall the updated direct URL. A router DHCP reservation can help keep a LAN address stable without exposing any port.

Firewall and reachability

A working catalog does not prove that direct torrent media on port 8090 is reachable. Avoid guest networks, client isolation, or VPN adapters that select an unreachable interface. Approve the relevant app executables in the host firewall for the trusted network only; do not disable the firewall. Approval can need renewal after replacing a Mac app bundle.

Optional host player: a different path

The advanced host-player API can control mpv through IPC or hand off to an installed IINA, VLC, or system handler. On macOS, install the player separately and configure an absolute PLAYER_PATH for mpv; a menu-bar app may not inherit your shell's PATH. A generic handoff does not provide HoshiStream's playback controls or prove codec compatibility. The Windows desktop payload is designed to bundle mpv, but its rollout is still deferred. Neither changes what the management page's Play button does.

See the management API reference for the advanced host-player interface, and remote access for the distinction between a stable pointer URL and actual off-LAN streaming.

Change the settings your launch mode actually reads

Most installed users can keep the generated defaults. Use the management page for library metadata, tags, disk-copy selections, download windows, and remote pointer setup. Use the private .env file for startup configuration. Editing a checkout's file does not configure an installed app.

Find the active configuration

1. Record the active build and paths. Back up before changing credentials, ports, or storage roots. For a simple setting change, stop playback first.
2. Open .env in a local plain-text editor. In Finder, use Go > Go to Folder to open the state folder and Command-Shift-Period if you need to reveal hidden files. Do not upload the file to an online editor.
3. Use one KEY=value per line, with the key at the start and no spaces around =. Keep comments on their own lines starting with #. Avoid duplicate keys, shell export statements, and inline comments.
4. Use absolute media paths. Native parsing does not expand ~, $HOME, or %LOCALAPPDATA% inside values. Double quotes can surround a path with spaces; do not use shell single-quote syntax. Keep generated tokens and numeric ports unquoted for the native menu's reader.
5. Save as plain text without adding a .txt suffix, then choose Restart Server. For a state-root migration, quit the entire app and use the recovery procedure instead. UI pointer and storage settings apply without this restart.

This example changes no credentials. Replace the media path with an existing folder you own; do not replace your generated file wholesale.

ADDON_PORT=7001
MEDIA_DIR="/Users/your-name/Movies"
HOME_SPEED_MBPS=10
LAN_REDIRECT=auto
MDNS_ENABLED=true
TRANSCODE_ENABLED=false

Native app and whole-stack startup settings

These values are read from the resolved project .env by scripts/native-server.mjs. A fresh native installation generates missing credentials; add-on-only mode does not.

For MDNS_ENABLED and TRANSCODE_ENABLED, only the exact strings true or 1 enable the option. Other supplied strings evaluate false. Prefer explicit true/false, not yes, on, or uppercase variants. Other enums are likewise case-sensitive. Omit optional values rather than leaving invalid empty URLs or numbers.

Settings saved through the interface

Know which files are yours and which are managed

HoshiStream has three different storage roles: linked originals stay where you selected them; browser uploads are copied into managed storage; torrent cache is temporary engine data. Keep on disk is an additional, explicit copy of selected torrent media to a registered drive or folder. It is not required to watch a local file or stream a torrent.

Keep an authorized torrent on a drive

1. With the native desktop app running, open Storage and choose + Add drive or folder. Select a writable local folder on the intended drive. Server-only mode has no desktop folder picker.
2. Confirm the volume is Online and has enough free space. HoshiStream creates a small .hoshistream-volume.json identity marker in that storage root. Keep it with the copied media.
3. Open a torrent-backed title's Keep on disk tab, select the registered volume, and choose Keep on disk. Inspection may be needed first. Local-file/folder entries are not eligible for this torrent archiving feature.
4. Review series file selection and apply the files you want to keep. The default scope keeps all selected media from the inspected entry; a selected-file scope preserves your explicit inclusion choices.
5. Follow Storage > Downloads. One title copies at a time. Use Pause or Resume explicitly; a manually paused job stays paused across restarts.
6. Optionally give a series a rolling window in its Keep on disk tab: Keep N ahead archives the next unwatched episodes after the one you last played, and Remove watched copies deletes copies you have finished once that window is on disk. Both are off by default; nothing that is playing or still copying is ever removed.

Disconnecting, reconnecting, and moving drives

Pause copies and stop playback from the drive before ejecting it through the operating system. A disconnected drive becomes Offline and its copying waits. HoshiStream identifies registered storage by its marker rather than trusting a volume name or Windows drive letter. A renamed/remounted drive can be found again; a different drive with the same name is not silently substituted.

Complete, valid disk files are preferred while available. If a selected copy is unavailable, the stable media route can fall back to its torrent. That fallback still needs a reachable source and network; it is not a seamless-playback or offline guarantee. Wrong-size or invalid copies need review and an explicit retry before replacement.

Download windows

In Storage > Download window, set start and end times and choose Enable window or Update window. Times use the host's local clock; overnight windows such as 23:00-06:00 work. Equal start/end times allow the whole day. By default, downloads run anytime.

A file already copying finishes when a window closes; new work waits. Playback and torrent fallback are never restricted by this schedule. Use Download anytime to remove the window. Space used by full disk copies and browser uploads is additional to TorrServer's 4 GiB cache configuration.

Back up the volume marker, copied media, library, volume registry, cleanup records, and schedule together. External-drive recovery remains outside first-cohort acceptance and should be assisted. See backups and recovery before cloning or moving a registered storage root.

A stable URL is not a tunnel to your media

Normal setup is trusted-LAN only. A remote pointer can keep an add-on address stable while directing clients to your last-registered LAN address. A tunnel instead exposes selected local services through an external hostname. These solve different problems. Neither removes the need for an awake host, reachable media, appropriate client support, and private credentials.

Optional: configure a remote pointer

Use only a pointer operator you trust with authentication requests and network metadata. This guide does not endorse or enroll you in a service. The UI can suggest an endpoint and identify its operator; review those details or enter your own service origin, such as https://pointer.example.com.

1. Choose Remote Pointer Settings in the Mac menu, or open Activity > Remote pointer.
2. Enter a trusted HTTPS origin without a path, query, fragment, or embedded credentials. HTTP is allowed only for loopback development. A Vercel deployment token or storage credential is not a service URL.
3. Choose Save and enable. This saves local setup only, sends nothing to the service, and needs no restart. Existing enabled setup uses the Save endpoint label.
4. Choose Register / update to deliberately send this installation's manifest, current LAN base address, and authentication to the service. The first successful push claims this token using the per-install push secret.
5. After a successful current registration, choose Copy private pointer URL and install it in a compatible client. Its shape is https://pointer.example.com/addon/PRIVATE_TOKEN/manifest.json.

The Mac menu's Copy Stremio URL uses the pointer only when local state reports it usable; otherwise it uses the direct LAN URL. Copy Direct LAN URL remains a recovery path. A pointer serves the stored manifest, then redirects other add-on requests to the last-pushed address. Media bytes do not pass through the pointer service. A device outside that LAN cannot reach its private address just because the pointer's manifest loads.

Updates, expiry, and removal are deliberate

• After a LAN-address change, reconnect and restart the native server, then use Register / update or Update Remote Pointer. There is no automatic IP tracking.
• Records expire after 90 days without a push in the supplied pointer implementation. Register/update again when appropriate. Local status is evidence of the last operation, not continuous service monitoring.
• Check service is another explicit network request. An unreachable or rate-limited service does not stop direct-LAN use.
• Remove remote record requests service-side deletion. Check for acknowledged success; a failure or ambiguous response is not proof of deletion. Remove a remembered record before changing services.
• Disable locally prevents pointer use but keeps the credentials and any remote record. Re-enable before requesting removal. Uninstalling the app does not delete a pointer record.

Preserve both ACCESS_TOKEN and POINTER_PUSH_SECRET in your private backup. A new random push secret cannot update an existing claim. If pointer history exists and configuration is lost, startup or pointer setup may stop rather than invent a new identity. Restore the original credentials while stopped, or arrange deliberate claim recovery privately with the service operator. Never send the secret to the operator as a support step.

The supplied service stores token/secret hashes, manifest, LAN base URL, and timestamps in its application records, not your library or media. Requests still carry credentials, and the operator/hosting platform can process them. Browser clients may block HTTPS-to-HTTP-LAN redirects through mixed-content or private-network rules. Use the direct LAN URL when that happens; acceptance depends on the exact client/version.

Advanced: an actual off-LAN connection

For a separately reviewed setup, Cloudflare Tunnel uses a connector making an outbound connection to a Cloudflare account/domain. The connector and its service credentials are separate from HoshiStream; neither desktop package automatically provisions that tunnel. A public hostname such as hoshi.example.com needs carefully restricted routing, TLS, client-compatible access controls, and verification of every returned media URL, not just the manifest.

The repository's older tunnel walkthrough is not a turnkey remote-playback guarantee. Ordinary torrent streams can point directly to TorrServer's port, while local files use add-on routes. Current request-host URL construction also uses HTTP rather than treating a TLS tunnel hostname as sufficient. Routing only port 7001 therefore does not establish a working, private, HTTPS media path. Do not solve that by publishing raw port 8090.

The existing LAN_REDIRECT=auto shortcut compares a tunnel request's Cloudflare client-IP header with a public-IP lookup at www.cloudflare.com/cdn-cgi/trace, cached for five minutes after success. A match can select configured LAN URLs. This is a routing hint, not authentication; CGNAT or unsuitable proxy/header handling can make it wrong. LAN_REDIRECT=off disables the shortcut, not startup measurement or the need for correct public stream URLs.

Before any remote-media experiment, verify the chosen provider's current video-traffic terms and limits, home upload capacity, TLS/range-request behavior, and exact client compatibility. Do not paste tunnel credentials into shared command history or reports. For operator background, consult the pointer deployment guide and the historical tunnel walkthrough, subject to the current limitations above.

Capture a source, then review it yourself

Chrome companion

The companion is an optional same-computer bridge, not a search engine or remote-library client. It has no Chrome Web Store release at present. Local testing uses a matching unpacked extension; that is not the finished distribution experience. The desktop app's native helper registration and installation of the extension in Chrome are separate steps.

1. Install the current app in its final location and open it once so it registers its native helper. For a source checkout, use the explicit registration workflow below.
2. For local testing, open chrome://extensions, enable Developer mode, and use Load unpacked on the matching extracted companion folder. Pin it if desired. Do not load an extension from an unknown source or change its identity independently of the helper.
3. Browse normally. Right-click a selected magnet and choose Add to HoshiStream, or open the companion's side panel. Reading source links from the active page requires your explicit action.
4. Choose the intended source if several are present. Review name, type, tags, and destination, then confirm adding. Follow the separate source check or open the saved entry.

For a protected .torrent link, download it normally in the browser, then choose/drop that file in the companion. No cookies or browsing history are exported. No server address or access token needs to be entered in the extension. A duplicate offers the existing entry; a lost response can be retried without deliberately adding another copy.

Add to an existing series

Choose Add to existing series, select an inspected torrent-backed series, and request an episode preview. That explicit preview can contact peers but does not add the source yet. Review new episodes and overlaps, then approve replacements before confirming. Filename numbering overrides an optional season hint; the newly appended source wins approved overlaps. Local-file/folder series are not eligible. An expired preview or changed target requires fresh review.

cd addon
npm run build
cd ..
node scripts/register-browser-bridge.mjs \
  --runtime-root="$PWD" \
  --project-root="$PWD" \
  --state-dir="$PWD/native-data"
node packaging/build-chrome-extension.mjs

Native magnet links, without Chrome

On macOS, choose Use HoshiStream for Magnet Links in the menu bar only if you want to change your default handler. Accept your browser's Open HoshiStream prompt when appropriate. A clicked magnet can start the app and open Add Media with a suggested source/name. You must still review and choose Add to library; clicking alone does not save a title or download torrent data.

The private handoff expires after ten minutes or an app restart. Click the original link again or choose Enter manually if it expires. To switch away later, use the other application's association setting. Windows' desktop implementation makes HoshiStream an available handler; selecting a protected default remains your choice in Windows settings.

If the helper will not connect

Open the matching desktop app and retry. A Node-only server does not install the Windows native helper, tray, or pickers. A checkout helper also needs its server started manually. If macOS blocks Chrome's helper from a checkout in Documents, prefer the installed Applications copy; do not disable protections or grant broad disk access to make the development path work. Be aware that switching registrations switches which local library you see.

See the companion installation and removal reference for native-host ownership and packaging requirements.

Separate a desktop candidate from a source server

Windows status and packaged behavior

Windows 11 x64 is the desktop target; rollout remains deferred pending exact redistribution materials and real Windows-machine acceptance. Cross-compilation and automated tests are not proof of tray, dialogs, SmartScreen, Chrome, sleep, drive, or player behavior on recipient hardware.

The implemented installer is per-user, with program files under %LOCALAPPDATA%\Programs\HoshiStream and private state under %LOCALAPPDATA%\HoshiStream. A portable build must be extracted as a complete tree to a stable folder; copying only HoshiStream.exe is insufficient. The desktop payload includes .NET, Node, TorrServer, mpv, ffmpeg, and ffprobe, so recipients do not need those development tools separately.

• Launch from the Start Menu or HoshiStream.exe. The notification-area icon may be hidden under the overflow arrow. The browser is the management interface; closing it does not quit the tray.
• The tray offers library/setup, copied URLs, Restart Server, Check Speed, pointer actions, logs, login/default-handler controls, and Quit. Start at Login is optional and starts the current-user tray after sign-in, not a service before login.
• Unsigned builds can trigger SmartScreen or unknown-publisher warnings. Verify origin and checksum; do not disable Defender or circumvent an organization policy.
• Permit LAN traffic only on a trusted Private network. The app does not silently create firewall rules. Prompts may name bundled node.exe or TorrServer.exe.
• Native selection links files in place. The helper and magnet integrations need the desktop build, not just the Node process. Sleep prevention is best effort; deliberate sleep, lid behavior, and power policy take precedence.

Windows startup configuration is edited in the state folder's .env, then applied with Restart Server. For example, MEDIA_DIR=C:\Users\your-name\Videos must name an actual folder. Keep state on private local NTFS, not a network share. Logs live under the state's logs directory.

Run the whole stack from source

Developers need repository access, Git, and Node 22.18 or newer with npm. Node strips TypeScript types directly in source mode. This is distinct from the independently pinned packaged runtime, currently Node v26.3.1. No container or database is required.

Quit any installed or terminal HoshiStream first: service ports and the peer port must not conflict. If you do not have a checkout yet, open Terminal or PowerShell in the folder where you keep projects, then run:

git clone https://github.com/MajorJohn98/HoshiStream.git
cd HoshiStream

From the repository root, on macOS or Windows x64:

cd addon
npm ci
cd ..
node packaging/fetch-torrserver.mjs
node packaging/fetch-ffmpeg.mjs
node scripts/native-server.mjs --dev

The fetchers obtain the host platform's pinned tools; the FFmpeg fetch includes ffprobe. Current TorrServer packaging is pinned to MatriX.141. The foreground server reads or creates the checkout .env, stores JSON state in native-data/, and stores managed uploads in data/media/. Correct any inherited example paths before use. View credentials only in a private editor and open the local management URL shape shown under players, using the generated token and configured port.

Keep the terminal open and press Ctrl+C to stop. For a watch/restart loop, run npm run dev:native from addon/. Server-only mode has no menu bar, native file picker, or automatic companion registration. Management assets are served from disk, so UI asset changes need a browser refresh.

Operate the installed state without the desktop shell

The start scripts are a drop-in for the installed app, not an isolated development library. They use its state folder and identity by default. Quit the desktop app first; do not run both against the same state. From the repository root:

macOS shell

./scripts/start-native.sh --dev

# Later, stop this terminal-launched stack:
./scripts/stop-native.sh

Windows PowerShell

.\scripts\start-native.ps1 --dev

# Later, stop this terminal-launched stack:
.\scripts\stop-native.ps1

Follow your machine's script policy; use foreground Node mode if scripts are not permitted rather than disabling security policy. Without --dev, checkout start scripts build the add-on first. Their start/stop controls verify the owned runtime and readiness rather than trusting a PID alone. A launched Windows connector or other service does not start this per-user app before sign-in.

cd addon
npm run build
node --env-file=../.env dist/index.js

cd addon
npm ci
cd ..
node packaging/fetch-node-runtime.mjs
node packaging/fetch-torrserver.mjs
node packaging/fetch-ffmpeg.mjs
./packaging/build-macos-app.sh

$env:HOSHISTREAM_TARGET = "win32-x64"
node packaging/fetch-node-runtime.mjs
node packaging/fetch-torrserver.mjs
node packaging/fetch-ffmpeg.mjs
node packaging/fetch-mpv.mjs
node packaging/build-windows-app.mjs --stage-only

Before submitting source changes, use the existing checks from addon/: npm run typecheck, npm test, npm run lint, and npm run format:check. The development guide, Windows setup reference, and Windows packaging guide describe the fuller operator workflows.

Stop first. Back up the complete, resolved state.

There is no automatic updater or universal downgrade guarantee. library.json.bak and a browser JSON export are not full backups. A usable snapshot includes configuration, credentials, managed source files, and the state that describes them. Store it privately on an encrypted, access-controlled destination, separate from your only live copy.

Inventory before copying

1. Record About HoshiStream's exact build ID, not just 0.15.0. Retain its app/image, checksum, and compatibility notes.
2. Resolve the actual project/configuration, state, and managed-data roots using the launch-mode table. Custom Mac builds, terminal overrides, and add-on-only paths can differ from the installed defaults.
3. Copy the entire state directory, including hidden files, library backups/quarantines, all auxiliary JSON stores, TorrServer config and cache, and existing transcode data. For split checkout layouts, also capture the project .env and entire data/ tree.
4. Back up linked originals and registered disk-library roots separately. Preserve each drive's marker and media along with volume/cleanup/schedule state. Record original absolute paths. Do not mount two copies of one volume identity together.

Runtime state belongs on a private local filesystem. Do not move the live state directory into a public/shared sync folder. Backups contain the same powerful credentials as the live app; copying files does not encrypt them. Logs can help private incident diagnosis but are not needed to restore. Browser/player history, OS login/default-handler settings, and external Chrome registration are separate.

Stop all writers

Turn off Start at Login, close player sessions and the companion, and choose Quit HoshiStream, not Restart Server. Stop foreground/watch servers with Ctrl+C or terminal-launched instances with their matching stop script. Wait for the owned Node and TorrServer processes to exit.

Check the configured service ports in Activity Monitor/Task Manager or with the read-only commands below on macOS. No output from a port query means no matching listener was found, not proof that every possible writer has stopped. A remaining runtime lock or supervisor socket blocks backup; do not delete a lock or kill an unidentified process to get past it.

lsof -nP -iTCP:7001 -sTCP:LISTEN
lsof -nP -iTCP:8090 -sTCP:LISTEN

STATE="$HOME/Library/Application Support/HoshiStream"
BACKUP="$HOME/HoshiStream Backups/2026-09-07-before-update"

umask 077
test -d "$STATE" && test -f "$STATE/.env" &&
test ! -e "$STATE/run/runtime.lock" &&
test ! -S "$STATE/run/supervisor.sock" &&
mkdir -p "$HOME/HoshiStream Backups" &&
mkdir "$BACKUP" &&
/usr/bin/ditto "$STATE" "$BACKUP/state" &&
/usr/bin/diff -qr "$STATE" "$BACKUP/state" &&
touch "$BACKUP/COMPLETE"

Update without changing your identity

1. Obtain an owner-approved compatible build, verify its origin/checksum, and complete the stopped backup.
2. Preserve the prior app. Replace only the app/program files using the intended install procedure; do not replace state with installer contents.
3. Launch once at the same location and confirm the exact build ID, library, tags, setup progress, linked originals, managed media, and client playback.
4. Verify private client URLs and pointer credentials are unchanged. Restarting or saving setup must not silently register a pointer.
5. If the LAN address changed, recopy the direct URL or manually update a configured pointer. Re-approve trusted firewall access if prompted.
6. Restore Start at Login only after a successful session. If data is unexpectedly missing, stop and preserve both states before adding or changing anything.

Restore at the same paths

Use the artifact that created the backup or an explicitly accepted forward reader. Stop all writers again. Verify the snapshot is complete. Restore it into a new sibling staging directory and compare it with the snapshot, then preserve the current state under a separate unused name before swapping the restored directory into its original path. Do not merge old/new library trees or overwrite the only current copy.

Do not reactivate backed-up runtime locks, sockets, control credentials, or PID files; preserve those records separately while the app recreates live runtime metadata. Keep the backup and held current state after the first successful launch. Do not run a restored clone alongside another installation with the same pointer credentials. Any failed staging/swap step is a reason to stop, not repeatedly launch.

Absolute file paths mean that another Mac, user account, mount point, or storage root needs assisted relinking/migration. Rolling back after a new app has written state requires both the old artifact and its matching pre-update snapshot. Newer changes do not move backward automatically. Never open current state with 0.8.2 or another unapproved older reader; unknown fields may be lost when it writes.

Uninstall the app without deleting your library

1. While the app works, use Remove remote record if you want pointer data removed. Confirm success and retain credentials until removal is settled.
2. Turn off Start at Login, choose another magnet handler if desired, remove the extension in Chrome, quit the app, and take a final stopped backup.
3. On macOS, unregister this installation's native helper while its tools are still available, using the ownership-aware companion removal procedure. Reopening the app registers the helper again.
4. Move only HoshiStream.app to Trash on macOS, or use the Windows installer's uninstall entry for an installed Windows build. The Windows implementation preserves state and removes only its owned integrations.
5. Leave state, logs, backups, managed files, linked originals, and volume markers intact. Do not use a cleanup utility that erases Application Support or shared media. Permanent data erasure is a separate explicit decision.

The backup, same-path restore, and rollback runbook contains the guarded Mac restore commands and full inventory. Use assisted recovery rather than adapting those commands blindly to Windows or a custom layout.

Start with the symptom, not a reset

Use Status and the native Show Logs action. Keep diagnostics local. The Mac app writes ~/Library/Logs/HoshiStream/server.log; terminal launchers and Windows use the resolved state folder's logs directory. Logs can contain media names, paths, and network context even when tokens are intentionally redacted.

Read-only checks without putting a token in a command

Use your configured port. /health checks the add-on process; /ready also checks TorrServer. Run the LAN check from a separate trusted-LAN device when possible, replacing the example address. These checks do not validate a private catalog, codec, or sustained stream.

macOS shell

curl --fail --show-error http://127.0.0.1:7001/health
curl --fail --show-error http://127.0.0.1:7001/ready
curl --fail --show-error http://192.168.1.50:7001/health

Windows PowerShell

Invoke-RestMethod http://127.0.0.1:7001/health
Invoke-RestMethod http://127.0.0.1:7001/ready
Invoke-RestMethod http://192.168.1.50:7001/health

Report only the minimum, privately

The release/support owner is MajorJohn98. The designated private feedback channel is not yet operational; do not substitute public issues or unsolicited email for a private report. Once an approved channel is provided, report the build ID, OS and exact player/browser versions, source type, steps, expected/actual behavior, approximate time, and a minimal sanitized error excerpt.

Do not attach .env, raw logs, authorization headers, private URLs, magnets, .torrent files, library exports, backups, network captures, or screenshots with address bars/media paths. Replace sensitive context locally with [redacted] and inspect the whole report before sending. For suspected data loss or credential exposure, stop the affected service and preserve state privately. Removing a leaked message does not revoke credentials; coordinate deliberate recovery and client-URL replacement.

Detailed references: troubleshooting, private support and incident handling, and backup and recovery.