Kettlecorn.Sandbox (kettlecorn v0.1.0)

Copy Markdown View Source

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 .beam files 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/env variables, with :env overrides; 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 is 536870912.

  • :max_lifetime - Wall-clock limit for the whole VM in milliseconds, enforced by Wasmtime and, as a backstop, by Kettlecorn.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 is false.

  • :cacerts (:host, a PEM file path, or a list of DER certificates) - The CA certificates the guest trusts with network: true: :public_key.cacerts_get/0 in the guest returns them, and Req uses them. :host passes the host's, and a PEM file or a list of DER certificates replaces them. With [], or :host without a host trust store, :public_key.cacerts_get/0 and Req HTTPS requests without their own :cacerts raise in the guest. With http: true, Wasmtime uses its compiled Mozilla root CA list; this option does not change those roots. The default value is :host.

  • :http (boolean/0) - Allows Kettlecorn.HTTP requests through wasi:http with beam-http.wasm. Req uses Kettlecorn.HTTP.ReqAdapter. Allows any destination. The default value is false.

  • :schedulers (pos_integer/0) - BEAM schedulers. They run as cooperative threads on one OS thread, so more schedulers add no parallelism. The default value is 1.

  • :runtime - Runtime directory. When nil, uses $KETTLECORN_RUNTIME, config :kettlecorn, :runtime, then the runtime installed by mix kettlecorn.install. Its manifest must declare this library's protocol version. See Kettlecorn.Runtime. The default value is nil.

  • :app - Cooked application directory (see Kettlecorn.Cook). Its applications take precedence over runtime copies. The guest loads its sys.config and starts its entrypoint before reporting that it has booted. The default value is nil.

  • :code_paths (list of String.t/0) - Extra host directories with .beam files, 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 is nil.

  • :apps (list of application names (atoms or non-empty strings)) - Extra applications to start at boot, available in the runtime, :code_paths or 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 is true.

  • :cache_dir - Override the private component cache directory; unusable caches fall back to compilation. The default value is nil.

  • :emulator_flags (list of String.t/0) - Extra emulator flags as erl passes them to beam: 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

t()

@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

new(opts)

@spec new(keyword()) :: t()

Builds the sandbox for opts (see the module doc). Raises ArgumentError for an unknown or invalid option, or a missing or incompatible runtime.