FAQ

About the product

Is there a hosted version I can just sign up for? No. Watcher is self-hosted: you run it, you hold the keys, and your watchlist never leaves your infrastructure. Start with the Quickstart.

What does it cost to run? Nothing, on free tiers, for a personal number of watches: a free database tier, free model tiers, a scheduled CI job, and Telegram. The ceilings and what breaks first are in Costs and quotas.

How is this different from a feed reader or an uptime checker? A feed reader shows you everything and makes you read it. An uptime checker tells you a page changed. Watcher answers a question about the content — “has the result been declared?” — and only tells you when the answer is yes, with the sentence that proves it.

Do I have to trust an AI’s judgement? Only partly, and that is the point. A model proposes; the system then checks that the quote really exists in the page, that the link was really fetched, that the source is credible, and that a second model from a different family agrees. Anything that fails a check is labelled “unconfirmed” rather than presented as fact. See Accuracy.

Can it watch a page behind a login? No. There is no mechanism for authenticating to a source.

Is there an iPhone app? No. The mobile app is Android-only and the iOS project is unmaintained.

Setting it up

What is the absolute minimum I need? Node.js, a MongoDB connection string, and a Google AI Studio API key. Telegram and search are optional.

Do I need the always-on API server? No. The monitoring runs as a scheduled job with no inbound server at all. The API and admin panel are conveniences for managing watches.

Why does it refuse to start? Almost always a missing GOOGLE_GENERATIVE_AI_API_KEY (needed for the evaluator, the embedder and the drafter), an unreachable database, or — for pnpm serve — a missing or too-short AUTH_JWT_SECRET. See Deployment issues.

I edited a file in watches/ and nothing changed. Watch files are an import source. Run pnpm watches:import to push them into the database, which is what the running system reads.

Using it

My watch is not firing. What do I check first? The run outcome. It names the exact stage where the run stopped. Start at Why didn’t my watch fire?.

I improved my condition, but still nothing happens. Content is evaluated exactly once. The content that would have matched has already been consumed and will not be re-read. The workarounds are in What Watcher remembers.

Why did my alert arrive marked “unconfirmed”? One of the six confirmation checks failed — most often the source was not graded as credible, or the model’s quote could not be found verbatim in the page. See Decision rules.

Why am I getting alerts from a site I do not trust? Add a trust rule marking that domain as low, and it can never lift an alert above the weak tier. See Manage the trust registry.

Can I make it check every minute? Only if the instance itself runs every minute. A watch cron faster than the instance’s schedule has no effect. See Scheduling.

Will it alert me twice for the same news? It is designed not to: content it has read is remembered, events have stable identities, and reworded versions of the same story are matched by meaning. A duplicate is possible if the embedding service was unavailable during the run.

What happens if Telegram is down when an alert fires? The alert is stored and replayed on the next run — no model call is spent, and you still get it. There are five attempts before it is given up on. See Failures and retries.

Data and privacy

What leaves my infrastructure? The text Watcher collects is sent to the model provider you configured, along with your condition. Alerts go to the channel you configured. Nothing else.

Can I stop a watch’s content reaching the free second-opinion model? Yes — set allowSecondaryModel: false on that watch. It then runs primary-only, with no second opinion and no failover.

Where are my API keys stored? Either in environment variables, or encrypted at rest in the database with a master key that lives only in the environment. Keys are decrypted in memory at the point of use and are never returned by the API — only masked previews.

Contributing

Can I add a new source type or delivery channel? Yes. Both are adapters behind a small interface, and neither requires touching the engine. See Add a collector and Add a notifier.

Is there support? Watcher is maintained by one person and provided as-is. These docs are the support channel — start with Troubleshooting.