Install and Set Up HomeButler for Remote Monitoring

What HomeButler does in a homelab

HomeButler is designed for operating a small home server without requiring a permanent database or an always-on HomeButler daemon. It can inspect the host from the command line, return structured JSON for automation, generate health reports, scan containers and ports, and provide a web dashboard. Its emphasis is not limited to showing a live graph. HomeButler records report snapshots so that subsequent reports can explain what changed relative to the previous state.

This distinction is useful in homelabs because many operational problems are changes rather than absolute values. A container might restart unexpectedly, a service might begin listening on a new port, a disk might approach capacity, or a backup might exist without having been tested. HomeButler provides narrowly scoped commands for examining these conditions instead of requiring unrestricted shell access for every routine question.

The project documents several interfaces: a conventional CLI, JSON output, a terminal dashboard, a browser dashboard, and MCP support for AI tools. This guide focuses on the CLI and browser dashboard. The browser service is particularly relevant to remote monitoring because homebutler serve creates a local HTTP endpoint that can be tested in a browser before any external connectivity is introduced.

HomeButler can also inspect Docker environments, diagnose containers, interact with supported homelab workflows, and provide visibility into supported Proxmox resources. The exact information available on a particular machine depends on what is installed, what the current user can inspect, and what was configured during initialization. An empty container list, for example, is not necessarily an installation failure if Docker is absent or no containers are running.

Prerequisites and deployment decisions

Install HomeButler on the server or workstation whose homelab resources you want it to inspect. Because it gathers host information and can inspect local services, placing it on an unrelated computer would not provide the same view unless that computer was separately configured to reach the intended servers.

The official installation script says that it automatically detects the operating system and architecture, but the supplied project documentation does not provide a complete support matrix. We therefore should not assume that every processor, operating system release, or shell environment is supported. If the script reports that the platform is unsupported, use a release artifact documented for that platform or consult the current project release information rather than substituting an unverified binary.

Choose one of the documented installation paths:

You also need a terminal session with permission to install software and run the resulting executable. HomeButler describes itself as a single Go binary with zero runtime dependencies, but the installation path can still have its own prerequisites. The shell method requires curl and a compatible shell, Homebrew requires Homebrew, and the npm method requires Node.js and npm.

For the browser dashboard, you need an available local TCP port. HomeButler uses port 8080 by default. If another process already owns that port, select another unused port with the documented --port option when starting the dashboard. You should also know whether local host firewall rules permit browser access from the location where you intend to test it.

Remote access introduces a separate prerequisite. The Localtonet client must run on the same device as HomeButler or on a device that can reach HomeButler's listening address and port. Since the documented default URL is localhost:8080, running our client on the HomeButler host is the clearest setup for this guide. The Localtonet device also needs outbound internet connectivity so that our client can establish its connection to a relay server.

Install HomeButler

Use only one installation method for the initial setup. Running every installer is unnecessary and can create confusion about which executable your shell resolves. After installation, verify the command before moving to interactive configuration.

Option 1: Install with the official shell script

The project's quick-start documentation provides this command:

curl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh

The installer is documented as automatically detecting the operating system and architecture. The available evidence does not enumerate every supported combination, so read any platform or architecture error literally rather than forcing a binary intended for a different system.

Option 2: Install with Homebrew

If Homebrew is already part of your package-management workflow, use the documented tap and formula:

brew install Higangssh/homebutler/homebutler

A package manager can make future upgrades and package tracking easier within environments already managed by Homebrew. This command does not imply that Homebrew is available on every HomeButler-compatible platform.

Option 3: Install through npm

HomeButler's release information also documents a global npm installation:

npm install -g homebutler

Use this path only where Node.js and npm are already installed and the global npm binary directory is available through the shell's command search path. The HomeButler program itself is described as a Go binary, but this distribution method still relies on npm for installation.

Confirm the executable

A direct status check verifies both command discovery and basic execution:

homebutler status

This command reports CPU, memory, disk, and uptime information. At this point, you are only confirming that HomeButler starts and can inspect basic host state. Server definitions and other configuration should be handled by initialization next.

Initialize and validate HomeButler

