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_fuelandmax_lifetimelimits 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:
Kettlecorn- evaluate code, call and cast to guest GenServers, exchange messages, and answer host calls.Kettlecorn.start_link/1- start a VM and configure boot and event delivery.Kettlecorn.Sandbox- resource limits, network grants, guest code, and caching.
Start with Getting started, then Working with guest VMs. Both install the published package and runtime. The remaining notebooks are independent:
- Use cases: user code, plugins, and submission tests.
- Network access: sockets, HTTP, and denied operations.
- Validating guest data: constructors and nested results.
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/.