This is an automated email from the ASF dual-hosted git repository. hsluoyz pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/casbin-gateway.git
commit 9cf80235f50e78c435ca36cbee09389adbc80b14 Author: Yang Luo <[email protected]> AuthorDate: Sat Aug 15 14:52:19 2026 +0800 docs: describe how agent monitoring has to be deployed and what it retains Agent monitoring shipped without documentation, and three of its properties are surprising enough that operators only discover them by being bitten. It is not a service you deploy once for a fleet. It reads and writes files owned by a particular account on a particular machine, so it must run natively on the same host as the agent and as that user. Under Docker, which is how the rest of the project is deployed, the Agents page is simply empty, and there is nothing on the page to explain why. Records are held in memory and lost on restart. That makes this a live diagnostic window rather than an audit log, and it should be stated before someone relies on it for retention or evidence. Different agents are monitored by different mechanisms and do not emit the same event types, so a filter can legitimately return nothing. The table says which agent yields what, and which ones are observed without touching their config. Also documents the new configuration keys and the privacy question, since payloads contain prompts, commands and file contents that any Gateway admin can read. Co-Authored-By: Claude Opus 5 <[email protected]> --- README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/README.md b/README.md index e07db2b..cc6206d 100644 --- a/README.md +++ b/README.md @@ -106,6 +106,76 @@ Casbin Gateway uses Casdoor to manage members. If you want to log in with oauth, Casbin Gateway uses Casdoor to upload files to cloud storage, send Emails and send SMSs. See Casdoor for more details. +## Agent monitoring + +The Agents page discovers AI coding agents installed on the host and can enable +audit-only monitoring for the ones Gateway supports. Monitoring never blocks an +agent action; it only observes and records. + +### Where this has to run + +Unlike the rest of Casbin Gateway, agent monitoring is not a service you deploy +once for a fleet. It reads and writes files that belong to a specific user +account on a specific machine, so it only works when Gateway runs: + +- **on the same host as the agent**, natively rather than in a container. A + container cannot see the host's installed agents or its home directories, so + the Agents page will simply be empty under Docker or Kubernetes. +- **as the user who owns the installation**, or as an account that can resolve + that user and write into their home directory. Gateway refuses to patch an + installation whose owner it cannot resolve rather than guessing. + +Patching Claude Code writes the absolute path of the running Gateway binary into +`~/.claude/settings.json`. Moving or reinstalling Gateway invalidates that path, +so unpatch before relocating the binary and patch again afterwards. + +### What is recorded, and for how long + +Records are held **in memory only**. They are never written to disk, and every +record is lost when Gateway restarts. This is a live diagnostic window, not a +durable audit log; do not rely on it for retention or evidence. + +The window holds `agentRecordCapacity` records (1000 by default), each capped at +64 KiB of sanitized payload, so it bounds its own memory use. Credentials are +redacted before a record is stored, and writes to files such as `.env`, `.ssh/` +and `*.pem` have their content removed while keeping the path. + +Payloads still contain prompts, commands and file contents. Anyone with admin +access to Gateway can read them, which has obvious privacy implications for the +people whose agents are monitored — decide whether that is acceptable, and +whether those people should be told, before enabling this in an organization. + +### What each agent reports + +Agents are monitored by different mechanisms, so they do not all produce the same +events. Filtering for an event type an agent never emits returns nothing. + +| Agent | Mechanism | Changes the agent's config | Events | +|-------|-----------|----------------------------|--------| +| Claude Code | Command hooks in `settings.json` | Yes | session, prompt, tool, mcp, permission, subagent, compact | +| Claude Desktop | MCP recorder registration | Yes (one `mcpServers` entry) | session, mcp; plus tool and mcp from Cowork transcripts on Windows | +| Codex, Codex CLI, Codex for VS Code | Tails rollout JSONL | No | llm, tool, mcp, session | +| OpenAgent | Tails audit JSONL | No | llm, tool, mcp, session | +| OpenClaw | Hook handler in `~/.openclaw` | Yes | tool, session | +| Cursor, Cursor Agent, Windsurf | Not implemented yet | — | — | + +Agents that are monitored by tailing files need no configuration change, so +unpatching them leaves nothing behind. For the others, Gateway removes only the +entry it added; if the file changed after patching, the entry it could not +safely remove is named in the error so it can be deleted by hand. + +### Configuration + +| Key | Default | Meaning | +|-----|---------|---------| +| `agentPatchStateDir` | `./data/agent-patches` | Patch manifests, config backups, ingest tokens and tail cursors | +| `agentRecordCapacity` | `1000` | Records kept in the in-memory window | +| `agentMonitorPollSeconds` | `5` | How often file-tailed agents are rescanned | + +Patched agents report over loopback to `/api/add-agent-record`, authenticating +with a token issued for that installation. Gateway rejects reports that arrive +through a proxy, so do not expose this endpoint through a reverse proxy. + ## Contribute For Casbin Gateway, if you have any questions, you can open Issues, or you can also directly start Pull Requests(but we recommend opening issues first to communicate with the community). --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
