Omni.Tools.Repl.Sandbox (Omni Tools v0.3.0)

Copy Markdown View Source

Executes Elixir code in an isolated peer node.

Each invocation starts a fresh Erlang peer node, evaluates the code, captures IO output and the raw return value, then stops the peer. Clean slate per execution — no state carries over between calls.

The host's code paths are injected into the peer, so all compiled modules (including application dependencies) are available. In dev, Mix.install/1 can add additional dependencies since each peer is a fresh VM.

Communication with the peer uses the :peer module's stdio control channel, so no Erlang distribution (EPMD) is required.

The sandbox executes arbitrary code with full system access. It is best-effort isolation, not a security boundary. For trusted use cases only: agent-driven experimentation, scratchpad computation — not adversarial input.

Options

  • :timeout - execution timeout in milliseconds (default: 60_000)
  • :max_output - truncation limit in bytes (default: 50_000)
  • :setup - code evaluated in the peer before the user's code. Setup runs before IO capture begins, so its output is not included. Accepts a string, quoted AST, or a list of either.

Return values

{:ok, %{output: "hello\n", result: :ok}}
{:error, :timeout, %{output: ""}}
{:error, {:error, %ArithmeticError{}, stacktrace}, %{output: ""}}

On success, result is the raw return value of the last expression (not inspected). On error, the second element is either :timeout, :noconnection, or a {kind, reason, stacktrace} triple from the caught exception.

Summary

Types

result()

Result of a sandbox evaluation — success, timeout/disconnect, or exception.

Functions

run(code, opts \\ [])

Evaluates code in a fresh peer node and returns the captured output and raw return value.

Types

result()

@type result() ::
  {:ok, %{output: String.t(), result: term()}}
  | {:error, :timeout | :noconnection, %{output: String.t()}}
  | {:error, {atom(), term(), Exception.stacktrace()}, %{output: String.t()}}

Result of a sandbox evaluation — success, timeout/disconnect, or exception.

Functions

run(code, opts \\ [])

@spec run(
  String.t(),
  keyword()
) :: result()

Evaluates code in a fresh peer node and returns the captured output and raw return value.