systems-manager

Version: 2.1.0

systems-manager is the typed host-operations provider for Agent Utilities and GraphOS. 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-utilities>=2.0.0,<3.0.0.

Install and run

Install only the interface you need:

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

The optional extras are:

For an ephemeral MCP launch:

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.

Related MCP server: SSH MCP Server

Security contract

• Network MCP listeners require configured authentication. Non-loopback listeners also require direct TLS or a trusted TLS-terminating proxy, exact allowed hosts, and the current Agent Utilities transport checks.

• Host mutations are denied unless SYSTEMS_MANAGER_ALLOW_HOST_MUTATIONS=true and the individual request receives destructive-operation approval.

• Managed-file writes additionally 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 verified 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 launch; 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)

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 Utilities 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.

GraphOS delegation

Host operations execute inside the service's local operating-system boundary. For fleet work, GraphOS 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 launch:

pip install "systems-manager[agent]"
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 Utilities contract.

Package environment variables

Inherited agent-utilities variables (apply to every connector)

47 package + 19 inherited variable(s). Auto-generated from .env.example + the shared agent-utilities 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-utilities>=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.

Deploy with agent-utilities-deployment

Provision this package with the consolidated agent-utilities-deployment workflow. It selects an installed-package, editable-source, or immutable-container path; records only runtime secret and TLS-profile references in AgentConfig; and runs doctor, registration, policy, observability, and rollback gates. Ask your agent to "deploy systems-manager with agent-utilities-deployment".

The repository embeds no deployment profile, credential value, certificate path, or environment-specific endpoint. Supply those at runtime through AgentConfig and the configured secret provider.

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, GraphOS delegation, or trace export.