Run HomeGenie interactively or headlessly on Windows, verify its local web interface, and provide deliberate remote access
HomeGenie is a portable, local-first automation server with a browser-based interface for connected devices, dashboards, programs, and local AI features. Current primary HomeGenie documentation verifies installation from a Windows ZIP, interactive startup through start.bat, graceful shutdown with CTRL + C, and headless startup by removing the --start-browser argument. It does not currently provide a verified Windows service registration, service name, account configuration, restart, removal, or upgrade procedure. This corrected guide therefore covers the supported interactive and headless Windows workflow, then shows how to publish the verified local HTTP endpoint through a Localtonet HTTP tunnel without claiming that HomeGenie includes a documented Windows service installer.
📋 What's in this guide
What is verified for HomeGenie on Windows
HomeGenie's current project documentation describes the application as a portable installation. For Windows, the documented setup is to select a release ZIP for the appropriate hardware, extract the complete archive, locate the included homegenie directory and startup script, and double-click start.bat. The supplied script passes --start-browser to the HomeGenie executable, which opens the interface as a desktop-style Progressive Web App. Pressing CTRL + C in the terminal gracefully stops the application.
The documentation also explains how to use a traditional server-only or headless mode. Edit the startup script and remove the --start-browser argument from the execution command. This prevents the automatic desktop window from opening, but HomeGenie still runs from the associated terminal session. Headless mode in this context does not automatically mean Windows service mode, background startup at boot, or operation after the launching session is terminated.
Current primary evidence does not establish an official HomeGenie Windows service procedure. In particular, it does not identify a service installer, registration command, service name, required working directory, supported service account, startup type, log location, status check, restart command, removal procedure, or service-aware upgrade sequence. Those details cannot be inferred safely from the portable ZIP workflow.
Do not register HomeGenie with sc.exe, PowerShell, Task Scheduler, or a third-party service wrapper based only on this article. Each approach introduces its own executable-path, working-directory, account, logging, shutdown, and upgrade behavior. Until HomeGenie publishes a current official service procedure, such a configuration is an administrator-managed customization rather than a verified HomeGenie installation method.
This distinction matters for remote access. A Localtonet tunnel can forward traffic only while HomeGenie is running and reachable from the Localtonet client. Localtonet does not convert an interactive application into a Windows service, restart HomeGenie, or keep it alive after its terminal closes. If unattended startup after a reboot is mandatory, establish and test a separately supported process-management strategy before relying on remote access.
How HomeGenie and Localtonet fit together
HomeGenie and Localtonet perform separate jobs. HomeGenie hosts the automation environment and web interface on a Windows computer you control. The Localtonet client establishes an outbound connection from a device on the private network to a Localtonet relay server. An HTTP tunnel maps its public HTTPS address to the local IP address and port where HomeGenie is already listening.
This design removes the need for inbound router port forwarding, a public IP address, firewall changes for an internet-facing inbound port, or VPN setup. It does not remove the requirement for a functioning local application. HomeGenie must start successfully, and its HTTP endpoint must be reachable from the device running our client.
start.bat script.
Local and remote request paths
During local use, the browser connects directly to HomeGenie's HTTP endpoint. During remote use, the browser opens the public address assigned to the Localtonet HTTP tunnel. Our relay sends the request through the connected Localtonet client, which forwards it to the configured HomeGenie target.
The tunnel is available only while the selected client is connected and the tunnel is running. HomeGenie must also remain active. Closing the HomeGenie terminal, pressing CTRL + C, putting Windows to sleep, shutting down the computer, or losing network connectivity interrupts the complete path.
Standard HTTP tunneling is not a VPN. It publishes the configured web service rather than joining remote devices to the entire private network. Localtonet VPN Manager is the separate feature for a private mesh VPN and LAN-bridging workflow.
Test HomeGenie on the Windows host first. If our client will run on another device, test the same endpoint from that device next. Only after both checks succeed should you create and start the public tunnel.
Prepare the Windows host
Choose a Windows computer that can stay powered on for as long as remote access is needed. HomeGenie and the Localtonet client consume different parts of the connection path, but both must remain available. Review Windows sleep and power settings so the host does not suspend unexpectedly during the intended access period.
HomeGenie publishes multiple Windows x64 packages. Select the package according to the computer's hardware and the acceleration features you intend to use. Installing a GPU-oriented package is not automatically beneficial if the required hardware or driver stack is absent.
| Windows package | Intended use | Selection guidance |
|---|---|---|
win-x64 |
Standard CPU-only operation | Use for maximum compatibility, older computers, headless servers, or systems without a dedicated GPU. |
win-x64-cuda12 |
NVIDIA GPU acceleration | Use with a suitable NVIDIA GPU and up-to-date NVIDIA drivers when accelerated LLM and vision workloads are required. |
win-x64-vulkan |
GPU acceleration on supported AMD, Intel, or NVIDIA hardware | HomeGenie identifies Vulkan for LLM workloads and DirectX 12 through DirectML for vision on Windows. |
Choose a permanent installation directory
HomeGenie is portable, so the extracted directory is the installation. Choose a stable location rather than launching it from a temporary download directory. Keep the archive's directory structure intact because the startup script and application can depend on files stored beside the executable.
The Windows account launching HomeGenie needs access to that directory and to any hardware, local files, cameras, network resources, or other integrations used by the automation system. Begin with an ordinary interactive launch under the intended account. This makes startup messages visible and avoids combining basic installation problems with an unverified background-launch mechanism.
Plan the network placement
The simplest arrangement is often to run HomeGenie and the Localtonet client on the same Windows computer. In that case, our client only needs to reach HomeGenie's local listener on that host. You can instead run Localtonet on another always-on device, but that device must be able to connect to the HomeGenie endpoint across the LAN.
A browser test on the HomeGenie computer does not prove that another client device can reach the same endpoint. Listener binding, Windows Firewall, network profiles, VLANs, guest-network isolation, and other local policies can affect cross-device access. Resolve that local path before introducing the tunnel.
HomeGenie's project guidance recommends a restricted, sandboxed environment because its advanced automation and AI engines can generate, compile, and execute code. Grant the Windows account only the files, devices, and network resources needed by the intended automation workload.
Install and start HomeGenie on Windows
The following sequence reproduces the current documented Windows installation path. Complete the first launch interactively even if you later intend to use headless mode. The visible terminal provides the best opportunity to identify extraction, dependency, hardware, and startup problems.
Download the appropriate Windows release ZIP
Choose win-x64, win-x64-cuda12, or win-x64-vulkan according to the host hardware and intended acceleration path. Use the standard package for a CPU-only system or when compatibility is the priority.
Extract the complete archive
Unzip the release into the permanent installation directory. Do not run individual files from inside the ZIP, and do not flatten or partially copy the extracted directory structure.
Run the supplied Windows startup script
Open the extracted folder and double-click start.bat. Keep the terminal open during the initial test and inspect any messages it displays. The default script includes --start-browser, so HomeGenie normally opens its interface as a desktop-style PWA.
If HomeGenie is already running in the background and you launch the startup script again, the documented behavior is to open another application window connected to the existing session rather than starting a second server. Even so, avoid repeatedly launching the script while diagnosing startup. First establish which terminal and process correspond to the active instance.
To stop the interactively launched server gracefully, focus its terminal and press CTRL + C. Wait for the process to exit before updating files, changing the script, or starting a new instance.
Keep the portable package structure intact. Do not remove files simply because they do not look like the primary executable, and do not move the startup script away from the extracted application without current project instructions supporting that change.
Run HomeGenie in documented headless mode
HomeGenie's default script opens the web interface automatically because it passes the --start-browser argument. For a traditional server-only or headless experience, the project documents editing the startup script and removing that argument from the execution command.
Make a backup copy of the original script before editing it. Change only the documented browser argument, preserve the rest of the command, and save the file in its original directory. Then run the edited script interactively and verify that the backend starts without opening the PWA window.
Stop the current HomeGenie process
In the terminal running HomeGenie, press CTRL + C and wait for a graceful exit. Do not edit or retest the script while an older instance is still active.
Back up and edit start.bat
Preserve an original copy, then remove the --start-browser argument from the HomeGenie execution command. Leave the executable path and other script content unchanged unless current HomeGenie documentation instructs otherwise.
Launch and verify the headless process
Run the edited script. Confirm that HomeGenie starts in the terminal without automatically opening the PWA, then open its local web interface manually in a browser.
Headless mode still depends on the launched process. Closing or terminating its terminal may stop HomeGenie, depending on how the session is managed. The documented removal of --start-browser changes browser-launch behavior only. It does not establish service installation, automatic startup, crash recovery, or operation independent of the launching session.
Why a generic Windows service recipe is not included
A reliable service tutorial must specify more than how to run an executable. It must establish the supported executable and arguments, service name, startup mode, working directory, account, file permissions, logging destination, stop semantics, restart behavior, removal process, and upgrade procedure. None of those service-specific HomeGenie details are established by the current primary evidence.
Generic wrappers may also handle graceful shutdown differently from the documented CTRL + C workflow. An incorrect working directory can cause a portable application to look for files in the wrong location. Running under a system account can change access to profiles, mapped drives, cameras, serial devices, configuration files, and network resources. For those reasons, we do not present a speculative service command.
Find and verify the local HomeGenie endpoint
The current evidence supplied for this guide does not verify a fixed default HomeGenie port, automatic fallback from port 80, or a documented serviceaddress.txt discovery mechanism. Do not assume port 80 or 8080, and do not configure the tunnel from a filename whose current behavior has not been established.
Instead, identify the actual HTTP address presented by the running release. Use the address opened by the supplied startup workflow, the startup information displayed by the running application, or the current HomeGenie configuration and documentation for that release. Record the host and port separately. The required value is the endpoint that the Localtonet client can actually reach, not a historical default from another version.
Test on the Windows host
Open the identified HomeGenie address in a browser on the server. Confirm that the expected interface loads, navigation works, and repeated refreshes continue to succeed. If you edited start.bat for headless mode, perform this test after launching the edited script so you know the backend works without the automatic PWA launch.
Keep the HomeGenie terminal visible during this test. If the browser fails, review the startup output before changing firewall rules or creating a tunnel. Confirm that the process did not exit, that you are using the address from the active release, and that another HomeGenie instance is not confusing the test.
Test from the Localtonet client device
If Localtonet will run on the same Windows computer, verify that the target is reachable there. If Localtonet will run on another device, open or otherwise test the same HomeGenie endpoint from that device. A target bound only to loopback on the HomeGenie host will not be reachable from a separate LAN device.
| Verification point | Expected result | If it fails |
|---|---|---|
| HomeGenie terminal | The process remains active without a startup error | Review extraction, package selection, dependencies, permissions, and visible startup messages. |
| Browser on the Windows host | The HomeGenie interface loads at the identified address | Confirm the current address and port, then resolve the application listener before configuring Localtonet. |
| Test from a separate client device | The endpoint responds from the device that will run Localtonet | Check listener binding, Windows Firewall, LAN routing, network profile, and device isolation. |
| Headless launch | The backend remains reachable without an automatic PWA window | Compare the edited script with the original and confirm only --start-browser was removed. |
Localtonet needs a local IP address and port, such as the endpoint already proven from the client device. Do not enter the future Localtonet public URL as the local target, and do not guess a HomeGenie port.
Connect HomeGenie with a Localtonet HTTP tunnel
Once the HomeGenie interface works from the intended client device, follow the documented Localtonet HTTP tunnel workflow. Install our client, select the corresponding device token, select an available relay server, configure the HTTP tunnel with the verified local target, and explicitly start the tunnel.
HTTP tunnels may use Random Sub Domain, Custom Sub Domain, or Custom Domain as their process type. All three serve the configured target content at a public HTTPS address. Availability can vary by current product configuration or subscription. If using a custom domain, follow the current DNS instructions rather than copying records from an older tutorial.
Install and run the Localtonet client
Install the appropriate Localtonet application on the Windows HomeGenie host or another device that can reach HomeGenie. Start the client so it can establish its outbound connection to our platform.
Open the HTTP tunnel configuration
In the Localtonet dashboard, create an HTTP tunnel and select the required process type from the options currently available to your account.
Select the device authentication token
Select the AuthToken for the client device that will run this tunnel. Tokens are device-specific credentials. Do not paste them into public examples, screenshots, repositories, or browser-accessible files.
Select an available relay server
Choose a currently available server or region from the dashboard. Obtain the value from the current product interface rather than hardcoding a server code from an older guide.
Enter the verified HomeGenie target
Configure the local IP address and port that succeeded during local testing. If Localtonet runs on another device, use an address reachable from that device rather than a loopback-only address on the HomeGenie host.
Start the tunnel
Creating the tunnel does not make it active. Press Start and confirm that the selected client is connected and the tunnel is running. The tunnel can later be stopped or deleted from the dashboard.
Verify the public address externally
Open the assigned public address from a genuinely external connection, such as a phone with Wi-Fi disabled. Confirm that the expected HomeGenie interface loads and that ordinary navigation works.
For the current dashboard fields and HTTP-specific options, consult the Localtonet HTTP tunnel documentation. Exact options can change with the product, client version, plan, or selected process type, so use the values shown in your current dashboard.
Test lifecycle behavior
Stop the tunnel and verify that the public endpoint is no longer available, then start it again and confirm recovery. Separately stop HomeGenie with CTRL + C and confirm that the tunnel can no longer reach its target. Relaunch HomeGenie, verify it locally, and retest the public address. These checks distinguish tunnel lifecycle problems from application lifecycle problems.
Secure remote HomeGenie access
A local-first application becomes publicly reachable when connected to a public HTTP tunnel. The outbound tunnel architecture avoids direct router port forwarding, but it does not replace authentication or authorization in the application. Review HomeGenie's current access controls before starting the tunnel and expose only the endpoint needed for remote use.
Do not rely on an unguessable-looking public URL as the sole protection. Treat HomeGenie as a sensitive control surface. Depending on the installation, it can reveal automation state or control lights, cameras, sensors, relays, heating, locks, and other connected equipment.
Protect both control layers
The Localtonet dashboard manages the tunnel configuration, device assignment, and lifecycle. HomeGenie manages its users, application behavior, automation data, and connected devices. Protect both layers independently. A protected Localtonet account does not compensate for weak HomeGenie access controls, and HomeGenie credentials do not make it acceptable to expose a Localtonet device token.
Avoid broad Windows privileges
Do not use an administrator account merely to suppress a startup or integration problem. Broad privileges can increase the impact of an application, script, or automation error. HomeGenie's programmable capabilities make account isolation and deliberate file permissions especially important.
Handle updates conservatively
Stop HomeGenie gracefully before replacing release files. Preserve application data and configuration according to the current HomeGenie upgrade guidance for the version being installed. Because the application is distributed as a portable ZIP, do not assume that copying selected binaries into an active installation is a supported upgrade.
After every update, launch HomeGenie locally and identify its active HTTP endpoint again. Verify the local interface before starting or reusing the tunnel. If the host or port changes, update the Localtonet target only after the new endpoint has passed local testing.
Apply strong access controls, avoid sharing the tunnel URL publicly, and verify remote actions carefully. Do not rely on remote operation alone for safety-sensitive equipment or any system that requires guaranteed availability.
Routine operation and troubleshooting
Use a consistent startup and health-check order
Start HomeGenie first and confirm its local interface. Start or confirm the Localtonet client next, then start the HTTP tunnel. Finally, test the public address. This order prevents an unavailable HomeGenie target from being misdiagnosed as a tunnel problem.
After a Windows reboot, do not assume that HomeGenie resumed automatically. The verified HomeGenie workflow in this guide is interactive or headless startup through start.bat, not a Windows service. Launch it using the documented script, confirm the endpoint, and then check the Localtonet client and tunnel.
The HomeGenie interface does not open
Return to the terminal used to start HomeGenie. Confirm that the process remains active and inspect its visible messages. Make sure the release was fully extracted, the correct Windows package was selected, and required GPU drivers are present if using an accelerated package.
If you edited the startup script, compare it with the backup. For the documented headless change, only the --start-browser argument needs to be removed. Restore the original script and retest if other command content was changed accidentally.
The PWA window does not appear
If the original script still includes --start-browser, verify that HomeGenie completed startup. If you intentionally removed that argument, the missing PWA is expected. Open the identified local HTTP address manually in a browser to verify the backend.
HomeGenie works on the server but not from the Localtonet client device
This indicates a local reachability problem. The HomeGenie listener may accept only loopback connections, Windows Firewall may block traffic from the LAN, or network segmentation may isolate the devices. If practical, running the Localtonet client on the HomeGenie host can avoid the need for a cross-device LAN path. Otherwise, resolve the local listener and firewall policy before creating the tunnel.
Local access works but the public address fails
Confirm that the working local test was performed from the same device that runs the Localtonet client. Then check that the correct device token is selected, the client is connected, and the tunnel has been started. Compare the configured local IP address and port with the endpoint that actually succeeded.
Remember that creating or saving a tunnel does not start it. Press Start and wait for the current connection state before testing externally. If the tunnel was stopped or the selected client disconnected, the public endpoint will not reach HomeGenie.
The tunnel stopped working after a reboot
Check each dependency independently. Confirm that Windows is awake and connected, launch HomeGenie, verify its current local endpoint, confirm that the selected Localtonet client is connected, and confirm that the tunnel is running. If the HomeGenie endpoint differs from the saved tunnel target, verify the new endpoint before updating the configuration.
HomeGenie stops when the terminal closes
The documented Windows workflow launches HomeGenie from start.bat. Removing --start-browser suppresses the automatic PWA window but does not make the application a Windows service. Keep the required process session active, or adopt a separately verified process-management method for your environment. Do not interpret headless mode as proof of session-independent execution.
A second launch opens another app window
This matches HomeGenie's documented behavior when it detects that the server is already running. The second launch connects another app window to the existing session instead of starting another server. Use the original terminal when you need to stop the active process gracefully.
| Symptom | Likely area | Next check |
|---|---|---|
| HomeGenie exits during startup | Package, extraction, dependency, or local permission issue | Review terminal output, package selection, directory contents, and required hardware drivers. |
| No PWA opens after script editing | Expected headless behavior | Open the local HTTP endpoint manually and verify that the backend is still active. |
| Local browser cannot connect | HomeGenie process, endpoint, or listener | Confirm the process is active and identify the address exposed by the current running release. |
| Server access works but client-device access fails | LAN reachability | Check binding, Windows Firewall, network profile, routing, and network isolation. |
| Local access works but public access fails | Localtonet device, tunnel state, or target | Confirm the selected client is connected, press Start, and compare the configured target with the verified endpoint. |
| Remote access fails after reboot | Process startup or tunnel lifecycle | Start HomeGenie, verify it locally, reconnect the Localtonet client, and confirm that the tunnel is running. |
Frequently asked questions
Does HomeGenie currently document an official Windows service installation?
The current primary evidence used for this guide documents portable ZIP installation, startup through start.bat, graceful shutdown with CTRL + C, and headless behavior by removing --start-browser. It does not establish a complete Windows service registration, management, removal, or upgrade procedure, so this article does not claim official service support.
Is HomeGenie's headless mode the same as running it as a Windows service?
No. The documented headless change removes the --start-browser argument so the PWA does not open automatically. It does not register a Windows service, configure startup at boot, select a service account, or guarantee that HomeGenie continues after the launching session ends.
What is HomeGenie's default HTTP port?
The current evidence supplied for this guide does not verify a fixed default or fallback port. Use the address exposed by the running release, its startup information, or current HomeGenie configuration guidance. Verify the endpoint in a browser before entering its host and port in Localtonet.
Should I use serviceaddress.txt to find the HomeGenie endpoint?
This guide does not rely on serviceaddress.txt because its current behavior is not established by the supplied primary evidence. Identify and verify the endpoint provided by the running HomeGenie release instead of assuming that a historical discovery file remains authoritative.
Can Localtonet run on the same Windows computer as HomeGenie?
Yes. Running our client on the HomeGenie host often simplifies local connectivity. It may also run on another device, but that device must be able to reach HomeGenie's local IP address and port across the LAN.
Does remote HomeGenie access require router port forwarding?
No. The Localtonet client establishes an outbound connection to our relay, so this workflow does not require an inbound router forwarding rule, a public IP address, firewall exposure of an internet-facing port, or VPN setup.
Does creating a Localtonet tunnel make it active immediately?
No. Creating the configuration does not mean the tunnel is running. The selected client must be connected and the tunnel must be started with the Start button. It can later be stopped or deleted.
Will the public address work while Windows is asleep?
No. HomeGenie must be running, the selected Localtonet client must remain connected, and the tunnel must be active. Sleep, shutdown, network loss, or termination of either process makes the endpoint unavailable.
Is a Localtonet HTTP tunnel a VPN?
No. An HTTP tunnel publishes a specific local web service through a public address. Localtonet VPN Manager is the separate feature for a private mesh VPN and LAN-bridging use cases.
Connect your verified HomeGenie endpoint with Localtonet
Install HomeGenie from its Windows ZIP, start it with the documented script, verify the actual HTTP endpoint locally, and use that working IP address and port as the target of a Localtonet HTTP tunnel. Keep the device token private, start the tunnel only when remote access is needed, and test the result from outside your local network.
Get Started Free →
