Validated VM options: limits, grants, guest code and runtime.
Kettlecorn.Sandbox.Instance creates the VM's private directory and its
launcher command line.
The guest has access to:
- a private copy of the runtime root (OTP + Elixir
.beamfiles and any:code_paths) mounted at/, created when the VM starts and deleted after confirmed launcher shutdown. A guest can't affect the runtime or other VMs through the file system; - the runtime's
launch/envvariables, with:envoverrides; host environment variables are not inherited, - a fixed host name,
localhost(never the host's), - stdin/stdout for the frame protocol.
Guest writes are not size-limited by Wasmtime: put
:instances_dir on a size-limited file system (e.g. a tmpfs) if guests
must not be able to fill your disk.
By default it has no network access, cannot spawn OS processes and cannot load native code.
Options
:max_memory(pos_integer/0) - Linear memory cap in bytes. Allocations that exceed it fail and can terminate the VM. The default value is536870912.:max_lifetime- Wall-clock limit for the whole VM in milliseconds, enforced by Wasmtime and, as a backstop, byKettlecorn.VM. The default value is:infinity.:max_fuel- CPU budget for the whole VM, including boot, in Wasmtime fuel units (roughly Wasm instructions). Exhaustion stops the guest with{:vm_down, :out_of_fuel}. The default value is:infinity.:network(boolean/0) - Allows TCP/UDP sockets and DNS. This allows any destination, including internal addresses; Kettlecorn has no host or port allowlist. The default value isfalse.:cacerts(:host, a PEM file path, or a list of DER certificates) - The CA certificates the guest trusts withnetwork: true::public_key.cacerts_get/0in the guest returns them, and Req uses them.:hostpasses the host's, and a PEM file or a list of DER certificates replaces them. With[], or:hostwithout a host trust store,:public_key.cacerts_get/0and Req HTTPS requests without their own:cacertsraise in the guest. Withhttp: true, Wasmtime uses its compiled Mozilla root CA list; this option does not change those roots. The default value is:host.:http(boolean/0) - AllowsKettlecorn.HTTPrequests throughwasi:httpwithbeam-http.wasm. Req usesKettlecorn.HTTP.ReqAdapter. Allows any destination. The default value isfalse.:schedulers(pos_integer/0) - BEAM schedulers. They run as cooperative threads on one OS thread, so more schedulers add no parallelism. The default value is1.:runtime- Runtime directory. When nil, uses$KETTLECORN_RUNTIME,config :kettlecorn, :runtime, then the runtime installed bymix kettlecorn.install. Its manifest must declare this library's protocol version. SeeKettlecorn.Runtime. The default value isnil.:app- Cooked application directory (seeKettlecorn.Cook). Its applications take precedence over runtime copies. The guest loads itssys.configand starts its entrypoint before reporting that it has booted. The default value isnil.:code_paths(list ofString.t/0) - Extra host directories with.beamfiles, copied into the guest and added to its code path. The default value is[].:instances_dir- Parent directory for each VM's private directory (mode 0700), containing the guest root and the launcher's stderr. When nil, uses the system temporary directory. The default value isnil.:apps(list of application names (atoms or non-empty strings)) - Extra applications to start at boot, available in the runtime,:code_pathsor the cooked app. The default value is[].:env(map or list of environment names to string values) - Extra guest environment variables. Names must be non-empty and contain no=. Names and values must contain no line breaks or NULs. The default value is%{}.:compile_cache(boolean/0) - Cache compiled components in the private per-user cache. The default value istrue.:cache_dir- Override the private component cache directory; unusable caches fall back to compilation. The default value isnil.:emulator_flags(list ofString.t/0) - Extra emulator flags aserlpasses them tobeam: with a dash instead of+, e.g.["-hms", "1000"]for+hms 1000. The default value is[].
Summary
Functions
Builds the sandbox for opts (see the module doc). Raises ArgumentError
for an unknown or invalid option, or a missing or incompatible runtime.
Types
@type t() :: %Kettlecorn.Sandbox{ app: Path.t() | nil, apps: [atom() | String.t()], cacerts: [:public_key.der_encoded()], cache_dir: Path.t() | nil, code_paths: [Path.t()], compile_cache: boolean(), emulator_flags: [String.t()], env: %{required(String.t()) => String.t()}, http: boolean(), instances_dir: Path.t() | nil, max_fuel: pos_integer() | :infinity, max_lifetime: pos_integer() | :infinity, max_memory: pos_integer(), network: boolean(), runtime: Kettlecorn.Runtime.t(), schedulers: pos_integer() }
Functions
Builds the sandbox for opts (see the module doc). Raises ArgumentError
for an unknown or invalid option, or a missing or incompatible runtime.