Self-Host onWatch with Docker and Localtonet

How this onWatch deployment works

onWatch is a local AI API quota monitoring application. It runs as a persistent background service, polls the providers that you configure, retains historical measurements in SQLite, and renders the results in a Material Design 3 web dashboard. Its purpose is broader than showing a provider's current usage snapshot. Historical data makes it possible to examine quota cycles, usage trends, burn rate, reset timing, and activity across multiple configured providers from one interface.

The Docker deployment packages the application as a container. The project documents a distroless image that runs as a non-root user, with an Alpine variant available when shell access inside the image is specifically needed. Persistent application data is mounted at /data inside the container, while container logs are written to standard output. That separation matters operationally: the container can be replaced during an update, while the mounted data should remain available if the Compose configuration and volume are preserved.

The local dashboard is available at http://localhost:9211 after the service starts successfully. Local verification is an essential boundary in this workflow. We first confirm that Docker can start the service, the configuration can be read, the expected port responds, and the dashboard credentials work. Only then do we add Localtonet. This order keeps application faults separate from tunnel faults and makes troubleshooting much faster.

For remote access, the Localtonet client runs on the same device as onWatch, or on another device that can reach the onWatch host and port. The client establishes an outbound connection to one of our relay servers. An HTTP tunnel then directs requests from its public HTTPS address to the local onWatch HTTP target. This does not require an inbound router port-forwarding rule, a public IP address, firewall changes for inbound internet traffic, or a VPN setup.

What Localtonet changes, and what it does not

Localtonet changes how the dashboard can be reached. It does not install onWatch, supply provider API credentials, repair an unhealthy container, or replace onWatch authentication. The tunnel remains dependent on the local application. If onWatch is stopped, Docker is unavailable, the host is offline, or port 9211 is unreachable from the Localtonet client device, the public endpoint cannot deliver the dashboard.

Creating a Localtonet tunnel also does not automatically start it. The selected Localtonet client or device must be connected, and the tunnel must be running. When either condition is not met, the public route is unavailable. This lifecycle is useful when access should be temporary because the tunnel can be stopped when remote monitoring is no longer required.

Prerequisites and deployment decisions

Prepare the host before copying configuration or entering secrets. The Docker path requires Docker or Docker Compose, enough permission to run containers, and a working directory containing the onWatch repository files. You also need at least one supported provider credential or a provider authentication method supported by onWatch. Finally, choose strong dashboard credentials before making the service remotely reachable.

Choose where configuration and data will live

This guide uses the Docker Compose files supplied in the project repository. Run the commands from the repository root so the Compose file and environment file are found in the expected location. The environment file contains sensitive values and should remain outside source control. Do not commit it, paste it into support tickets, include it in screenshots, or copy its contents into a tunnel description.

Treat the persistent data mount as part of the deployment rather than as temporary container storage. The application database contains the history that makes onWatch useful. Before changing the Compose file, moving the installation, or rebuilding the host, identify the actual host volume or bind-mount location defined by the checked-out Compose configuration. The supplied evidence establishes /data as the container-side persistence path, but the host-side storage location can depend on the Compose file version in use. Inspect that file rather than guessing.

Provider and dashboard credentials serve different purposes

Provider credentials let onWatch retrieve account or quota information. Dashboard credentials protect access to the onWatch web interface. They should not be reused. The documented environment example includes variables such as SYNTHETIC_API_KEY, ZAI_API_KEY, ANTHROPIC_TOKEN, CODEX_TOKEN, and COPILOT_TOKEN, as well as ONWATCH_ADMIN_USER and ONWATCH_ADMIN_PASS. Configure only the providers you intend to monitor.

Some non-container installations can auto-detect credentials from host applications or operating-system credential stores. A container has a different filesystem and security boundary. Do not assume that host-side auto-detection will work in Docker unless the current onWatch Docker documentation and Compose configuration explicitly provide the required mount or integration. For a Docker-first deployment, use configuration methods explicitly supported by the version you are running.

Install onWatch with Docker Compose

