Build a self-hosted monitoring dashboard, verify it locally, and then publish only the status page you intend to share
Kuvasz is an open-source uptime and SSL monitoring service with HTTP, heartbeat, ICMP, TCP, and DNS monitors, plus status pages, notifications, a REST API, metrics exporters, and an MCP server. This guide explains the verified deployment requirements, the information you must obtain from the version-matched Kuvasz deployment guide, local verification, status-page planning, and safe routine operation. After Kuvasz works on your own network, we show how to expose its HTTP service through Localtonet without configuring inbound router port forwarding, changing firewall rules, setting up a VPN, or requiring a public IP address.
📋 What's in this guide
What this Kuvasz and Localtonet setup does
Kuvasz monitors websites and services from infrastructure you control. Its documented monitor types include HTTP and HTTPS checks, daily SSL certificate checks, push or heartbeat monitoring, ICMP reachability checks, TCP connection checks, and DNS checks. It can notify different channels on a per-monitor basis, schedule maintenance windows, expose monitoring data through a REST API and MCP server, and export metrics to Prometheus or an OTLP-compatible system.
Status pages provide a separate presentation layer for selected monitoring information. Kuvasz supports public and private, brandable status pages. A public page can inform customers about service health, while a private page can provide an internal operational summary. This distinction matters because a status page and the Kuvasz administration interface do not have the same audience or risk profile.
Localtonet becomes relevant only after the Kuvasz web service is installed, running, and reachable locally. Our client establishes an outbound connection from the device to a Localtonet relay server. An HTTP tunnel then provides a public HTTPS address that forwards requests to the local IP address and port you configured. The tunnel remains available only while the selected device is connected and the tunnel is running.
Keep the monitoring path and publishing path separate
Kuvasz performs monitoring from the network where it runs. Localtonet publishes a reachable HTTP entry point for the Kuvasz service. Creating a tunnel does not change which targets Kuvasz can monitor, and it does not transform standard tunneling into a VPN. If Kuvasz needs to check an internal application, the Kuvasz host itself must be able to reach that application through normal routing and access controls.
The safest sequence is therefore straightforward: deploy Kuvasz, connect it to PostgreSQL, start it, open its interface locally, create at least one monitor, confirm that checks are being recorded, create the intended status page, test that page locally, and only then create an HTTP tunnel for the known local address.
Prerequisites and decisions to make first
Kuvasz is distributed as a single Docker image and requires a PostgreSQL database. The available evidence does not establish a complete Docker run command, Compose file, Kubernetes procedure, database initialization command, local port, default listening address, volume layout, environment-variable set, or initial administrator credentials. Those values must not be inferred from an image name, an example directory, or an unrelated release.
Before deployment, choose a specific Kuvasz release and use the deployment documentation for that same version. Version alignment matters because supported configuration keys, upgrade requirements, image tags, and startup behavior can change. Release 4.2.0, for example, documents this image pull command:
docker pull kuvaszmonitoring/kuvasz:4.2.0Pulling the image does not create the required PostgreSQL database, configure Kuvasz, or start a working deployment. It only downloads that tagged image. If you select another release, use its documented image tag and its matching deployment and upgrade instructions rather than substituting the example above.
| Requirement | Why it is needed | What to record |
|---|---|---|
| Container-capable host | Kuvasz is distributed as a Docker image | Host name, operating system, architecture, and container runtime version |
| PostgreSQL database | Kuvasz requires PostgreSQL to run | Database host, port, database name, and a securely stored application credential |
| Version-matched deployment configuration | Startup settings and supported keys can vary by release | Selected Kuvasz version, official deployment method, and upgrade notes |
| Persistent storage and backup plan | Monitoring history and configuration should survive routine host maintenance | PostgreSQL backup process and any documented persistent paths |
| Known local HTTP endpoint | Local verification and the Localtonet tunnel need an exact destination | Actual listening IP address, port, scheme, and status-page path |
| Localtonet client device | The client must be able to reach the Kuvasz HTTP endpoint | The selected device and its private, device-specific authentication token |
The supplied project evidence does not establish Kuvasz's local port, listening interface, database variables, initial credentials, container startup command, or status-page URL format. Obtain those exact values from the deployment guide for your chosen Kuvasz release and verify them against the running configuration. A guessed port or environment variable can produce an unavailable service, an unsafe network binding, or an accidental connection to the wrong database.
Plan the exposure boundary
Decide whether remote visitors need a public status page, a private status page, the administrative interface, an API endpoint, or a heartbeat endpoint. Do not treat these as interchangeable. A customer-facing status page usually needs narrower exposure than an administrator dashboard. The REST API, MCP server, and heartbeat endpoints can perform or receive operational actions, so publishing them requires separate authentication and authorization review.
Also decide where the Localtonet client will run. It may run on the Kuvasz host or another device that can reach Kuvasz over the local network. In either case, test connectivity from that exact device. Successful access from your laptop does not prove that a different client device can reach the same IP address and port.
Install and start Kuvasz without inventing missing settings
A responsible installation procedure must distinguish verified requirements from installation details that are release-specific. Kuvasz is containerized and requires PostgreSQL, but the available project excerpt does not contain the complete deployment guide. We can therefore document the safe installation sequence and the one evidenced image pull command, but we cannot provide a fabricated Compose file or startup command.
Choose and document a Kuvasz release
Select the version you intend to operate. Read that release's deployment and upgrade notes before changing a production installation. Record the image tag so that a later restart does not silently switch to a different version.
Prepare the PostgreSQL dependency
Provision a PostgreSQL database using the database requirements documented for the selected Kuvasz release. Create and store the required application credential securely. Do not place database passwords in shell history, public repositories, screenshots, or article examples.
Pull the selected Kuvasz image
Pull the exact documented image tag. For release 4.2.0, the evidenced command is docker pull kuvaszmonitoring/kuvasz:4.2.0. Use the tag belonging to your chosen release if it differs.
Apply the version-matched deployment configuration
Use the official deployment guide to supply the database connection, required application settings, network publication, and persistent storage exactly as documented. The evidence supplied for this article does not include those keys or paths, so they are deliberately not reproduced or guessed here.
Start Kuvasz and inspect its runtime state
Start the deployment using the documented command for your chosen method. Confirm that the container remains running and inspect its logs for database connection failures, unsupported configuration keys, migration errors, address conflicts, or startup exceptions.
Record the real local endpoint
From the running deployment, identify the actual HTTP or HTTPS scheme, listening address, published host port, and status-page path. These observed values, not assumptions, become the inputs for browser verification and the later Localtonet HTTP tunnel.
A plausible-looking container file would still be unsafe if it used an unsupported variable, incorrect image tag, wrong database URL format, nonexistent volume path, or fabricated default port. Follow the deployment configuration published for your selected release, then return to this workflow with the verified local endpoint. This limitation preserves a reproducible installation instead of hiding uncertainty behind untested commands.
Configure useful monitoring before publishing anything
Once the web interface is reachable locally, create a small monitoring baseline. Kuvasz lets you manage monitors through its user interface, REST API, or YAML configuration. Use one method consistently at first so that you know which source is authoritative. If you later combine UI, API, and infrastructure-as-code workflows, document how changes are reviewed and reconciled.
Choose the right monitor type
| Monitor type | What it tests | Typical use |
|---|---|---|
| HTTP or HTTPS | Sends HTTP requests and can evaluate availability, response behavior, and performance | Websites, APIs, dashboards, and application health endpoints |
| SSL certificate | Checks certificates daily and can notify before expiration | Public HTTPS services and certificate-renewal validation |
| Heartbeat | Waits for a push from a scheduled process | Cron jobs, backups, imports, and scheduled automation |
| Ping or ICMP | Checks host reachability and latency with ICMP echo requests | Hosts and network devices that permit ICMP |
| TCP | Attempts a TCP connection and tracks connection latency | Databases, SSH, SMTP, brokers, and other TCP listeners |
| DNS | Checks resolution, expected records, response behavior, and optional record drift | Public or internal DNS records and resolver behavior |
Start with one target whose behavior you understand. For an HTTP monitor, use a purpose-built health endpoint when the application provides one. A generic home page may return a successful status even when a database or critical dependency has failed. Conversely, an overly expensive end-to-end request can add unnecessary load when checked frequently.
Configure notifications deliberately. Kuvasz supports multiple channels and allows channel selection per monitor. Route a test monitor to a non-disruptive destination first, verify delivery, and then apply the desired escalation path. Maintenance windows can pause affected checks and suppress false alerts during planned work, including manual, recurring cron-based, and one-off maintenance.
Verify monitor behavior, not merely monitor creation
Wait for several checks and examine their recorded state. Confirm that an intentionally healthy target appears healthy and that response or connection information is plausible. In a controlled test window, use a safe test service to validate the failure and recovery path. Avoid deliberately interrupting a production dependency solely to test notifications.
DNS and TCP monitoring were added in Kuvasz 4.2.0 and are integrated with the web interface, REST API, YAML, incidents, statistics, notifications, metrics, import and restore workflows, and the MCP server. If you operate an older version, check its documentation instead of assuming these monitor types are available.
Create and review the Kuvasz status page
Kuvasz supports public and private, brandable status pages. The exact field names, menu sequence, URL format, and authentication controls are not present in the supplied project excerpt, so this article does not invent them. Use the status-page management screen or supported API for your installed release and make the following decisions explicitly.
Define the page audience
Choose public visibility for information intended for anyone with the address, or private visibility for an internal audience. Confirm the actual access behavior in your installed Kuvasz version before sharing the page.
Select only appropriate monitors
Include services whose names and health states are suitable for the intended audience. Internal host names, infrastructure labels, or sensitive operational details may be inappropriate on a public page.
Apply the required branding
Use the brandable status-page options supported by your release. Review the rendered page on desktop and mobile rather than assuming that saved settings produce the intended public presentation.
Save and copy the exact local page address
Open the resulting status page locally and record its complete path. Do not assume that the application root and the status-page route are identical.
An HTTP tunnel forwards traffic to the configured local web service. A public status-page path does not automatically prove that every other route on the same origin is suitably protected. Before sharing the tunnel address, test the application root, administration routes, REST API, MCP endpoint, heartbeat routes, and any other known paths. Keep Kuvasz authentication enabled where applicable and use least-privilege controls around operational interfaces.
Verify Kuvasz locally before creating the tunnel
Local testing separates application problems from tunnel problems. Perform the first check on the Kuvasz host, followed by a check from the device that will run the Localtonet client if it is a different machine.
Confirm the deployment remains healthy
Check that the Kuvasz container is running and that its logs do not show recurring database, migration, configuration, or binding errors.
Open the actual local web address
Use the scheme, IP address, and published port observed from your deployment. Confirm that the browser reaches Kuvasz and that the expected interface renders completely.
Open the exact status-page path
Verify that the intended status page loads directly, displays the selected monitors, and reflects their current states. Test its public or private behavior as configured.
Test from the future tunnel device
If Localtonet will run elsewhere, open the same endpoint from that device. Resolve host names and local certificates there, because the tunnel client must be able to reach the target independently.
Record a known-good baseline
Record the working local IP, port, scheme, path, response behavior, and time of the test. This baseline makes later troubleshooting much faster.
If local access fails, stop here. A tunnel cannot repair a stopped container, incorrect database connection, missing host-port publication, unsuitable bind address, local DNS failure, or application error. Resolve the local issue first and repeat the verification sequence.
Publish the working Kuvasz service with Localtonet
Use a Localtonet HTTP tunnel for the browser-based Kuvasz interface or status page. HTTP tunnels point to a local IP address and port on, or reachable from, the client device. For HTTP tunnels, the Process Type can be Random Sub Domain, Custom Sub Domain, or Custom Domain. Each serves the configured local content at a public HTTPS address.
Available relay servers and regions must be selected from the current dashboard. We do not hardcode server codes because availability can vary. Likewise, device authentication tokens are private and device-specific. Never paste one into documentation, support screenshots, shell history, or a public repository.
Install and run the Localtonet client
Install our client on the Kuvasz host or another device that has already passed the local connectivity test. Keep the client running for as long as remote access is required.
Authenticate and select the client device
Use the device-specific authentication token associated with the client that will carry the tunnel. Treat the token as a credential and do not expose it.
Select an available relay server
Choose a currently available server or region from the Localtonet dashboard. Do not copy a server code from an old tutorial because available values must come from the current product interface.
Create an HTTP tunnel to Kuvasz
Select the required HTTP Process Type and enter the verified local IP address and port. Use an address reachable from the selected client device. Do not guess a Kuvasz default port.
Start the tunnel
Creating a tunnel does not start it. Use the Start button, then wait for the selected client and tunnel to show that they are connected and running.
Open and test the assigned public address
Open the assigned public HTTPS address from a network outside the Kuvasz LAN. Append the verified status-page path when necessary, then confirm content, authentication behavior, monitor visibility, and browser rendering.
For the current dashboard workflow, consult our Localtonet HTTP tunnel documentation. If you choose a custom domain, verify the current DNS requirements in our documentation before changing DNS records. Exact custom-domain records are intentionally not supplied here because they must match the current configuration workflow.
The public address is available only while the selected Localtonet client is connected and the tunnel is running. You can stop the tunnel when remote access is no longer required, or delete it when the configuration should not be retained.
Test the public result safely
Use a separate connection, such as a mobile network, to avoid accidentally testing through the same LAN path. Load the exact shared page, refresh it, and confirm that its monitor data is current. Check that private pages still require their intended access controls and that administrative operations are not anonymously available.
Do not share the address until you have tested unexpected paths. Requesting the application root instead of the status-page path is a useful first check. Also review known API and operational routes based on the Kuvasz documentation for your version. Localtonet provides connectivity to the local service, but application-level authorization remains part of the Kuvasz deployment design.
Routine operation, upgrades, and troubleshooting
Daily and weekly operational checks
Review monitor states, open incidents, notification delivery, PostgreSQL health, disk capacity, and Kuvasz runtime logs. Use maintenance windows for planned changes so expected downtime does not generate misleading incidents. Review status-page membership whenever services are renamed, retired, or reorganized.
Back up PostgreSQL using a tested database backup process. A backup is only useful if its restoration procedure has been validated. Keep deployment configuration and secrets under appropriate access controls, and avoid embedding secrets directly in a public YAML repository. Kuvasz 4.2.0 documents configuration placeholders and support for splitting configuration through MICRONAUT_CONFIG_FILES, including workflows where secrets come from a Docker secret. Follow the exact syntax from the documentation for your installed release.
Upgrade carefully
Before upgrading, read every applicable upgrade note between the installed and target versions. Back up the database, preserve the current deployment configuration, pull the exact target image tag, and schedule a maintenance window. After startup, inspect logs, test the interface, wait for monitor checks, verify notifications, open the status page locally, and finally test it through Localtonet.
Avoid using an unpinned image reference for an operational monitoring system unless the project's deployment guidance explicitly calls for that workflow and you accept its update behavior. Pinning a reviewed version makes rollback and incident analysis more predictable.
The Kuvasz page works locally but not through Localtonet
Test the endpoint from the Localtonet client device, not only from another computer. Confirm that the tunnel target contains the same reachable IP address and port that passed the test. Then verify that the selected token belongs to the connected device, an available relay server was selected, and the tunnel was actually started.
If Kuvasz is bound only inside a container network, a client running directly on the host or another LAN device may not be able to reach it. Correct this using the network publication procedure documented by Kuvasz for your deployment method. Do not solve it by exposing unrelated database or administration ports publicly.
The tunnel opens the wrong Kuvasz page
The tunnel targets an origin defined by an IP address and port. The status page may live at a path below that origin. Use the complete public URL with the verified local status-page path. If the application generates redirects to an unexpected host, scheme, or internal address, review Kuvasz's documented external URL or proxy-related settings for your release. Those setting names are not established by the supplied evidence and should not be guessed.
Monitors fail after the tunnel is published
Localtonet does not alter Kuvasz's outbound monitoring path. Investigate the monitor target, DNS resolution, network policy, certificate state, request configuration, timeout, and target availability from the Kuvasz host. For a TCP monitor, confirm that the destination accepts connections. For DNS monitoring, confirm the configured resolver and expected records. For heartbeat monitoring, verify that the scheduled process sends its expected push.
The public address suddenly stops responding
Confirm that the Kuvasz container and PostgreSQL are healthy, then verify that the Localtonet client remains connected and the tunnel remains running. A restarted or sleeping host, stopped client, stopped tunnel, changed local IP, or changed published container port can interrupt access. If the local endpoint changed, update the tunnel only after verifying the new address locally.
The status page reveals too much information
Remove sensitive monitors from the page, revise labels that expose internal infrastructure, and reassess whether the page should be public or private. Stop the tunnel while reviewing an accidental exposure. Also inspect whether the same origin provides unauthenticated access to administration, API, MCP, or heartbeat functionality.
Frequently asked questions
What does Kuvasz require to run?
Kuvasz is distributed as a single Docker image and requires a PostgreSQL database. The exact startup command, database configuration, network mapping, storage paths, and credentials must come from the deployment guide matching your selected Kuvasz version.
What is the default Kuvasz port?
The evidence supplied for this guide does not establish a default local port or published host port. Read the deployment documentation for your selected version and inspect the running container configuration. Use the endpoint that you have successfully tested from the Localtonet client device.
Can Kuvasz create both public and private status pages?
Yes. Kuvasz supports public and private, brandable status pages. Confirm the exact access behavior and available controls in your installed version before sharing a page remotely.
Which Localtonet tunnel type should I use for a Kuvasz status page?
Use an HTTP tunnel for the browser-based Kuvasz service. Configure it with the verified local IP address and port reachable from the selected Localtonet client. The public status page may also require its path after the assigned public HTTPS address.
Does Localtonet require router port forwarding or a public IP?
No. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Does publishing a status page also expose the Kuvasz dashboard?
An HTTP tunnel forwards to the configured local web origin. If the status page, dashboard, API, MCP server, or heartbeat routes share that origin, other paths may also be reachable unless Kuvasz protects them. Test those paths and retain appropriate application authentication and authorization.
Will the public URL remain available if the host is turned off?
No. The Kuvasz service must be running, the selected Localtonet client must be connected, and the tunnel must be running. If any part of that chain stops, visitors cannot reach the status page through the tunnel.
Can Localtonet make a broken Kuvasz installation work remotely?
No. Localtonet provides connectivity to the configured local target. Kuvasz must already be running, connected to PostgreSQL, and reachable from the client device. Always fix local installation or application errors before troubleshooting the tunnel.
Publish your verified Kuvasz status page with Localtonet
Once Kuvasz is healthy locally and the intended status page has been reviewed, create an HTTP tunnel to its verified local IP address and port. Start the tunnel, test the assigned public HTTPS address from an external network, and keep application authentication enabled for every operational route that should remain private.
Get Started Free →
