systems-manager

Version: 2.2.3

systems-manager is the typed host-operations provider for Agent Connector SDK and Arbora. It exposes cross-platform package, service, process, network, disk, managed-file, firewall, physical-storage, Agent OS, and privacy-safe host-ingestion capabilities without exposing a raw command tool.

The current package requires Python 3.11–3.14 and agent-connector-sdk>=2.0.0,<3.0.0.

Install and run

Install only the interface the operator need:

pip install "systems-manager[mcp]"
systems-manager-mcp --transport stdio

The optional extras are:

Extra	Capability
`mcp`	FastMCP provider runtime
`agent`	Agent server and Logfire integration
`all`	MCP plus agent runtime
`test`	Test dependencies

For an ephemeral MCP start:

uvx --from "systems-manager[mcp]" systems-manager-mcp --transport stdio

The checked-in mcp_config.json is a reference-only client catalog. It contains env:// references and safe deny defaults, never deployment endpoints, credentials, certificate paths, filesystem paths, hostnames, or identities. Project-specific values belong in AgentConfig or the process launcher.

Security contract

Network MCP listeners require configured authentication. Non-loopback listeners also require direct TLS or a trusted TLS-stop proxy, exact allowed hosts, and the current Agent Connector SDK transport checks.
Host mutations are denied unless SYSTEMS_MANAGER_ALLOW_HOST_MUTATIONS=true and the individual request receives destructive-operation approval.
Managed-file writes also require SYSTEMS_MANAGER_ALLOW_FILESYSTEM_MUTATIONS=true.
Sensitive reads and active probes have independent default-deny gates.
Managed paths are confined beneath an explicit SYSTEMS_MANAGER_FILESYSTEM_ROOT; there is no working-directory fallback.
Raw shell, arbitrary commands, plaintext credentials, model-authored cron creation, and compatibility command aliases are not capabilities.
Logs and observability are metadata-only. Keep LANGFUSE_CAPTURE_CONTENT=false.

AgentConfig, secrets, and TLS

Use TLS_PROFILE / TLS_PROFILE_REF with TLS_PROFILES_REF for shared checked outbound trust. Service-specific profiles such as OIDC_TLS_PROFILE_REF, MODEL_TLS_PROFILE_REF, and LANGFUSE_TLS_PROFILE_REF may select entries from the same runtime catalog. Do not hardcode CA paths or verification flags in application code, and do not disable verification for incomplete certificate chains.

Out-of-band BMC health reads consume one runtime secret projection from SYSTEMS_MANAGER_BMC_CREDENTIALS. AgentConfig resolves the checked env:// or secret reference before start; the provider accepts exactly a JSON object with host, user, and password. No secret-store vendor, secret path, token, or credential value is embedded in this package.

The MCP listener's own certificate or trusted-proxy boundary uses the current Agent Utilities MCP_TLS_* configuration. The optional agent listener uses SERVER_TLS_* and requires JWT configuration for non-loopback serving.

MCP tools

The default MCP_TOOL_MODE=intent exposes the small intent-verb surface. Backing action-routed tools stay available for governed discovery and on-demand loading. Tool and tag filters can further reduce the visible surface.

Auto-generated from the live MCP server; do not edit between the markers.

Condensed action-routed tools (`MCP_TOOL_MODE=condensed`)

