systems-manager
Version: 2.2.1
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=trueand 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, andDiskVolumenodes;hasInterfaceandhasVolumerelationships;- 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_NODE_REFS |
— | Runtime aliases for governed derivation |
SYSTEMS_MANAGER_NOTIFY_URL |
— | Optional credential-free HTTPS notification target |
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_AGENT_IMAGE_DIGEST |
— | Required immutable agent 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 |
AGENT_HEALTHTOOL |
true |
Register agent health tools |
IDENTITYTOOL |
true |
Register identity tools |
SPECIALIST_REGISTRYTOOL |
true |
Register specialist registry tools |
WATCHDOGTOOL |
true |
Register filesystem watchdog tools |
MAX_CONCURRENT_AGENTS |
5 |
Agent scheduler limit |
AGENT_POLICIES_PATH |
— | Runtime policy location |
PERMISSIONS_SIGNING_KEY |
secret-injected | Runtime secret projection for identity signing |
SPECIALIST_REGISTRY_PATH |
— | Runtime specialist registry location |
MCP_CONFIG_PATH |
— | Runtime MCP catalog location |
PROJECT_ROOT |
— | Runtime automation boundary |
WORKSPACE_PATH |
— | Explicit agent workspace directory |
TRANSPORT |
stdio |
Local MCP transport |
HOST |
127.0.0.1 |
Loopback bind for HTTP transports |
PORT |
8000 |
Bind port for HTTP transports |
SYSTEMS_MANAGER_ALLOW_REMOTE_AGENT_SERVER |
false |
Explicit non-loopback agent-listener gate |
ENABLE_OTEL |
false |
Enable only with an approved collector |
LANGFUSE_CAPTURE_CONTENT |
false |
Never capture host/tool content |
SERVER_TRUSTED_PROXY_CIDRS |
— | Trusted proxy networks for a remotely served agent |
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.
1 maintainer
Metadata
1 maintainer
Release files for systems-manager 2.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| systems_manager-2.2.1-py3-none-any.whl | Python 3 | none | any | Details |
Release files / systems_manager-2.2.1-py3-none-any.whl
| Download URL | systems_manager-2.2.1-py3-none-any.whl |
|---|---|
| Size | 145.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c9c66cfcd2f4e3e28df43f0e22ed746242db61471b38af0f1cc9a9a04c692a84
|
|
BLAKE2b-256 checksum How to use checksums |
db7958fc0cc38e210f0a7bf822fda05aad9505e7346645f5cdeecdb386c78dca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