The following installation path uses the project's documented Docker workflow. It obtains the repository, creates the runtime environment file from the Docker example, requires you to add at least one provider credential, and starts the service in detached mode. Do not start with Localtonet. The immediate objective is a healthy local dashboard.

git clone https://github.com/onllm-dev/onwatch.git
cd onwatch

cp .env.docker.example .env

SYNTHETIC_API_KEY=syn_your_key_here
ZAI_API_KEY=your_zai_key_here
ANTHROPIC_TOKEN=your_token_here
CODEX_TOKEN=your_token_here
COPILOT_TOKEN=ghp_your_token_here

ONWATCH_ADMIN_USER=admin
ONWATCH_ADMIN_PASS=replace_with_a_unique_password

docker-compose up -d

The project also documents an alternative wrapper command:

./app.sh --docker --run

Use one startup path consistently. The direct docker-compose up -d command is easier to reason about when learning the deployment because it maps directly to the Compose file. The wrapper can be convenient if you already use the project's app.sh workflow.

Verify the container, logs, and local dashboard

Verification should progress from the container layer to the application layer and finally to authentication. A browser error alone does not identify which layer failed. Start with the container's output, confirm that the host can reach the expected endpoint, and then sign in.

Inspect onWatch logs

The Docker deployment sends application logs to standard output. The project documents the following command for following the running container:

docker logs -f onwatch

Review the initial output for configuration errors, missing credentials, port-binding failures, repeated restarts, or provider authentication errors. Press the terminal interrupt shortcut when you have finished following the stream. Stopping log display does not stop the container.

A provider-specific error does not always mean the dashboard itself is unavailable. First determine whether the application remains running and serves its interface. Then correct the affected provider configuration. This distinction is useful when several providers are configured and only one credential has expired or lacks the necessary permission.

Open the local endpoint

On the Docker host, open:

http://localhost:9211

Sign in with the values assigned to ONWATCH_ADMIN_USER and ONWATCH_ADMIN_PASS. A successful test establishes that the host port is reachable, the application is serving HTTP, and the dashboard authentication values are accepted.

Do not use the presence of a login page as the only success criterion. After signing in, confirm that the expected provider appears and that onWatch can retrieve meaningful account or quota information. Newly started monitoring may not yet have enough history to populate long-range trends. Historical analysis depends on the daemon continuing to run and collect measurements over time.

Validate the target from the Localtonet client device

If the Localtonet client will run on the same host, 127.0.0.1 or localhost can refer to the host from which the tunnel client connects. If the client will run on another machine, localhost would refer to that other machine, not to the onWatch server. In that topology, verify the onWatch host's reachable private address and make sure the service is intentionally available across that trusted local path.

The exact bind address and host-port publication are controlled by the current Compose configuration. Inspect docker-compose.yml rather than assuming that the service listens on every network interface. A deployment that works at localhost:9211 on the Docker host may not be reachable from a second device, and that can be a desirable restriction. Running the Localtonet client on the same host avoids opening the dashboard across the LAN solely for tunneling.

Operate, stop, update, and protect onWatch data

A monitoring daemon is useful only while it is running consistently. Plan for routine status checks, controlled restarts, updates, credential changes, and persistence. Docker simplifies process management, but it does not remove the need to understand which state is disposable and which state must be retained.

Observe the running service

Use Docker's normal container and Compose inspection facilities to confirm that the onWatch service remains up. For application-level diagnosis, continue to use:

docker logs -f onwatch

Logs are particularly important after editing .env, changing a provider token, updating the project files, or restarting Docker. The browser may continue displaying previously loaded data even when the backend is no longer polling successfully, so a visual dashboard check should be combined with recent log review when diagnosing stale information.

Apply configuration changes deliberately

Editing .env changes the intended configuration, but a running container may need to be recreated or restarted before it receives those values. The exact action can depend on the Compose configuration and the type of change. Use your installed Compose implementation to apply the updated configuration, then inspect the logs and sign in again.

Avoid placing secrets directly on a command line when they can be stored in the protected environment file expected by the project. Command histories, process listings, terminal recordings, and automation logs can preserve command-line values. Limit read access to .env to the account or service that administers the deployment.

Back up persistent data before disruptive changes