Run the documented interactive setup:

homebutler init

Follow the prompts shown by your installed version and add the servers appropriate to your homelab. Prompt wording and available options can change between releases, so this guide does not invent field names or fixed answers that are not present in the supplied project evidence. Enter only addresses and credentials that match your own environment, and do not copy secrets into screenshots, support posts, or tunnel descriptions.

After initialization, validate the effective configuration:

homebutler config validate

Configuration validation is especially important because the project documents two potentially quiet failure modes. An unrecognized configuration key can be ignored, and a nonexistent path supplied through a configuration option can fall back to built-in defaults rather than failing immediately. Validation reports which file was used, how it was resolved, and how HomeButler interpreted each section.

For a more conservative automation check, use strict validation:

homebutler config validate --strict

Strict mode exits unsuccessfully on warnings as well as errors. This makes it useful in scripts or scheduled checks where a warning should prevent the workflow from continuing unnoticed. For structured processing, request JSON:

homebutler config validate --json

Create an initial report baseline

HomeButler's change reporting becomes more useful after it has a saved baseline. Run:

homebutler report

On the first run, HomeButler creates a baseline under ~/.homebutler/reports/snapshots/. Later reports compare the current state against the latest snapshot. The documented default retains 30 snapshots and prunes older entries so that report history does not grow indefinitely.

You can select another retention count:

homebutler report --keep 7

To preview a report without writing another snapshot, use:

homebutler report --no-save

The first report cannot identify a meaningful historical change because no earlier snapshot exists. Treat it as the reference point, then run another report after an actual service, container, port, or resource change.

Verify HomeButler before starting remote access

Verification should proceed from simple host inspection to the features relevant to your environment. A successful command is more informative than merely checking that a binary file exists because it confirms that HomeButler can execute under the current user and inspect at least part of the system.

Check host status

homebutler status

If you plan to consume results in an automation workflow, verify the JSON form independently:

homebutler status --json

A human-readable command can appear correct while a downstream script still depends on structured output, so test the same format that your automation will consume.

Inspect containers and ports

homebutler docker list
homebutler inventory scan

The inventory result is a valuable security checkpoint. Compare the listening ports and discovered services with your intended design. An unexpected public bind port should be investigated before adding any new remote-access path.

Machine-readable inventory output is available as well:

homebutler inventory scan --json

Run the doctor check

homebutler doctor

The doctor command is a read-only preflight designed to identify common homelab concerns, including high disk or memory usage, stopped containers, public ports, stale or missing backups, missing notifications, and whether a report baseline exists. Findings name a next command to run, which helps turn a warning into a focused investigation.

For cron or CI-style checks where warnings and failures should produce a nonzero exit status, use:

homebutler doctor --strict

JSON is also documented:

homebutler doctor --json

Start and test the HomeButler web dashboard

Start the browser interface with:

homebutler serve

The documented default address is:

http://localhost:8080

Keep the terminal process running and open that address in a browser on the same machine. Confirm that the page loads and that expected homelab information appears. Test more than the initial HTML response. Navigate through the dashboard views relevant to you, confirm that status information populates, and verify that any expected container or port data agrees with the CLI.

The localhost name refers to the machine making the request. If HomeButler runs on a server but the browser runs on a laptop, entering localhost:8080 on the laptop points to the laptop, not the server. The documented evidence establishes the local endpoint but does not establish a HomeButler bind-address option or LAN-listening default. We therefore do not recommend guessing an undocumented flag. Test directly on the host, or use a browser arrangement that can access that host-local service.

Use another port when 8080 is occupied

HomeButler documents a --port option for selecting a custom port. For example:

homebutler serve --port 9090

With that example, the local browser target becomes http://localhost:9090. Use an available port appropriate to your environment, and remember to configure the same port as the Localtonet local target later.

Understand the dashboard process lifecycle

HomeButler does not require an always-on daemon for its general CLI workflows. The web dashboard is different in one practical respect: the homebutler serve process must remain running while you want the dashboard available. Closing its terminal, ending the process, rebooting the machine, or stopping HomeButler makes the HTTP endpoint unavailable.

