> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentx.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# agentx serve

> Keep watching and report whenever something changes.

`agentx serve` is what the desktop app runs in the background. It scans the machine once, then rescans whenever anything it inventories changes, and reports again only when the inventory changed. It also checks your skills for updates. You rarely need to run it yourself.

## What counts as a change

Serve watches agentx itself, the library and every skills directory an agent client reads, including the ones clients keep under their own configuration such as `~/.claude/skills`. An edit inside a skill counts, not only a skill added or removed. Edit a skill with any editor or another tool and the next snapshot shows it.

A change outside the inventory, such as a skill in a directory no installed client reads, causes a rescan that prints nothing.

## Run it

```sh theme={null}
agentx serve
```

```text theme={null}
snapshot 1: 3 configurations, 5 skills
update pdf: 3f2a9c1 -> 8b1e0f4, 2 files
snapshot 2: 3 configurations, 6 skills
```

Each `snapshot` line means the inventory changed; a change that leaves the inventory as it was prints nothing. Each `update` line is a skill with an update available. Close the process's stdin, or press Ctrl-C, to stop it. Either way serve exits `0`.

The desktop app runs serve with [`--json`](/cli/output#json-output). It then also gets the whole inventory, a notice when a skill changes state, and answers to its own refresh and search requests.

## Update checks

Serve checks your managed skills for updates as [`agentx skill check`](/cli/skill#check-for-updates) does: once when it starts, right after the first snapshot, and then every thirty minutes. Each check also fetches every source you added, even the ones you have not installed anything from, as [`agentx source fetch --all`](/cli/source#fetch-a-source-again) would. A machine without any source has nothing to fetch, and serve runs no git for it.

A check only records what it found; nothing is ever applied. Every check lists every available update again, so the `update` lines repeat while the update is available. Apply an update with [`agentx skill update`](/cli/skill#update-a-skill).

A source that cannot be fetched, because you are offline or the repository moved, is a warning starting `update check:` that names it and any skills it left unchecked. Serve warns once, not on every check. It warns again only when the reason changes, and it says so on a line of its own when the source can be fetched again:

```text theme={null}
warning: update check: https://github.com/me/skills: git fetch: fatal: unable to access 'https://github.com/me/skills/': Could not resolve host: github.com; not checked: pdf
info: update check: https://github.com/me/skills can be fetched again
```

The checks in between log the failure as a debug line, which `--verbose` shows, and serve keeps running. A skill whose new version agentx refuses to import, and a source that was fetched but could not be read, are warned about on every check. The other `update check:` warnings say what an update leaves out or renames, or that a whole check failed.

Serve cannot fetch a source that [`agentx import`](/cli/export#import-onto-another-machine) brought back until you add it again. Run `agentx source add <url>` to fetch it, or `agentx source add <url>#<pin>` for a pinned source so that it stays pinned.

Checks run in the background: scans go on while a check waits on the network, and a check still running when the next one is due is not started twice.

To check more or less often, set `AGENTX_CHECK_INTERVAL` to a duration such as `10m` or `2h` before starting serve. Serve refuses to start with exit code 1 when it is not a positive duration.

## Run one pass

```sh theme={null}
agentx serve --once
```

Scans once, prints the snapshot and exits. It runs no update check. For an inventory to read, run [`agentx scan`](/cli/scan) instead.

## One serve per home

Only one serve runs per agentx home. Starting a second one exits with code 6 and names the lock file, `serve.lock` in agentx home. Stop the running one first.

## When watching is not possible

If a directory cannot be watched, serve exits with code 6 and an error naming the directory and the cause. On Linux this usually means the inotify watch limit is reached; raise `fs.inotify.max_user_watches`. Serve never polls instead.

On macOS the released binary watches through FSEvents, which handles a library of any size. A macOS binary built without cgo watches through kqueue instead, which needs one open file per watched file and reaches the default limit of 256 with a few dozen skills; raise the limit with `ulimit -n`, or use the released binary.

A skills directory that does not exist yet is not watched. Serve picks it up at the next rescan after it appears.


## Related topics

- [agentx](/index.md)
- [agentx doctor](/cli/doctor.md)
- [agentx scan](/cli/scan.md)
- [agentx source](/cli/source.md)
- [agentx skill](/cli/skill.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.