Structured, typed, cross-platform access to kernel-level OS information -- built for AI agents.

Like fungal mycelium threading through soil to surface nutrients, Mycelium threads through /proc, /sys, and OS APIs to surface clean, structured system data. AI agents connect via MCP and get typed JSON instead of parsing raw shell output.

Note: This is a personal learning project built for reverse engineering and educational purposes. I built Mycelium to deepen my understanding of Rust, systems programming, eBPF, and cross-platform OS internals. Features like process memory access, hook detection, persistence scanning, and eBPF tracing exist for learning and security research -- not for malicious use. Contributions and feedback are welcome, but expect rough edges.

• 🔍 50 tools across 10 categories (process, memory, network, storage, system, tuning, services, logs, security, probes)
• 🛡️ Policy engine with role presets, capability groups, resource filters, and specificity-based evaluation
• 📊 Dual output -- human-readable tables or structured JSON
• 🧩 Modular workspace -- zero-dependency core, pluggable OS backends
• 🔒 Audit logging with per-agent tracking and dry-run mode
• ⚡ Stateless & synchronous -- every call reads fresh kernel data, no caching

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   AI Agent   │     │   mycelium   │     │   Your App   │
│  (MCP client)│     │     CLI      │     │  (Rust lib)  │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │ JSON-RPC           │ direct             │ direct
       ▼                    ▼                    ▼
┌──────────────────────────────────────────────────────┐
│                   mycelium-core                      │
│          Platform trait · Policy · Types              │
└───────────────────────┬──────────────────────────────┘
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
      ┌──────────────┐    ┌──────────────┐
      │ mycelium-    │    │ mycelium-    │
      │ linux        │    │ windows      │
      │ /proc  /sys  │    │ WMI  winreg  │
      └──────────────┘    └──────────────┘
            ✅                  ✅

# CLI
cargo build --release -p mycelium-cli

# MCP server
cargo build --release -p mycelium-mcp

Start the MCP server on stdio for AI agent integration:

# Default (no policy restrictions)
mycelium-mcp

# With policy and agent identity
mycelium-mcp --config policy.toml --agent deploy-bot

The server speaks JSON-RPC over stdin/stdout (MCP protocol 2024-11-05). All 50 tools are registered and discoverable via tools/list. Policy enforcement and audit logging apply to every tool call.

Claude Desktop / MCP client config:

{
  "mcpServers": {
    "mycelium": {
      "command": "/path/to/mycelium-mcp",
      "args": ["--config", "/path/to/policy.toml", "--agent", "claude"]
    }
  }
}

mycelium system info

# System overview
mycelium system info
mycelium system cpu
mycelium memory info

# Processes
mycelium process list
mycelium process inspect 1
mycelium process resources 1823

# Network
mycelium network interfaces
mycelium network connections
mycelium network ports

# Storage
mycelium storage disks
mycelium storage mounts
mycelium storage io

# Services & logs
mycelium service list
mycelium service status sshd
mycelium log -u sshd -l warning -n 10

# Security
mycelium security users
mycelium security modules
mycelium security status

# Kernel tunables
mycelium tuning get net.ipv4.ip_forward
mycelium tuning list net.ipv4

Add --json before any command for structured output:

mycelium --json process list

[
  {
    "pid": 1,
    "ppid": 0,
    "name": "systemd",
    "state": "Sleeping",
    "user": "root",
    "uid": 0,
    "threads": 1,
    "cpu_percent": 0.0,
    "memory_bytes": 12648448,
    "command": "/sbin/init",
    "start_time": 1709312400
  }
]

Control what each agent can do with role-based presets and fine-grained rules.

# policy.toml
[global]
default_profile = "operator"

[[global.rules]]
action = "allow"
target = "all"

[[global.rules]]
action = "deny"
target = { capability = "probe_manage" }
reason = "eBPF probes disabled globally"

# Full admin for trusted agents
[profiles.claude-code]
role = "admin"

# Restricted bot -- can only restart specific services
[profiles.deploy-bot]
role = "operator"

[[profiles.deploy-bot.rules]]
action = "allow"
target = { tool = "service_action" }
filter = { service_names = ["nginx", "postgresql", "redis"] }

[[profiles.deploy-bot.rules]]
action = "deny"
target = { tool = "service_action" }
reason = "Only nginx, postgresql, redis allowed"

# Read-only monitoring
[profiles.monitor-bot]
role = "read-only"
dry_run = true

Roles: admin (full access) · operator (reads + process/service management) · read-only (reads only) · custom (fully user-defined)

Capabilities: process_manage · kernel_tune · firewall_manage · service_manage · probe_manage · policy_manage · memory_access

mycelium --config policy.toml policy show --profile deploy-bot
mycelium --config policy.toml policy list
mycelium policy validate policy.toml

Global flags: --json · --dry-run · --config <PATH>

See TODO.md for detailed phase breakdowns.

# Build
cargo build --workspace

# Test (245 passing)
cargo test --workspace

# Lint
cargo clippy --workspace -- -D warnings

# Format
cargo fmt --all -- --check

Requirements: Rust 2024 edition (rustc 1.85+), Linux or Windows

eBPF probes (optional): Requires bpf-linker, nightly Rust, kernel 5.8+, root/CAP_BPF at runtime:

cargo install bpf-linker
cargo build --workspace --features mycelium-linux/ebpf

MIT