Kettlecorn

Kettlecorn runs untrusted Elixir and Erlang in a WebAssembly sandbox. Use it from your Elixir application to evaluate code, call guest GenServers, or run whole Mix applications.

Each VM runs OTP 29 and Elixir 1.20 in a separate Wasmtime process with a private filesystem. Guests cannot start OS processes or load native code. Network access is off by default, and WebAssembly linear memory is capped at 512 MiB. Execution and lifetime limits are opt-in.

Experimental software {: .warning}

Kettlecorn is experimental. It enables Wasmtime's component-model threading, an unfinished feature that Wasmtime leaves off by default.

Bugs in Kettlecorn or its dependencies may compromise isolation. Set finite max_fuel and max_lifetime limits for untrusted workloads. These constrain guest execution; host memory and disk use need separate controls. Review the sandbox's limits and network grants.

Installation

Requires Elixir 1.20 or later on x86_64 or ARM64 Linux or Apple silicon macOS.

def deps do
  [{:kettlecorn, "~> 0.1"}]
end

Fetch the dependency and install the platform runtime:

$ mix deps.get
$ mix kettlecorn.install

The runtime bundles its native launcher and Wasmtime engine; no separate Wasmtime installation is needed. The installer verifies the archive's SHA-256. See mix help kettlecorn.install for installation options.

Usage

{:ok, vm} = Kettlecorn.start_link(max_fuel: 50_000_000_000, max_lifetime: 30_000)

Kettlecorn.eval(vm, ~S"""
IO.puts("This is your BEAM on WASI.")

transactions = [{101, 1_500}, {102, 2_000}, {101, -500}]

Enum.reduce(transactions, %{}, fn {account_id, cents}, totals ->
  Map.update(totals, account_id, cents, &(&1 + cents))
end)
""")
#=> {:ok, %{
#     "value" => %{101 => 1000, 102 => 2000},
#     "inspected" => "%{101 => 1000, 102 => 2000}",
#     "output" => "This is your BEAM on WASI.\n"
#   }}

Kettlecorn.stop(vm)

Evaluation results

Field Contains
"value" The result as plain data, within the evaluator's traversal limit. Omitted for other results.
"inspected" The result's text representation.
"output" Captured standard output.

Writes to stderr go to the VM's console output, available through owner events and Kettlecorn.take_output/1.

VM limits and lifetime

The example sets two limits for the whole VM:

Option Limits
max_fuel Total execution budget, measured roughly in WebAssembly instructions.
max_lifetime: 30_000 Lifetime of 30 seconds.

Both include startup and apply across all evaluations in that VM.

start_link/1 links the VM to its caller: a resource limit or guest crash can terminate that caller. Kettlecorn.run/2 starts a fresh VM, evaluates code once, and stops it afterward. See Managing VM lifetime for unlinked VMs and caller cleanup.

Reuse a VM for repeated evaluations from the same tenant. Give mutually untrusted tenants separate VMs: modules, processes, and files persist between evaluations. See VM reuse.

Erlang use

Pass language: :erlang to Kettlecorn.eval/3 for expressions or module source.

Guest events

With owner: pid, consume guest events and call Kettlecorn.acknowledge(vm) after each one. Exceeding the unacknowledged event count or byte budget stops the VM. See sandbox and resource limits for delivery budgets and host memory and disk controls.

Command line

In a Mix project with the kettlecorn dependency and an installed runtime:

mix kettlecorn.run script.exs arg1 arg2

See the CLI guide for installation, expressions, IEx, and runtime selection.

mix kettlecorn.eval 'Enum.sum(1..10)' uses the host evaluation API and prints the inspected result. Pass --erlang to evaluate Erlang.

Mix applications

mix kettlecorn.cook packages a Mix application and its dependencies for the guest. Start it with Kettlecorn.start_link(app: dir).

Cooking compiles code and evaluates configuration on the host, outside the guest sandbox. Cook trusted projects and dependencies, or isolate the build separately. See Cooking Mix applications.

Compile guest .beam files with the runtime's OTP major release and exact Elixir version, recorded in its manifest.json. This also applies to dependencies loaded through code_paths.

Configuration and deployment

The runtime is separate from the Hex package; include it in your deployment. The installer defaults to your user cache directory. Kettlecorn.Runtime documents discovery and configuration, including KETTLECORN_RUNTIME.

Running applications covers deployment in images and Mix releases. Its troubleshooting section covers runtime discovery, rejected payloads, and VM failures. Guest API documents the modules available inside the VM.

Learn the API

API reference:

Run in Livebook

Start with Getting started, then Working with guest VMs. Both install the published package and runtime. The remaining notebooks are independent:

Lua compares host embedding with guest execution; Internals examines the implementation. See Architecture, Development, and Performance for implementation details and benchmarks.

Kettlecorn builds on Popcorn, which runs Elixir and Erlang in the browser. See the architecture guide for the relationship.

License

Apache-2.0. The runtime contains third-party components under their own licenses; it ships them in licenses/.