MuonTrap requires cgroup v2 (the unified hierarchy at /sys/fs/cgroup). To use it, you must perform a one-time setup:

1. Enable controllers at the root: A controller must be enabled in the root's cgroup.subtree_control before it is available to child cgroups. You can do this via CLI or Elixir:

   • CLI: echo +cpu +memory +pids | sudo tee /sys/fs/cgroup/cgroup.subtree_control
   • Elixir: File.write!("/sys/fs/cgroup/cgroup.subtree_control", "+cpu +memory +pids") Note: On systemd hosts, it is often easier to use a slice with Delegate=yes and point cgroup_base to that slice's directory.

2. Create a writable parent directory: Create a directory under /sys/fs/cgroup that MuonTrap can use as a base for creating sub-cgroups, and ensure your user has permissions:

   sudo mkdir -p /sys/fs/cgroup/mycgroup
   sudo chown -R $(whoami) /sys/fs/cgroup/mycgroup

On Nerves, ensure the kernel has CONFIG_CGROUPS, CONFIG_MEMCG, CONFIG_CFS_BANDWIDTH, and CONFIG_CGROUP_PIDS enabled.

If running on Linux with cgroup v2 support, you can use MuonTrap to enforce resource limits (like memory or CPU) using cgroups.

1. Enable controllers: Write to /sys/fs/cgroup/cgroup.subtree_control to enable the desired controllers (e.g., +cpu +memory +pids).
2. Create a base directory: Create a parent directory in /sys/fs/cgroup/ that MuonTrap can use as a base.
3. Set permissions: Ensure the directory is writable (you may need to chown it).
4. Configure the Daemon: Pass cgroup_base and a cgroup map in the options.

MuonTrap will create a unique sub-cgroup under your base directory for the process.

# 1. Enable controllers
File.write("/sys/fs/cgroup/cgroup.subtree_control", "+cpu +memory +pids")

# 2. Create parent directory
File.mkdir_p("/sys/fs/cgroup/mycgroup")

# 3. Use in Daemon
{MuonTrap.Daemon, [
   "long_running_command",
   ["arg1", "arg2"],
   [cgroup_base: "mycgroup", cgroup: %{memory_max: 500_000_000}]
 ]}

MuonTrap provides resource limits (cgroups), but not filesystem or network isolation. To achieve true sandboxing (e.g., for browsers or untrusted code), layer bubblewrap (bwrap) under MuonTrap. MuonTrap manages the lifecycle and resource caps, while bwrap manages namespaces and isolation.

Recommended flags for bwrap:

• --unshare-all: Provides fresh namespaces (PID, network, etc.).
• --die-with-parent: Ensures the sandbox dies if MuonTrap dies.
• --ro-bind / --bind: Controls filesystem visibility.

{MuonTrap.Daemon,
 ["bwrap",
  [
    "--ro-bind", "/usr", "/usr",
    "--ro-bind", "/lib", "/lib",
    "--ro-bind", "/lib64", "/lib64",
    "--proc", "/proc",
    "--dev", "/dev",
    "--bind", "/tmp/browser-home", "/home/browser",
    "--unshare-all",
    "--die-with-parent",
    "--",
    "/usr/bin/my-browser"
  ],
  [
    cgroup_base: "mycgroup",
    cgroup: %{
      memory_max: 536_870_912,
      memory_oom_group: true,
      cpu_max: {50_000, 100_000},
      pids_max: 200
    }
  ]
 ]}

Use MuonTrap.Daemon functions to inspect a running daemon:

• MuonTrap.Daemon.statistics(daemon_pid): Returns output byte counters and a snapshot of all readable cgroup stat files (e.g., memory.current, cpu.stat, pids.current).
• MuonTrap.Daemon.cgroup_config(daemon_pid): Returns the current writable :cgroup configuration map.
• MuonTrap.Daemon.cgroup_path(daemon_pid): Returns the current cgroup path.
• MuonTrap.Daemon.cgget(daemon_pid, "file_name"): Reads a specific raw cgroup interface file.
• MuonTrap.Daemon.cgset(daemon_pid, "file_name", "value"): Writes to a specific cgroup interface file.

# Get all stats
stats = MuonTrap.Daemon.statistics(daemon_pid)

# Get current config
config = MuonTrap.Daemon.cgroup_config(daemon_pid)

# Generic interface access
{:ok, raw} = MuonTrap.Daemon.cgget(daemon_pid, "memory.peak")
:ok = MuonTrap.Daemon.cgset(daemon_pid, "memory.max", "536870912")