The supplied evidence does not establish an official system service definition, startup task, container deployment procedure, or process supervisor configuration for homebutler serve. Rather than inventing one, this guide keeps it in the foreground during initial testing. If you later make the process persistent, use a service-management method appropriate to your verified operating system and review the current HomeButler documentation for any official recommendation.

Connect the working dashboard to Localtonet

After the dashboard works at http://localhost:8080, an HTTP tunnel can make that local endpoint reachable through a public HTTPS address. With Localtonet, our client establishes an outbound connection to a Localtonet relay server. This avoids inbound router port forwarding, a public IP requirement, firewall changes for inbound forwarding, and VPN setup.

The tunnel does not move HomeButler into our infrastructure. HomeButler continues to run on your machine, and the tunnel forwards requests to the local IP address and port you configure. The tunnel remains available only while the selected Localtonet client is connected, the HomeButler dashboard is running, and the tunnel itself has been started.

Current server codes, available regions, process types, and subscription-dependent options must be selected from the current Localtonet dashboard. Do not copy a server identifier from an old tutorial or guess a value.

For the current dashboard workflow, see our Localtonet HTTP tunnel documentation. Use the live documentation and dashboard for current field names, available relay selections, and domain requirements.

Security considerations for remote homelab monitoring

A homelab dashboard can reveal hostnames, service names, container state, listening ports, topology, resource usage, and operational warnings. Some HomeButler workflows can also perform management actions. This makes dashboard exposure more sensitive than publishing a static test page.

The supplied HomeButler documentation does not establish whether the web dashboard provides built-in user authentication, role-based authorization, session controls, or an access-control configuration appropriate for internet exposure. Localtonet provides the connectivity path and a public HTTPS address for an HTTP tunnel, but a tunnel is not a substitute for application authorization. HTTPS protects the public HTTP connection at the tunnel edge, while access policy still determines who should be allowed to use the application.

Keep the Localtonet device token private. It identifies the client device and should be handled like a credential. Do not include it in command examples, tickets, public repositories, terminal recordings, or screenshots. If you suspect that a token was disclosed, use the current Localtonet account controls and documentation to address the affected device rather than continuing to rely on the exposed value.

Apply least privilege to the operating-system account that runs HomeButler. Permissions influence which host resources, container sockets, service managers, and files the process can inspect or control. Grant only the access needed for the workflows you actually use. Remote convenience does not justify giving a monitoring process unrestricted host access without review.

Run homebutler inventory scan and homebutler doctor before exposure. Investigate unexpected public bind ports, stopped services, resource pressure, and backup warnings. These checks do not prove that a host is secure, but they can reveal conditions that should be resolved before another remote entry point is added.

Stop or delete access when it is no longer required

A Localtonet tunnel can be stopped and later started again. Stop it when maintenance is complete or when the dashboard should return to local-only use. Delete it when the configuration is no longer needed. Remember that stopping HomeButler and stopping the Localtonet tunnel are separate actions: the local service process controls whether the dashboard exists, while the tunnel controls whether the configured remote path is active.

Routine operation and maintenance

Once installation and remote access are working, routine checks help distinguish application problems from tunnel problems. Start with HomeButler locally, then test Localtonet. This order avoids troubleshooting two layers at the same time.

Recommended startup sequence

1. Start the HomeButler dashboard with homebutler serve or your selected custom port.
2. Open the local URL and verify that the dashboard responds.
3. Confirm that the Localtonet client device is connected.
4. Review the tunnel target and start the tunnel.
5. Test the public address and confirm that the expected dashboard appears.

Recommended shutdown sequence

1. Stop the Localtonet tunnel so that new remote requests no longer reach the dashboard.
2. Finish any local HomeButler work.
3. Stop the homebutler serve process if the dashboard is no longer needed.

Refresh reports and compare changes

Run homebutler report after meaningful maintenance, such as changing a container deployment or resolving a host problem. HomeButler compares the current report with the most recent saved snapshot. Use --no-save when you want to inspect the result without changing the comparison baseline, and adjust --keep when the default retention of 30 snapshots is not appropriate for your workflow.

