MuonTrap

June 2, 2026 · View on GitHub

Hex version API docs CircleCI Coverage Status REUSE status

This is a v2 branch. The v2 releases replace MuonTrap's cgroup v1 support with v2. Non-cgroup APIs remain compatible with v1. See the muontrap maint-v1.x branch for v1.

Keep programs, daemons, and applications launched from Erlang and Elixir contained and well-behaved. This lightweight library kills OS processes if the Elixir process running them crashes and if you're running on Linux, it can use cgroups to prevent many other shenanigans.

Some other features:

  • Attach your OS process to a supervision tree via a convenient child_spec
  • Set cgroup controls like thresholds on memory and CPU utilization
  • Start OS processes as a different user or group
  • Send SIGKILL to processes that aren't responsive to SIGTERM
  • With cgroups, get lots of resource usage statistics on the process and all children

MuonTrap can certainly run an LLM, but sandboxing it to limit network access, for example, is not supported. Look at tools like bubblewrap.

TL;DR

Add muontrap to your project's mix.exs dependency list:

def deps do
  [
    {:muontrap, "~> 2.0.0-rc.0"}
  ]
end

Run a command similar to System.cmd/3:

iex>  MuonTrap.cmd("echo", ["hello"])
{"hello\n", 0}

Attach a long running process to a supervision tree using a child_spec like the following:

{MuonTrap.Daemon, ["long_running_command", ["arg1", "arg2"], options]}

If you're running on Linux or Nerves with cgroup v2 support enabled, set up a parent cgroup once:

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

# Create a parent directory MuonTrap can write under:
File.mkdir_p("/sys/fs/cgroup/mycgroup")

# You may need to chown the path

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

MuonTrap will create a sub-cgroup under mycgroup to run long_running_command. If the command fails, it will be restarted. If it should no longer be running (e.g., something crashed in Elixir and supervision is cleaning up), then MuonTrap will kill long_running_command and all of its children.

MuonTrap 2.0 dropped cgroup v1. v2 (the unified hierarchy) is commonly available these days. If you're stuck on v1, pin to MuonTrap 1.x.

Want to know more about the motivations for this library? Read on in the Background section.

FAQ

How do I watch stdout?

If you're using MuonTrap.cmd/3, you don't get the called program's output until after it exits. Just like System.cmd/3, the :into option can be used to get the output as it's printed. Here's an example.

MuonTrap.cmd("my_program", [], stderr_to_stdout: true, into: IO.binstream(:stdio, :line))

If you're using MuonTrap.Daemon, then the best way is to send output to the logger. There are quite a few options, so see the MuonTrap.Daemon docs on what makes sense for you.

How do I stop a MuonTrap.Daemon?

Treat the MuonTrap.Daemon process just like any other Elixir process. If you put it in a supervision tree, call Supervisor.terminate_child/2. If you have it's pid, call Process.exit/2.

How do I delay a daemon until a dependency is ready?

Pass a 0-arity function via the :wait_for option. It runs in a linked Task before the OS process is launched, so it can block (e.g., poll a TCP port or wait on a file) without holding up the supervisor. The Daemon launches the command once the function returns; if it raises, the link tears the Daemon down and the supervisor's restart policy applies.

{MuonTrap.Daemon,
 ["my_server", [],
  [wait_for: fn -> wait_for_tcp_port("db", 5432) end]]}

Background

The Erlang VM's port interface lets Elixir applications run external programs. This is important since it's not practical to rewrite everything in Elixir. Plus, if the program is long running like a daemon or a server, you use Elixir to supervise it and restart it on crashes. The catch is that the Erlang VM expects port processes to be well-behaved. As you'd expect, many useful programs don't quite meet the Erlang VM's expectations.

For example, let's say that you want to monitor a network connection and decide that ping is the right tool. Here's how you could start ping in a process.

iex> pid = spawn(fn -> System.cmd("ping", ["-i", "5", "localhost"], into: IO.stream(:stdio, :line)) end)
#PID<0.6116.0>
PING localhost (127.0.0.1): 56 data bytes
64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.032 ms
64 bytes from 127.0.0.1: icmp_seq=1 ttl=64 time=0.077 ms

To see that ping is running, call ps to look for it. You can also do this from a separate terminal window outside of IEx:

iex> :os.cmd('ps -ef | grep ping') |> IO.puts
  501 38820 38587   0  9:26PM ??         0:00.01 /sbin/ping -i 5 localhost
  501 38824 38822   0  9:27PM ??         0:00.00 grep ping
:ok

Now exit the Elixir process. Imagine here that in the real program that something happened in Elixir and the process needs to exit and be restarted by a supervisor.

iex> Process.exit(pid, :oops)
true
iex> :os.cmd('ps -ef | grep ping') |> IO.puts
  501 38820 38587   0  9:26PM ??         0:00.02 /sbin/ping -i 5 localhost
  501 38833 38831   0  9:34PM ??         0:00.00 grep ping