The documented container path for persistent data is /data. Determine whether the current Compose file maps that path to a named Docker volume or a host directory. Back up the corresponding host-side data using a method appropriate to that storage type. Stop or quiesce the application when necessary to produce a consistent SQLite backup.

A sound backup plan covers both application history and recoverable configuration. Store the database backup separately from the live Docker host. Handle the environment file carefully because it contains secrets. In many environments, it is safer to back up a secret inventory through an approved password or secret manager and rebuild .env during recovery rather than copying an unencrypted credential file into a general-purpose backup archive.

Update with a rollback plan

onWatch is actively developed, and its beta status means behavior can change. Before an update, record the version currently in use, back up persistent data, preserve the working Compose and environment configuration, and review the release notes for relevant changes. Then retrieve the intended project revision or image, recreate the service using the project's current instructions, and repeat local verification.

Do not assume that a container update also migrates every surrounding file safely. A new repository checkout can include a changed .env.docker.example or docker-compose.yml. Compare those files with your deployment instead of blindly replacing a working environment file. Never copy example placeholders over real secrets.

Alternative installation methods

Docker is not the only supported installation path. The project also documents a macOS and Linux installer script, Homebrew, a Windows PowerShell installer, release binaries for macOS, Linux, and Windows on AMD64 and ARM64, and source builds requiring Go 1.25 or newer. Native installations use commands such as onwatch, onwatch --debug, onwatch stop, and onwatch status. This article stays with Docker Compose so that service management, storage, and troubleshooting use one consistent model.

Expose the verified dashboard with a Localtonet HTTP tunnel

Once the local dashboard is healthy, an HTTP tunnel is the appropriate Localtonet tunnel family because onWatch serves a browser-based HTTP application. The tunnel's local target is the address and port where the Localtonet client can reach onWatch. In the simplest and safest topology, both applications run on the same host and the target is the local onWatch endpoint on port 9211.

Localtonet HTTP tunnels can use a Random Sub Domain, Custom Sub Domain, or Custom Domain process type. All three serve the same target content through a public HTTPS address. Availability can vary by current product configuration or plan, so use the options presented in your dashboard. Exact custom-domain DNS instructions should be taken from the current Localtonet documentation rather than inferred.

For the current interface and configuration sequence, consult our Localtonet HTTP tunnel documentation. The public endpoint works only while the selected client is connected and the tunnel is running. Stop the tunnel when remote access is no longer required, or delete it when the route should not be retained.

Secure the dashboard, secrets, and public route

onWatch can contain sensitive operational information. Quota patterns can reveal when tools are used, which providers are configured, and how usage changes over time. The environment file also contains credentials that may authorize provider API access. Remote convenience should therefore be balanced against least privilege and a clear need for public reachability.

Keep application authentication enabled

The Localtonet URL makes the service reachable, but onWatch remains responsible for its dashboard login. Use a unique administrator username where practical and a strong password that is not reused for provider, email, source-control, or Localtonet accounts. Test authentication locally and again through the public address.

Never rely on an obscure subdomain as an authentication control. Public addresses can be copied, logged, discovered through browser history, or unintentionally shared. The login credentials are the explicit access boundary documented by onWatch, so placeholder or weak values are not acceptable.

Minimize secret exposure

Restrict access to .env, avoid transmitting it through chat, and do not include it in container images or source-control commits. Configure only the provider credentials that the deployment needs. If a credential can be scoped by the provider, choose the least privilege that still supports onWatch's documented integration.

Localtonet authentication tokens are also device-specific secrets. They identify the client device that runs the tunnel and must not appear in screenshots, examples, automation output, or public issue reports. If any secret is exposed, treat it as compromised and rotate or revoke it through the relevant system.

Prefer the same-host tunnel topology

Running the Localtonet client on the Docker host allows the tunnel to target the loopback service directly. This can avoid broadening the onWatch port's LAN exposure merely to make tunneling possible. If the client must run elsewhere, permit only the required trusted network path and verify which interfaces Docker publishes.

Use temporary exposure when appropriate