Use JSON intentionally

JSON output is available throughout HomeButler's documented workflows, including status, inventory, reports, doctor checks, and configuration validation. Treat JSON as a stable machine-consumption interface only to the extent guaranteed by the HomeButler version you deploy. When upgrading, test scripts against the new version before relying on them for alerts or automated decisions.

Upgrade carefully

The project documents this upgrade command for an existing installation:

homebutler upgrade

Before upgrading a remotely used dashboard, record the currently working version and configuration, stop unnecessary public exposure, and verify the CLI and local dashboard after the upgrade. Only restart the Localtonet tunnel after the new HomeButler process has passed local testing.

Installation through a package manager can have its own update conventions. Avoid mixing a self-upgrade command with a separate package manager unless the current project guidance explicitly supports that combination. Multiple installations can leave more than one homebutler executable on the machine, making behavior depend on shell path order.

Troubleshooting HomeButler and the HTTP tunnel

The shell says that homebutler is not found

First confirm that the selected installer completed without an error. Open a new terminal so that package-manager path changes can take effect. If more than one installation method was attempted, inspect which executable directory is expected to contain HomeButler and remove ambiguity before continuing. Do not repeatedly execute different installers without understanding where each one places the command.

Configuration validation reports unexpected defaults

Run:

homebutler config validate

Read the reported configuration source and resolution rule. The project warns that a nonexistent explicit configuration path can fall back to built-in defaults. Validation can also identify unrecognized keys and suggest likely spelling corrections. Correct the source configuration, validate it again, and only then repeat operational tests.

Docker or inventory data is missing

Confirm that Docker is installed if you expect Docker data, that containers are actually present, and that the current user has appropriate access. Compare homebutler docker list with homebutler inventory scan. Missing container information does not necessarily mean the HomeButler binary is broken, since the host might not have the expected runtime or the current account might not be able to inspect it.

Port 8080 is already in use

Start HomeButler on another available port with its documented port option:

homebutler serve --port 9090

Replace 9090 with an appropriate available port if necessary. Test the new local URL, then update the Localtonet HTTP tunnel's local target port to exactly the same value. A port mismatch commonly produces an unreachable tunnel even when both applications are otherwise running.

The local dashboard does not load

Check the terminal running homebutler serve. It must remain active. Verify that you are opening the URL on the same machine when using localhost, and confirm that the selected port matches the startup command. If the process exits, use its displayed error rather than troubleshooting Localtonet, since a tunnel cannot forward to a service that is not listening.

The local dashboard works, but the public URL does not

Verify each layer in order:

1. Confirm that homebutler serve is still running.
2. Reload the local URL on the HomeButler machine.
3. Confirm that the Localtonet client is connected under the selected device token.
4. Check that the HTTP tunnel points to 127.0.0.1 and the actual HomeButler port.
5. Confirm that the tunnel was started, not merely created.
6. Use the public URL currently assigned in the dashboard.

If our client runs on a different computer, 127.0.0.1 points to that other computer, not the HomeButler server. The available evidence does not document the HomeButler bind configuration needed for a separate-client LAN arrangement, so move the Localtonet client to the HomeButler host or consult current HomeButler documentation rather than guessing a network-listening option.

The public URL opens the wrong application

Stop the tunnel immediately. Check whether HomeButler stopped and another process later acquired the configured port. Confirm the local target directly before restarting remote access. This is one reason to verify both the page identity and its actual dashboard data rather than accepting any successful HTTP response as proof.

The tunnel becomes unavailable after closing a terminal

Determine which process was closed. If the HomeButler terminal ended, the web dashboard is no longer listening. If the Localtonet client ended, the outbound relay connection is unavailable. If the tunnel was stopped in the dashboard, it must be started again. All three components must be active: HomeButler, our connected client, and the HTTP tunnel.

The report does not show any changes

The first saved report establishes a baseline. A later report needs a meaningful difference from the latest snapshot before it can describe a change. Also check whether a previous command used --no-save, which intentionally avoids writing a snapshot. Use ordinary homebutler report when you want the current state retained for later comparison.

Frequently asked questions