---
title: Watchers
order: 4
description: Every file watcher in the runtime and the application that owns it. Start, stop and restart need BoxLang+.
icon: lucide:eye
---

# Watchers

![The Watchers page](../assets/screenshots/console-watchers.png)

The Watchers page lists every file watcher registered in the runtime, global ones and the ones an application started, with its state and settings. It updates live.

## The list

| Column | Meaning |
|---|---|
| Watcher | The name. A watcher an application declares in `this.watchers` is named `application:watcher`. |
| Owner | The application that started it. A watcher that belongs to no application is `global`: one from `boxlang.json` or created with `watcherNew()` outside an application. |
| State | `running`, `stopped` or `created` (registered, not started). |
| Path | The first path, and how many more there are. |
| Listener | `class`, `closure` or `struct`, or `other`. |
| Errors | Listener errors in a row. A watcher stops by itself when the count reaches its error threshold. |

The tiles count the watchers, how many run, how many are stopped and how many have errors.

## The detail

Pick a watcher to see its owner, listener, whether it recurses, the debounce and throttle in milliseconds, atomic writes, the errors in a row against the threshold, and every path.

BoxLang reports the settings and the state of a watcher. It keeps no count of the events a watcher handled and no time of the last event, so Lens shows neither.

## Actions

!!! note "BoxLang+"
    Start, stop and restart need BoxLang+ or a trial, an admin login and a console that is not read only. On Free the page shows a BoxLang+ note, the buttons are disabled and the server answers 403. You still see every watcher.

| Action | What it does |
|---|---|
| Start | Starts a stopped or created watcher. |
| Stop | Stops listening to its paths. The watcher stays registered. |
| Restart | Stops and starts it again. |

A watcher that an application owns is stopped and removed when that application is restarted, and created again when the application starts. Each action writes an audit line with the caller's address: `watcher.start`, `watcher.stop` or `watcher.restart`.

With BoxLang+, [Lensy](ai.md) reads watchers with the `watchers` tool and acts with `watcherAction`, after your approval.

## Other servers

With the server selector (BoxLang+) the page shows what another server saved in its health snapshot, read only. Actions are never run on another server.

## Settings

| Setting | Default | Meaning |
|---|---|---|
| `collectors.watchers.enabled` | `true` | Shows the Watchers page. |
| `console.actions` | `true` | Allows Start, Stop and Restart (and the other actions of the console). |