High-level handler for interactive Python execution.

The Sandbox automates the start/resume loop by dispatching name lookups, function calls, dataclass method calls, and OS calls to handler callbacks.

External function names are auto-detected at runtime: when Python code references an undefined name, the sandbox checks the :functions map and :handler module to decide whether to provide a function object or raise NameError. No upfront declaration of external functions is needed.

Dataclass method calls are dispatched through the same function handlers as regular external function calls. The method name is looked up in the :functions map or dispatched to handle_function/3 in the :handler module.

Module-based Handler

defmodule MyHandler do
  @behaviour ExMonty.Sandbox

  @impl true
  def handle_function("fetch", [url], _kwargs) do
    case Req.get(url) do
      {:ok, resp} -> {:ok, resp.body}
      {:error, _} -> {:error, :runtime_error, "fetch failed"}
    end
  end

  @impl true
  def handle_os(:read_text, [{:path, path}], _kwargs) do
    case File.read(path) do
      {:ok, content} -> {:ok, content}
      {:error, reason} -> {:error, :file_not_found_error, to_string(reason)}
    end
  end
end

{:ok, result, output} = ExMonty.Sandbox.run(code,
  inputs: %{"url" => "https://example.com"},
  handler: MyHandler,
  limits: %{max_duration_secs: 5.0}
)

Function Map Handler

{:ok, result, output} = ExMonty.Sandbox.run(code,
  inputs: %{"x" => 1},
  functions: %{
    "fetch" => fn [url], _kwargs -> {:ok, "response"} end
  }
)

Clock Handlers

date.today() and datetime.now() are surfaced as :date_today and :datetime_now os calls. Provide handlers in the :os map to control what "now" means (deterministic tests, time-travel, request timestamps, etc.):

now = DateTime.utc_now()

{:ok, _result, _} = ExMonty.Sandbox.run(
  "from datetime import datetime, timezone\ndatetime.now(tz=timezone.utc).year",
  os: %{
    datetime_now: fn _args, _kwargs ->
      {:ok, {:datetime, %{
        year: now.year, month: now.month, day: now.day,
        hour: now.hour, minute: now.minute, second: now.second,
        microsecond: elem(now.microsecond, 0),
        offset_seconds: 0, tz_name: nil
      }}}
    end
  }
)

Host Filesystem Mounts

For sandboxed access to real host directories, pass an ExMonty.Mount as the :mounts option:

mounts =
  ExMonty.Mount.new!()
  |> ExMonty.Mount.add!("/data", "/var/lib/myapp/data", :read_only)

ExMonty.Sandbox.run(code, mounts: mounts)

:mounts composes with :os — mounts handle filesystem calls, the :os map handles non-filesystem fallbacks (:getenv, :datetime_now, etc.). See ExMonty.Mount for mode semantics, lease lifecycle, and security guarantees.

Pseudo Filesystem

Pass an ExMonty.PseudoFS as the :os option for sandboxed filesystem access:

fs = ExMonty.PseudoFS.new()
  |> ExMonty.PseudoFS.put_file("/data/input.txt", "hello world")

{:ok, result, output} = ExMonty.Sandbox.run(
  "from pathlib import Path; Path('/data/input.txt').read_text()",
  os: fs
)