As you can tell, ping is still running after the exit. If you run :observer you'll see that Elixir did indeed terminate both the process and the port, but that didn't stop ping. The reason for this is that ping doesn't pay attention to stdin and doesn't notice the Erlang VM closing it to signal that it should exit.

Imagine now that the process was supervised and it restarts. If this happens a regularly, you could be running dozens of ping commands.

This is just one of the problems that muontrap fixes.

Applicability

This is intended for long running processes. It's not great for interactive programs that communicate via the port or send signals. That feature is possible to add, but you'll probably be happier with other solutions like erlexec.

Running commands

The simplest way to use muontrap is as a replacement to System.cmd/3. Here's an example using ping:

iex> pid = spawn(fn -> MuonTrap.cmd("ping", ["-i", "5", "localhost"], into: IO.stream(:stdio, :line)) end)
#PID<0.30860.0>
PING localhost (127.0.0.1): 56 data bytes
64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.027 ms
64 bytes from 127.0.0.1: icmp_seq=1 ttl=64 time=0.081 ms

Now if you exit that process, ping gets killed as well:

iex> Process.exit(pid, :oops)
true
iex> :os.cmd('ps -ef | grep ping') |> IO.puts
  501 38898 38896   0  9:58PM ??         0:00.00 grep ping

:ok

Containment with cgroups

Even if you don't set any controller limits, putting your port process in a cgroup is useful by itself: when MuonTrap tears down the cgroup, every descendant process inside it dies too — no orphaned children, no escapees.

Setting up cgroup v2

MuonTrap requires cgroup v2 (the unified hierarchy at /sys/fs/cgroup). Two pieces of one-time setup:

1. Enable the controllers you need at the root. A controller has to be enabled in a cgroup's cgroup.subtree_control before it's available to the children of that cgroup. Most users will do this once at the root:

echo +cpu +memory +pids | sudo tee /sys/fs/cgroup/cgroup.subtree_control

or

File.write!("/sys/fs/cgroup/cgroup.subtree_control", "+cpu +memory +pids")

This only needs to happen before MuonTrap launches its first cgroup-using process — there's no need to wire it into early boot. On Nerves, where the BEAM runs as root, calling File.write!/2 from an application start callback works fine.

On systemd hosts, systemd manages cgroup.subtree_control — usually the easiest path is to put your application in a slice with Delegate=yes, CPUAccounting=yes, MemoryAccounting=yes, etc., and point cgroup_base at that slice's directory. See man 5 systemd.resource-control.

Required kernel options on Nerves: CONFIG_CGROUPS, CONFIG_MEMCG, CONFIG_CFS_BANDWIDTH, CONFIG_CGROUP_PIDS. Some official Nerves systems have this enabled already. If you're on the Raspberry Pi, the bootloader turns off memory cgroups by default since there's a ~1% overhead when enabled.

2. Create a parent directory MuonTrap can write to. Any path under /sys/fs/cgroup works; MuonTrap creates a sub-cgroup beneath it.

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

If MuonTrap can't find the controllers it needs, it will exit with a clear error and tell you which controller is missing.

Running a command in a cgroup

iex> MuonTrap.cmd("spawning_program", [], cgroup_base: "mycgroup", cgroup: %{cpu_weight: 100})
{"hello\n", 0}

MuonTrap creates a temporary sub-cgroup under mycgroup, runs the program in it, and tears it down on exit. Controllers are enabled automatically based on which keys are present in the :cgroup map (here, cpu.* → the cpu controller). If you want a fixed path, use :cgroup_path instead — but make sure nothing else uses that cgroup, since MuonTrap kills everything in it on cleanup.

Cap the memory used by a process

iex> MuonTrap.cmd("memory_hog", [],
       cgroup_base: "mycgroup",
       cgroup: %{memory_max: 268_435_456})

That restricts total memory to 256 MB. When the limit is hit, the kernel invokes the OOM killer; if you also want the whole cgroup to be killed together (rather than one process at a time), set memory.oom.group:

cgroup: %{memory_max: 268_435_456, memory_oom_group: true}

Cap CPU usage

In v2, CPU bandwidth is controlled by cpu.max, expressed as {quota_us, period_us}. Limit a process to 50% of one CPU:

iex> MuonTrap.cmd("cpu_hog", [],
       cgroup_base: "mycgroup",
       cgroup: %{cpu_max: {50_000, 100_000}})

Cap the number of processes (anti-fork-bomb)

cgroup: %{pids_max: 200}

Useful when you're running something that might fork uncontrollably (a compromised browser, an LLM-driven shell, a flaky third-party binary).

Reading current usage and configuration