MCP Tool	Toggle Env Var	Description
`capture_system_snapshot`	`OS_PROVIDERTOOL`	Takes a point-in-time snapshot of the system state (CPU, RAM, Processes).
`get_management_capabilities`	—
`get_network_connections`	`OS_PROVIDERTOOL`	Maps active TCP/UDP endpoints directly to owning processes.
`get_process_details`	`OS_PROVIDERTOOL`	Retrieves deep cross-platform process details (threads, modules, memory).
`health_check`	—
`list_kernel_modules`	`OS_PROVIDERTOOL`	List loaded drivers/modules (lsmod or driverquery).
`list_services`	`OS_PROVIDERTOOL`	Cross-platform service enumeration (systemctl or Get-Service).
`manage_service`	`OS_PROVIDERTOOL`	Start/Stop/Restart/Enable/Disable services cross-platform.
`query_system_logs`	`OS_PROVIDERTOOL`	Cross-platform log querying (journalctl or Get-WinEvent).
`sm_advanced_operations`	—	Operations for SSH and specialized managers
`sm_agent_identity_operations`	`IDENTITYTOOL`	Issues or verifies privacy-preserving agent identities.
`sm_agent_scheduler_operations`	`AGENT_HEALTHTOOL`	Manages the cognitive scheduler: get stats, list processes, preempt, or reset quota.
`sm_agent_specialist_operations`	`SPECIALIST_REGISTRYTOOL`	Manages specialist packages: install, uninstall, list, or search.
`sm_agent_watchdog_operations`	`WATCHDOGTOOL`	Manages file watchdog triggers: check file change, list active watchers, or drain triggers.
`sm_cron_operations`	—	Operations for cron jobs
`sm_disk_operations`	—	Operations for managing system disks
`sm_file_operations`	—	Operations for file and log management
`sm_firewall_operations`	—	Operations for firewall management
`sm_network_operations`	—	Operations for network analysis
`sm_process_operations`	—	Operations for managing system processes
`sm_service_operations`	—	Operations for managing system services
`sm_storage_health`	`STORAGE_HEALTHTOOL`	Physical disk + BMC drive-fault health: SMART (incl. megaraid passthrough),
`sm_system_operations`	—	System operations for managing packages, system health, and updates
`sm_user_operations`	—	Operations for user and group management
`start_system_trace`	`OS_PROVIDERTOOL`	Start a kernel-level event trace (ETW on Windows, or strace on Linux).
`stop_system_trace`	`OS_PROVIDERTOOL`	Stop a kernel-level event trace.
`systems_ingest_host`	—	Ingest a keyed host telemetry projection through the governed ChangeEnvelope boundary as typed HardwareNode, NetworkInterface, and DiskVolume nodes.

27 action-routed tool(s) · 0 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (intent default — the six verb-tools, granular set loaded on demand · condensed action-routed · verbose 1:1 · both). Auto-generated — do not edit.

Typical backing domains include OS/package lifecycle, services, processes, networks, disks, managed files, cron removal, structured firewall rules, storage/BMC diagnostics, Agent OS administration, and governed host telemetry ingestion. Discover an action schema before calling it; unavailable operations must not be emulated with another tool.

Knowledge-graph ingestion

systems_ingest_host reads local typed telemetry and submits an allowlisted projection through the Agent Connector SDK native governed ingestion boundary. It emits only:

HardwareNode, NetworkInterface, and DiskVolume nodes;
hasInterface and hasVolume relationships;
HMAC-SHA-256 opaque identifiers derived with the deployment-owned SYSTEMS_MANAGER_PSEUDONYMIZATION_KEY.

Hostnames, network addresses, hardware addresses, usernames, local paths, credentials, and arbitrary extra fields are rejected or excluded. Missing graph authority, invalid content, and unavailable ingestion fail explicitly; they are not silent no-ops.

Arbora delegation

Host operations run inside the service's local operating-system boundary. For fleet work, Arbora delegates to an authenticated systems-manager service on the target boundary. Inventory, endpoints, credentials, TLS profiles, and target aliases remain external deployment configuration. Persist only opaque, non-personal references.

The bundled systems-manager-operations skill covers every current provider workflow. Older BMC command and NIC-bond script skills were consolidated because those raw-script surfaces are not part of the typed current contract.

Agent server

Install the agent extra and start:

systems-manager-agent --help

Workspace, MCP catalog, and custom-skill paths are accepted only when explicitly configured and present. There is no packaged-config or current-directory fallback. A non-loopback listener requires an explicit allow gate, direct or trusted-proxy TLS, JWT issuer/JWKS/audience configuration, and debug mode disabled.

Environment variables

The generated table is sourced from the value-free .env.example plus the inherited Agent Connector SDK contract.

Package environment variables

