Setup and usage

The two projects deploy independently, so pick one to start. If you only care whether a block of text changed, use WebMonitor. If you want alerts such as “notify me when the price drops 10%”, “out of stock becomes available” or “a new list entry appears”, use the Agent. If someone already gave you an instance URL and an account, just sign in — no Docker needed.

You need a computer or server that can run Docker, plus curl to download the deployment files. A normal install needs no repository clone and no registry login. The public images support both Intel/AMD and Apple Silicon; Docker picks the right one automatically.

Images follow the latest stable release, latest, by default. To pin a release, set WEBMONITOR_IMAGE in .env to a version such as 1.0.0. Both projects start with docker compose up -d --wait, which returns only after the health checks pass.

WebMonitor runs as one container that serves both the web interface and the API, with SQLite and Chromium included. It needs no model key; configure email after signing in.

mkdir -p webmonitor
cd webmonitor
curl -fsSLo compose.yaml https://raw.githubusercontent.com/webmonitor/WebMonitor/main/compose.yaml

WEBMONITOR_IMAGE=ghcr.io/webmonitor/webmonitor:latest
SECRET_KEY=
ADMIN_USERNAME=admin
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=

docker compose up -d --wait
# Open http://localhost:8000

If you reach the dashboard, the install worked. The sidebar leads to Monitors, Monitor logs, Email settings and Public tasks. If --wait fails or never returns, run docker compose ps and docker compose logs --tail=100 to see why.

WebMonitor repository and full guide

The Agent needs a model service compatible with OpenAI Chat Completions to understand your request and prepare monitor settings. The install starts a group of containers: the app, a database, page-archive storage and an egress proxy. The application image is pulled from the public registry; two helper images are built locally from the downloaded files on first start.

mkdir -p webmonitor-agent
cd webmonitor-agent
(
  set -e
  for file in compose.yaml .dockerignore deploy/browser-seccomp.json deploy/minio.Dockerfile deploy/minio-artifacts.json deploy/egress.Dockerfile deploy/egress/squid.conf deploy/egress/unbound.conf deploy/egress/entrypoint.sh deploy/proxy/nginx.conf; do
    curl -fsSL --create-dirs "https://raw.githubusercontent.com/webmonitor/WebMonitor-Agent/main/$file" -o "$file"
  done
)

WEBMONITOR_IMAGE=ghcr.io/webmonitor/webmonitor-agent:latest
WEBMONITOR_HTTP_PORT=8080
APP_ORIGIN=http://localhost:8080
DEVELOPMENT_MODE=true
POSTGRES_PASSWORD=
SECRET_KEY=
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=
SMTP_HOST=
SMTP_PORT=465
SMTP_USERNAME=
SMTP_PASSWORD=
SMTP_USE_SSL=true
SMTP_STARTTLS=false
MAIL_FROM=

docker compose up -d --wait
# Open http://localhost:8080

Open the page and sign in with ADMIN_EMAIL and ADMIN_PASSWORD from .env; you should land in the conversation workspace. If there is no admin account yet, or you need to invite a member, see “Troubleshooting” below.

WebMonitor-Agent repository and full guide

1. After signing in, open Monitors and choose Create task.
2. Fill in the task name, monitor URL, XPath selector and check interval in seconds (minimum 10, default 300). If you are unsure about the XPath, choose Test monitor first and check the extracted text; the test sends no email.
3. Decide whether to make the task public and whether to enable monitoring, then create the task.
4. Open Monitor logs to review each check’s time, result and new content. The dashboard summarises task counts, recent changes and the execution success rate.

The first successful scheduled check may send an initial notification; after that, email is sent only when the text changes. A task without an email configuration still collects and logs, it just sends nothing. Once a task is public, other users on the same instance can subscribe from Public tasks and receive notifications through their own email settings.

1. After signing in, choose New conversation in the sidebar.
2. Describe the URL and the request together: what to watch, how often to check, and when to notify you. For example: “Watch this page’s price and email me when it drops 10%.”
3. The assistant opens the page and takes one real sample. Wait while it reads the page and prepares the monitor settings.
4. On the Create monitor card, review the extracted content, notification rules, recipients and email preview. If something is off, choose Preview again.
5. Choose Create monitor to start scheduled checks.

The monitor then appears under Monitors in the sidebar. Open it to see the current content, recent checks and events, plus screenshots and page archives saved by browser collection. The top right offers Pause, Resume, Check now and Edit settings. To change what is watched or when it notifies, explain it in the conversation, review the new preview and save.

