winget install --id=sysmanage.sysmanage-agent -e SysManage Agent is the host-side daemon for the SysManage open-source fleet management platform. It registers the host with a SysManage server, reports inventory, applies declarative deployment plans (package install, firewall config, antivirus deployment, VM lifecycle), and surfaces real-time health metrics.
A lightweight, secure, cross-platform system monitoring agent that connects to SysManage Server via WebSocket for real-time remote management.
Complete documentation is available at sysmanage.org
SysManage Agent is a headless Python application designed to be installed on remote systems for centralized monitoring and management. It establishes a secure WebSocket connection to the SysManage Server and provides real-time system information, command execution capabilities, and health monitoring.
ansible-core on POSIX or the vendored DSC v3 engine on Windows, reporting per-task changed/ok/failed back over the same connectionInstall the agent from a signed native package. The full per-platform instructions are at sysmanage.org/docs/agent/installation.html; the common cases are below. SysManage does not publish container images.
sudo add-apt-repository ppa:bceverly/sysmanage-agent
sudo apt update
sudo apt install sysmanage-agent
# Install the archive signing key and check its fingerprint:
# 896E ED43 9F5E 9BB1 FCA6 69A5 E033 E691 377F 0AE3
sudo install -d -m 0755 /usr/share/keyrings
curl -fsSL https://repo.sysmanage.org/agent/sysmanage-archive-keyring.gpg \
| sudo tee /usr/share/keyrings/sysmanage-archive-keyring.gpg > /dev/null
gpg --show-keys /usr/share/keyrings/sysmanage-archive-keyring.gpg
# Add the repository, verified against that key
echo "deb [signed-by=/usr/share/keyrings/sysmanage-archive-keyring.gpg] https://repo.sysmanage.org/agent/deb stable main" \
| sudo tee /etc/apt/sources.list.d/sysmanage-agent.list
sudo apt update
sudo apt install sysmanage-agent
RHEL, Rocky Linux, AlmaLinux, Oracle Linux and CentOS Stream 9 and 10, Fedora 43 and Amazon Linux 2023 (x86_64 and aarch64). Release 8 of the RHEL family is not supported: the agent needs Python 3.9 or newer.
sudo dnf install epel-release # RHEL family only; skip on Fedora and Amazon Linux
sudo dnf copr enable bceverly/sysmanage-agent
sudo dnf install sysmanage-agent
EL9 hosts that cannot reach Copr can use the signed DNF repository on the mirror:
sudo tee /etc/yum.repos.d/sysmanage-agent.repo << 'EOF'
[sysmanage-agent]
name=SysManage Agent
baseurl=https://repo.sysmanage.org/agent/rpm/el9/$basearch
enabled=1
gpgcheck=1
gpgkey=https://repo.sysmanage.org/agent/rpm/RPM-GPG-KEY-sysmanage
EOF
sudo dnf install sysmanage-agent
sudo rpm --import https://repo.sysmanage.org/agent/rpm/RPM-GPG-KEY-sysmanage
sudo zypper addrepo https://repo.sysmanage.org/agent/rpm/opensuse-tumbleweed/x86_64 sysmanage-agent # Tumbleweed
# sudo zypper addrepo https://repo.sysmanage.org/agent/rpm/sles/15/x86_64 sysmanage-agent # SLES 15
sudo zypper refresh
sudo zypper install sysmanage-agent
yay -S sysmanage-agent (AUR)brew install bceverly/tap/sysmanage-agentwinget install --id sysmanage.sysmanage-agent --exact (x64), or
the .exe bundle for x64 and ARM64 from the mirrorhttps://repo.sysmanage.org/agent//. These downloads are not
signed; each has a .sha256 next to it. Check it before installing, as the
installation guide shows.Edit /etc/sysmanage-agent.yaml (C:\ProgramData\SysManage\sysmanage-agent.yaml
on Windows), set server.url, and restart the agent. The agent needs outbound
port 443 to the server and nothing else. Then approve the host on the server's
Hosts page.
server:
url: "https://sysmanage.example.com"
verify_ssl: true
sudo systemctl restart sysmanage-agent
For working on the agent itself. You need Python 3.9 through 3.14 (tested
across the full range in CI; 3.9 retained for macOS system Python) with its
development headers, a C compiler, and make (gmake on the BSDs).
git clone https://github.com/bceverly/sysmanage-agent.git
cd sysmanage-agent
make install-dev
cp installer/ubuntu/sysmanage-agent.yaml.example sysmanage-agent.yaml # then set server.url
make start # gmake on the BSDs
# make start-privileged # Privileged agent (for package management)
A source checkout reads sysmanage-agent.yaml in the project directory when
/etc/sysmanage-agent.yaml does not exist.
SysManage Agent includes automatic server discovery that eliminates the need for manual configuration in most scenarios:
Create configuration file at:
/etc/sysmanage-agent.yamlC:\ProgramData\SysManage\sysmanage-agent.yamlš For complete configuration options, visit sysmanage.org/docs/agent/configuration.html
SysManage Agent implements multiple layers of security:
š For complete security documentation, visit sysmanage.org/docs/security/
We test explicitly for the thirteen weakness classes in Steve Christey's MITRE paper Unforgivable Vulnerabilities (2007): flaws so well documented and so easy to find that shipping one is unforgivable. The agent runs as root / SYSTEM and acts on the server's commands, so the checks focus on what a privileged process must never do and on refusing hostile values in those commands:
| # | Class (CWE) | What this repository checks |
|---|---|---|
| 1 | Buffer overflow (120) | 100 KB strings, null and wrong-type fields in commands are answered with an error, never crash the agent; nested commands are depth-limited |
| 2 | XSS (79) | The agent produces no HTML at all |
| 3 | Directory traversal (23) | Package names cannot be ../.., /full/path or ./local.deb; hostnames are validated |
| 4 | Remote file inclusion (98) | No eval/exec/dynamic imports/pickle/unsafe YAML on received data |
| 5 | SQL injection (89) | No SQL built from strings; package names cannot smuggle options (-o ...) or shell metacharacters |
| 6 | World-writable files (276) | Code, installers and packaging never make a file world-writable; deployed files keep the mode the server asked for |
| 7 | Direct request (425) | Not applicable: the agent serves no requests (checked in the server) |
| 8 | authenticated=1 (472) | Not applicable: the agent accepts no logins (checked in the server) |
| 9 | Home-grown crypto (327) | No weak or home-made crypto; no random where a secret is involved |
| 10 | Privilege escalation via Help (271) | The privileged agent never launches a browser, help viewer or shell UI |
| 11 | Symlink following (61) | No predictable /tmp names; a symlink planted at a deploy path is replaced, never followed |
| 12 | Hard-coded / default password (259) | No credential ships in any agent config or in the code |
| 13 | Integer overflow (190) | 0xffffffff, 2**63 and negative values in names and file modes are refused |
Exceptions are recorded with their reasons in tests/lucky13/. Run the checks with make test-lucky13 (also part of make security and make test); CI runs them as their own step on every push.
The agent requires elevated privileges for certain system management operations, particularly package management. Cross-platform privileged runner scripts are included:
run-privileged.sh - Works on macOS, Linux, and OpenBSDrun-privileged.cmd and run-privileged.ps1 - Batch and PowerShell scriptsš For detailed privileged execution setup, visit sysmanage.org/docs/agent/privileged-execution.html
# Run all tests with coverage
make test
# Direct pytest execution
python -m pytest tests/ -v
# Run with coverage
python -m pytest tests/ --cov=. --cov-report=html
# Run linting
make lint
SysManage Agent supports 14 languages for logging and system messages:
| Language | Code | Status |
|---|---|---|
| English | en | ā Complete |
| Spanish | es | ā Complete |
| French | fr | ā Complete |
| German | de | ā Complete |
| Italian | it | ā Complete |
| Portuguese | pt | ā Complete |
| Dutch | nl | ā Complete |
| Japanese | ja | ā Complete |
| Simplified Chinese | zh_CN | ā Complete |
| Traditional Chinese | zh_TW | ā Complete |
| Korean | ko | ā Complete |
| Russian | ru | ā Complete |
| Arabic | ar | ā Complete |
| Hindi | hi | ā Complete |
sysmanage-agent/
āāā main.py # Agent entry point
āāā config.py # Configuration management
āāā registration.py # Server registration logic
āāā websocket_client.py # WebSocket communication
āāā system_info.py # System information collection
āāā command_executor.py # Command execution engine
āāā tests/ # Test suite
āāā requirements.txt # Python dependencies
āāā run-privileged.sh # Privileged execution script
make lint test)š For detailed contribution guidelines, visit sysmanage.org/docs/
This project is licensed under the GNU Affero General Public License v3.0. See LICENSE for details.