Variable	Example	Description
`SYSTEMS_MANAGER_FILESYSTEM_ROOT`	—	Required managed filesystem boundary
`SYSTEMS_MANAGER_TEMP_ROOT`	—	Optional cleanup root beneath the managed boundary
`SYSTEMS_MANAGER_PSEUDONYMIZATION_KEY`	secret-injected	Deployment-owned secret, at least 32 bytes
`SYSTEMS_MANAGER_BMC_CREDENTIALS`	—	Secret-projected JSON with host/user/password
`TLS_PROFILE`	—	Shared mandatory-verification transport profile
`TLS_PROFILES_REF`	—	Runtime reference to the transport profile catalog
`LANGFUSE_TLS_PROFILE_REF`	—	Runtime reference to verified Langfuse trust
`MCP_TOOL_MODE`	`intent`	Current intent-first tool surface
`SYSTEMS_MANAGER_ALLOW_HOST_MUTATIONS`	`false`	Default-deny host mutations
`SYSTEMS_MANAGER_ALLOW_FILESYSTEM_MUTATIONS`	`false`	Default-deny file mutations
`SYSTEMS_MANAGER_ALLOW_SENSITIVE_READS`	`false`	Default-deny sensitive inventory
`SYSTEMS_MANAGER_ALLOW_NETWORK_PROBES`	`false`	Default-deny active probes
`SYSTEMS_MANAGER_MAX_BLOCKING_OPERATIONS`	`2`	Bounded host-operation concurrency
`SYSTEMS_MANAGER_HEALTH_INGEST`	`true`	Enable governed health trend ingestion
`SYSTEMS_MANAGER_HEALTH_AGGREGATE_S`	`3600`	Health trend aggregation window
`SYSTEMS_MANAGER_NODE_REF`	—	Runtime node alias; only a keyed digest persists
`SYSTEMS_MANAGER_NOTIFY_TLS_PROFILE`	—	Optional inline mandatory-verification notification TLS profile
`SYSTEMS_MANAGER_NOTIFY_TLS_PROFILE_REF`	—	Runtime reference to the notification TLS profile
`SYSTEMS_MANAGER_MCP_IMAGE_DIGEST`	—	Required immutable MCP image digest
`SYSTEMS_MANAGER_REPOSITORY_ALLOWLIST_JSON`	`[]`	Approved credential-free repositories
`SYSTEMS_MANAGER_LOCAL_PACKAGE_SHA256_MAP`	`{}`	Approved package paths and digests
`SYSTEMS_MANAGER_COMMAND_TIMEOUT_SECONDS`	`120`	Default command timeout
`SYSTEMS_MANAGER_ENV_METADATA_ALLOWLIST`	—	Non-sensitive environment names readable as metadata
`SYSTEMS_MANAGER_UV_VERSION`	—	Exact approved uv release
`SYSTEMS_MANAGER_NVM_COMMIT`	—	Exact approved NVM commit
`SYSTEMS_MANAGER_NVM_DIR`	—	NVM directory beneath the managed filesystem root
`ALLOW_UPDATE_ON_K8S`	`false`	Keep Kubernetes lifecycle guard enabled
`MISCTOOL`	`true`	Register base health/readiness tools
`OS_PROVIDERTOOL`	`true`	Register operating-system provider tools
`STORAGE_HEALTHTOOL`	`true`	Register storage health tools
`TRANSPORT`	`stdio`	Local MCP transport
`HOST`	`127.0.0.1`	Loopback bind for HTTP transports
`PORT`	`8000`	Bind port for HTTP transports
`ENABLE_OTEL`	`false`	Enable only with an approved collector

Inherited agent-connector-sdk variables (apply to every connector)