MuonTrap.Daemon.statistics/1 returns the daemon's output counters plus a snapshot of every readable cgroup stat file under a :cgroup key. The cgroup map is keyed by the v2 interface file name (memory usage and peak, CPU and memory PSI, OOM-kill counts, pids.current, etc.):

%{
  output_byte_count: 295,
  cgroup: %{
    "memory.current" => 552_222_720,
    "memory.peak"    => 555_364_352,
    "memory.events"  => %{"oom_kill" => 0, ...},
    "cpu.stat"       => %{"usage_usec" => 867_248_613, ...},
    "cpu.pressure"   => %{"some" => %{"avg10" => 0.0, ...}, "full" => %{...}},
    "pids.current"   => 42,
    "pids.peak"      => 52,
    ...
  }
} = MuonTrap.Daemon.statistics(daemon_pid)

The :cgroup map is empty when the daemon isn't running under a cgroup.

MuonTrap.Daemon.cgroup_config/1 returns the writable side in the same shape you'd pass to :cgroup, so a running daemon's settings can be cloned into a new one:

%{memory_max: 268_435_456,
  cpu_weight: 100} = MuonTrap.Daemon.cgroup_config(daemon_pid)

"mycgroup/abc"   = MuonTrap.Daemon.cgroup_path(daemon_pid)

For anything outside this set, use the generic interface:

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

The full list of v2 interface files is in man 7 cgroups and the kernel's Documentation/admin-guide/cgroup-v2.rst.

Sandboxing a process (browser, LLM workspace, untrusted binaries)

Cgroups give you resource limits, not isolation. A process that's been capped at 256 MB still has full filesystem, network, and syscall access — if it gets compromised, the attacker can read your secrets, exfiltrate over the network, and so on. For real isolation you need namespaces (mount, PID, net, user, IPC, UTS), seccomp filters, and dropped capabilities.

The simplest way to get that on Linux is bubblewrap (bwrap) — a small setuid helper used by Flatpak. Layer it under MuonTrap: MuonTrap handles lifecycle and resource caps, bwrap handles isolation.

{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
     }
   ]
 ]}

--die-with-parent ensures bwrap (and its child) dies if MuonTrap dies, and --unshare-all puts the program in fresh namespaces so it can't see other processes, your real network stack, or the rest of your filesystem.

For LLM agents that run untrusted code, the same pattern applies, but you likely also want filesystem rollback (overlayfs scratch dir) and a tighter network policy. MuonTrap handles only the lifecycle + resource caps piece; for the rest, look at bwrap, nsjail, or container runtimes (Podman, Firecracker microVMs).

Supervision

For many long running programs, you may want to restart them if they crash. Luckily Erlang already has mechanisms to do this. MuonTrap provides a GenServer called MuonTrap.Daemon that you can hook into one of your supervision trees. For example, you could specify it like this in your application's supervisor:

  def start(_type, _args) do
    children = [
      {MuonTrap.Daemon, ["command", ["arg1", "arg2"], options]}
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end

Supervisors provide three restart strategies, :permanent, :temporary, and :transient. They work as follows:

  • :permanent - Always restart the command if it exits or crashes. Restarts are limited to the Supervisor's restart intensity settings as they would be with normal GenServers. This is the default.
  • :transient - If the exit status of the command is 0 (i.e., success), then don't restart. Any other exit status is considered an error and the command is restarted.
  • :temporary - Don't restart

If you're running more than one MuonTrap.Daemon under the same Supervisor, then you'll need to give each one a unique :id. Here's an example child_spec for setting the :id and the :restart parameters:

    Supervisor.child_spec(
        {MuonTrap.Daemon, ["command", ["arg1"], options]},
         id: :my_daemon,
         restart: :transient
      )

stdio flow control

The Erlang port feature does not implement flow control from messages coming from the port process. Since MuonTrap captures stdio from the program being run, it's possible that the program sends output so fast that it grows the Elixir process's mailbox big enough to cause an out-of-memory error.

MuonTrap protects against this by implementing a flow control mechanism. When triggered, the running program's stdout and stderr file handles won't be read and hence it will eventually be blocked from writing to those handles.

The :stdio_window option specifies the maximum number of unacknowledged bytes allowed. The default is 10 KB.

muontrap development

The cgroup-tagged tests need a muontrap_test cgroup with the cpu and memory controllers available:

# One-time root setup (skip if your system or systemd already enables these):
echo +cpu +memory | sudo tee /sys/fs/cgroup/cgroup.subtree_control

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

To skip cgroup-tagged tests entirely (e.g., on macOS), run mix test --exclude cgroup.

License

All original source code in this project is licensed under Apache-2.0.

Additionally, this project follows the REUSE recommendations and labels so that licensing and copyright are clear at the file level.

Exceptions to Apache-2.0 licensing are:

  • Configuration and data files are licensed under CC0-1.0
  • Documentation is CC-BY-4.0