# `Kettlecorn.Sandbox`
[🔗](https://github.com/mjrusso/kettlecorn/blob/v0.1.0/host/lib/kettlecorn/sandbox.ex#L1)

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` (`t: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` (`t: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` (`t: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` (`t: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 `t: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` (`t: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 `t: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 `[]`.

# `t`

```elixir
@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()) =&gt; 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()
}
```

# `new`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