Variable	Example	Description
`MCP_ENABLED_TOOLS`	—	Comma-separated tool allow-list
`MCP_DISABLED_TOOLS`	—	Comma-separated tool deny-list
`MCP_ENABLED_TAGS`	—	Comma-separated tag allow-list
`MCP_DISABLED_TAGS`	—	Comma-separated tag deny-list
`EUNOMIA_TYPE`	`none`	Authorization mode: `none` \| `embedded` \| `remote`
`EUNOMIA_POLICY_FILE`	`mcp_policies.json`	Embedded Eunomia policy file
`EUNOMIA_REMOTE_URL`	—	Remote Eunomia authorization server URL
`OTEL_EXPORTER_OTLP_ENDPOINT`	—	OTLP collector endpoint
`MCP_CLIENT_AUTH`	—	Outbound MCP child auth: `oidc-client-credentials` \| `basic` \| `none`
`OIDC_CLIENT_ID`	—	OIDC client id (service-account auth)
`OIDC_CLIENT_SECRET_REF`	`secret://identity/oidc-client-secret`	Runtime secret reference for the OIDC service account
`MCP_BASIC_AUTH_USERNAME`	—	HTTP Basic username (`MCP_CLIENT_AUTH=basic`)
`MCP_BASIC_AUTH_PASSWORD_REF`	`secret://identity/mcp-basic-password`	Runtime secret reference for HTTP Basic auth (`MCP_CLIENT_AUTH=basic`)
`DEBUG`	`False`	Verbose logging
`PYTHONUNBUFFERED`	`1`	Unbuffered stdout (recommended in containers)
`MCP_URL`	`http://localhost:8000/mcp`	URL of the MCP server the agent connects to
`PROVIDER`	`openai`	LLM provider for the agent
`MODEL_ID`	`gpt-4o`	Model id for the agent
`ENABLE_WEB_UI`	`True`	Serve the AG-UI web interface

51 package + 19 inherited variable(s). Auto-generated from .env.example + the shared agent-connector-sdk set — do not edit.

Development and release gates

pytest -q
ruff check systems_manager tests
black --check systems_manager tests
mkdocs build --strict
pre-commit run --all-files

Run host operations only through mocks during tests. Do not run native builds or live host mutations as a validation shortcut. The source dependency floor is intentionally agent-connector-sdk>=2.0.0; regenerate and commit a neutral lock only after that release is available from the configured package index. Never commit an editable local source or a stale dependency resolution.

See the documentation for installation, deployment, configuration, usage, multi-host delegation, and security details.

Governed capability contract

This package ships a compact canonical skill surface with specialist procedures kept as referenced workflows. The current MCP tools, skill metadata, connector_manifest.yml, ontology, mappings, shapes, fixtures, migrations, tool-schema fingerprints, and certification metadata form one versioned capability contract. Validate them together; do not rely on stale tool names or historical per-task skill wrappers.

Runtime endpoints, credentials, certificate trust, tenant identity, retention, and observability policy are deployment inputs and are never packaged values. See Configuration, trust, and privacy before enabling a network transport, connector ingestion, Arbora delegation, or trace export.

Development Status
- 5 - Production/Stable
Environment
- Console
License
- Public Domain
Operating System
- POSIX :: Linux
Programming Language
- Python :: 3

Metadata

Development Status
- 5 - Production/Stable
Environment
- Console
License
- Public Domain
Operating System
- POSIX :: Linux
Programming Language
- Python :: 3

Release files for systems-manager 2.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for systems-manager 2.2.3
File	Size	Uploaded	Provenance
systems_manager-2.2.3.tar.gz	875.8 kB	Oct 23, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for systems-manager 2.2.3
File	Interpreter	ABI	Platform	Reset
systems_manager-2.2.3-py3-none-any.whl 146.7 kB Oct 23, 2026 Without provenance	Python 3	none	any	Details

Total release size: 1.0 MB

Release files / systems_manager-2.2.3.tar.gz

Download URL	systems_manager-2.2.3.tar.gz
Size	875.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`28591599fe7adc6d66ea1df877dc39f357a1e34e8bf44460a88618c8437fbffe`
BLAKE2b-256 checksum How to use checksums	`527bc0beee05f95867bb0e2d5920e84bf8ed32d16840735817c94ebea4252702`
Upload date	Oct 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.4`

Release files / systems_manager-2.2.3-py3-none-any.whl

Download URL	systems_manager-2.2.3-py3-none-any.whl
Size	146.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3acc024bbf04f65397b3bf43b0dd1fd52c75bc793c9bac4375e9c62106293449`
BLAKE2b-256 checksum How to use checksums	`9cdc633839c777d5115a90343c2645a5bb38972994760c2fc75cfa2317483e1f`
Upload date	Oct 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.4`

Security for systems-manager 2.2.3

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.