Skip to content
Watcher Docs

Quickstart

By the end of this page Watcher will have collected real content from a real website, asked a model whether your condition was met, and printed its verdict.

Before you start

Section titled “Before you start”

You need:

  • Node.js 20+ and pnpm — check with node --version and pnpm --version
  • A MongoDB connection string — a free Atlas cluster works, so does a local mongodb://localhost:27017
  • A Google AI Studio API key — the model that evaluates conditions

Steps

Section titled “Steps”

  1. Install dependencies

    Terminal window
    pnpm install

  2. Create your .env

    Terminal window
    cp .env.example .env

    Open .env and set the two required values:

    .env
    GOOGLE_GENERATIVE_AI_API_KEY=<your-google-ai-studio-key>
    MongoDB_URI=<your-mongodb-connection-string>

    Without a Google key Watcher will not start at all — the evaluator, the embedder and the AI drafter are all built from it.

  3. Write a watch

    Create watches/my-first-watch.yml:

    watches/my-first-watch.yml
    id: nodejs-security
    name: Node.js security releases
    sources:
      - type: rss
        value: "https://nodejs.org/en/feed/blog.xml"
        trust: official
    schedule: "0 * * * *"
    condition: "A new Node.js security release or vulnerability announcement"
    channels: [telegram]
    threshold: 0.6
    weakThreshold: 0.4
    enabled: true

    You have just declared where to look (an RSS feed), what counts (the condition), how often (hourly, in UTC), and how sure the model must be (0.6) before this counts as a confirmed alert.

  4. Import it into the database

    Watch files are an import source, not the live source of truth. The running system reads watches from MongoDB:

    Terminal window
    pnpm watches:import

    You should see Imported 1 watch(es) … created. Re-running is safe: the import is an idempotent upsert.

  5. Run it once, now

    Terminal window
    pnpm run-due:force

    --force ignores the cron schedule so you need not wait for the top of the hour. Watcher collects the feed, drops anything it has already seen, asks the model about the fresh items, and prints one line per watch:

    Ran 1 watch(es) from MongoDB (force)
    

    • nodejs-security: not-triggered (collected 10, fresh 10, sent 0)

  6. Read the outcome

    That line is the whole system in miniature. collected is how many items the sources returned, fresh is how many were new since the last run, and the outcome word is what the engine decided. not-triggered means the model looked and found nothing matching your condition — the correct result on a quiet day.

    Every possible outcome is listed in Run outcomes.

  7. Run it a second time

    Terminal window
    pnpm run-due:force

    Now you should see nothing-new and fresh 0. Watcher remembers content it has already evaluated, so it never pays for the same judgement twice. That memory is explained in What Watcher remembers.

Where alerts go

Section titled “Where alerts go”

With no Telegram credentials configured, the telegram channel falls back to printing the alert to your console — exactly what you want while testing. To deliver to a real device, continue to Get the alerts.

Useful commands

Section titled “Useful commands”
Terminal window
pnpm run-due          # run only watches whose schedule is due
pnpm run-due:force    # run every enabled watch now
pnpm serve            # start the API + admin panel backend

Next

Section titled “Next”