Email works differently in the two projects: WebMonitor users enter SMTP and recipients in the app, while the Agent’s SMTP belongs to the deployment and an admin maintains recipients in notification groups. Without email, both still collect and show changes — you just get no alerts.

WebMonitor: open Email settings and choose Add email configuration. Enter a name, SMTP server, SMTP port, sender address, SMTP password and recipient address, and turn on Use SSL if your provider requires it. The password is usually an app-specific password. Choose Test connection and confirm the test email arrives, then create or edit a task and select this configuration under Email configuration. With “Do not send notifications”, the task still collects but sends no mail.

WebMonitor-Agent: set SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD and MAIL_FROM in .env, then run docker compose up -d --wait so the new settings take effect. Sign in as an admin, open Notifications → Notification groups and choose New. Enter a name and recipients (one email per line, or separated by commas or spaces). When creating or editing a monitor, choose the group under Recipients; one monitor can notify several mailboxes.

WebMonitor keeps everything in the sidebar:

• Monitors lets you test, edit, pause or enable, and delete tasks; the list shows each check interval and attached email configuration.
• Monitor logs shows each check’s status, new content and error message, per task.
• Public tasks and My subscriptions share tasks within the instance and let you subscribe to others; each user receives notifications through their own email configuration.
• Admins can also adjust accounts and subscription limits under Users, and restrict which domains regular users may monitor under Blacklist.

The Agent manages conversations, monitors and notifications in one workspace:

• Open any monitor from the Monitors list to see current content, recent checks and events; use Pause, Resume, Check now and Edit settings to control it.
• Events records changes, failed checks and recoveries. Filter by Unread and choose Mark as read when done.
• Notifications manages notification groups and shows each email’s recipients, status and failure reason.
• An admin invites members, and new members register through an invitation link.

• The startup command fails or never returns: run docker compose ps and docker compose logs --tail=100 in the deployment directory. Common causes are a blank value in .env, an occupied port, or unusable model settings. Fix it and run the startup command again.
• The page will not open: check that you are visiting http://localhost:8000 (WebMonitor) or http://localhost:8080 (Agent), and that the containers are running.
• WebMonitor sign-in fails: sign in with ADMIN_USERNAME from .env, not the email. The initial admin is created only when the database has no admin; editing .env later does not reset an existing account.
• Agent sign-in fails: use ADMIN_EMAIL and ADMIN_PASSWORD from .env; the password must be 12–128 characters.
• The Agent has no admin, or a new member cannot register: in the deployment directory run docker compose exec api webmonitor admin-create --email you@example.com to create an admin, or docker compose exec api webmonitor invite-create --email member@example.com --ttl-hours 24 to generate a one-time invitation link. An expired link or a different email will not work.
• WebMonitor extracts nothing: use Test monitor to check that the XPath selects the element that actually contains the text. Content that requires signing in cannot be monitored directly.
• The Agent preview fails or the address is rejected: the target must be a public http/https address on port 80 or 443. An unreachable site, bot blocking, a sign-in requirement, or content inside an iframe / Shadow DOM can all fail; an unavailable model service also interrupts the conversation.
• No email arrives: for WebMonitor choose Test connection under Email settings; for the Agent check SMTP in .env and the recipients in the notification group. Also check spam and the delivery log.
• After an update the app will not open or the data looks wrong: neither project migrates databases automatically. Restore the matching backup, or set WEBMONITOR_IMAGE back to the previous version and start again.

Back up your data and note the current image version before updating. Change WEBMONITOR_IMAGE in .env to the new version, then run the commands below in each project’s deployment directory.

docker compose pull
docker compose up -d --wait

docker compose pull api web
docker compose up -d --wait api web

To roll back, set WEBMONITOR_IMAGE to a previous version that is still available and run the same commands for that project. There is no database downgrade: an older version may not read data written by a newer one, so restore the pre-update backup if needed.

WebMonitor releases

Agent releases

Neither project provides automatic backups or data migration; the data lives inside the containers, so keep your own backups outside them.

docker compose stop
docker cp webmonitor:/app/data/webmonitor.db ./webmonitor-backup.db
docker compose start

Monitoring limits:

Report issues in the relevant project with reproduction steps and a page example with sensitive data removed.

WebMonitor on GitHub