The tunnel is available only while the selected device is connected and the tunnel is running. Use that lifecycle as an operational control. Start remote access when needed, stop it afterward, and delete obsolete routes. This reduces the time during which the login endpoint is publicly reachable.

Troubleshoot Docker, onWatch, and Localtonet separately

Diagnose from the inside out. First check the container, then the local HTTP endpoint, then authentication, then reachability from the Localtonet client, and finally the public tunnel. This sequence prevents a tunnel setting from distracting from a service that never started.

The container does not start

Confirm that Docker is running and that the account has permission to use it. Make sure the terminal is in the repository directory and that docker-compose.yml, .env.docker.example, and the newly created .env are present. Then inspect container output:

docker logs -f onwatch

If Docker reports that no container named onwatch exists, the Compose creation step may have failed before the container was created, or the checked-out Compose version may use a different generated name. Review the output from the Compose startup command and inspect the services defined by the current Compose file rather than repeatedly querying a nonexistent container.

The service reports missing provider configuration

At least one provider key is required. Open .env and verify that the intended variable name matches the project's current Docker example. Check for accidental spaces, copied quotation marks, placeholder text, or an expired credential. Do not print the complete file while collecting diagnostics.

After changing configuration, make sure the running container receives the update. A file edit does not necessarily alter the environment of an already created process. Reapply the Compose configuration using the supported workflow, then inspect fresh logs.

Port 9211 is already in use

Another process or container may already own the documented host port. Identify that process before stopping or reconfiguring it. Do not arbitrarily change the port in only one place. If you intentionally change the Compose port mapping, local verification and the Localtonet target must use the actual host-side port. The container's internal behavior and the host-published port are separate settings.

The browser cannot open localhost:9211

Confirm that the container remains running and review its logs. Make sure the browser is running on the Docker host. From another computer, localhost refers to that computer, not the server. If you are testing remotely across a LAN, use an address intentionally exposed by the Docker host and allowed by local network policy.

Also check the Compose port publication. The evidence establishes the documented local URL, but a locally modified Compose file may behave differently. Compare your file with the version expected by the installed release.

The login page works but credentials are rejected

Verify the exact values configured for ONWATCH_ADMIN_USER and ONWATCH_ADMIN_PASS without exposing them. Watch for trailing whitespace introduced by an editor and confirm that the container was recreated or restarted as required after the values changed. Browser password managers can also submit an older saved password, so test by entering the intended credentials directly.

The dashboard opens but provider data is missing

Review logs for provider authentication or permission errors. Confirm that the relevant provider variable is configured and that the credential remains valid. Some integrations have provider-specific requirements. For example, the documented Copilot setup requires a classic GitHub Personal Access Token with the copilot scope. Do not broaden a token's permissions blindly. Follow the integration requirement for the provider and version in use.

A fresh deployment may also lack historical charts because it has not collected enough observations. Let the daemon run and confirm that new data arrives. Missing history immediately after installation is different from a provider that never returns current information.

The local dashboard works but the public URL does not

Check that the Localtonet client is connected, the correct device is selected, and the tunnel has been started. Remember that creating the configuration is not the same as running it. Confirm that the tunnel type is HTTP and that its target is the local address and port reachable from that client.

If Localtonet runs on another device, test the onWatch host and port from that device. A service bound only to loopback cannot be reached through another machine's loopback address. Either run Localtonet on the onWatch host or intentionally configure a trusted network path, taking care not to expose the service more broadly than needed.

The public login loads but dashboard assets or requests fail

First compare behavior through http://localhost:9211. If the same request fails locally, troubleshoot onWatch rather than the tunnel. If the issue occurs only through the public URL, capture non-sensitive browser error details, confirm that the complete assigned HTTPS URL is being used, and review both onWatch and Localtonet connection state. Do not include cookies, provider tokens, Localtonet auth tokens, or authorization headers in shared diagnostics.

Data disappeared after an update or recreation

Inspect the Compose storage configuration and determine whether the new container uses the same persistent host volume or bind mount as before. The application expects persistent data at /data inside the container, but recreating a deployment with a different project name, volume, or host path can attach empty storage. Stop making changes until you identify the previous data location. Restore from a verified backup if necessary.

Frequently asked questions