Agent Activity is a monitoring platform for registered desktop machines. It combines a Python endpoint agent, a FastAPI backend, and an Angular dashboard so system activity can be collected, organized, and reviewed from one place.
At a high level, each enrolled machine identifies itself to the backend, keeps sending health data, and checks whether there is any pending work to execute. The dashboard turns that stream of information into an operator console: online status, host details, system metrics, screenshots, activity logs, and command results are all available through a single interface.
Caution
Agent Activity can collect sensitive information, including keyboard events, clipboard contents, screenshots, process data, and selected file contents. Use it only on machines where monitoring is authorized, disclosed, and appropriate. SO BE CAREFUL, THE AGENT COULD BE USE AS A MALWARE!
Agents register with machine details such as hostname, operating system, IP address, MAC address, CPU information, and core count. Each agent sends regular heartbeat metrics, allowing the backend to keep track of which machines are online and which have gone quiet.
The dashboard uses that information to present a live fleet view. Operators can search agents, filter by operating system or status, open an individual agent, and quickly understand when it was last seen.
On supported desktop platforms, the agent can collect keyboard activity and group typed input into structured events. Those events are buffered locally, written as JSON Lines, and periodically sent to the backend for review.
The backend stores keylog events with timestamps, application context, event type, and value. From the dashboard, operators can inspect keylog history, filter it, and download it when needed.
The agent can monitor clipboard changes and capture text content that passes configured length checks. Like keylogs, clipboard events are buffered, persisted locally, and sent to the backend in batches.
This makes it possible to review copied text alongside the application that was active when the clipboard changed. Because clipboard data is often highly sensitive, this feature should be enabled and used with particular care.
The screenshot service captures the desktop at a configured interval, compresses the image, stores it locally, and uploads it to the backend. The agent also removes old local screenshots once the configured maximum count is reached.
The backend stores screenshot metadata and serves the image files to the dashboard. Operators can browse screenshots per agent, open individual captures, delete old captures, or download all screenshots for an agent as a ZIP archive.
Every heartbeat includes system information such as CPU usage, memory usage, disk usage, network counters, upload and download speed estimates, uptime, process count, battery state, and current active application.
These metrics are stored as time-series records and shown in the dashboard so an operator can see how a machine is behaving over time, not only whether it is online.
The backend can queue commands for an online agent. The agent polls for pending commands, runs the matching handler, and reports the result back with a final status.
Currently supported commands are intentionally small and inspect-oriented: filesystem.list_directory
, filesystem.read_file
, and processes.list_processes
. This keeps the command channel useful while limiting the command surface.
Start the backend first:
cd backend
python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
alembic upgrade head
python -m app.main
Then start the dashboard:
cd frontend
npm install
npm start
Finally, start an agent from a machine that can reach the backend:
cd agent
python -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python main.py
On Windows, activate Python virtual environments with venv\Scripts\activate
.
The agent can be packaged with PyInstaller for each supported operating system. Linux packaging installs a systemd
service, macOS packaging creates a menu bar app and DMG, and Windows packaging creates a tray application.