rubyrs is an embedding API. The host process gives a script some compute, some memory, and (optionally) some host functions. What the script can do with those resources is what this document is about.

The shortest summary: rubyrs is not a sandbox. It is a hardening layer for one component of a sandbox. The cap machinery described here defends against accidental and moderately-adversarial scripts. For seriously hostile input (rubygems.org gemspecs, paid tenants, network-sourced plugins), you must combine rubyrs with OS-level sandboxing or run the WebAssembly build inside wasmtime. The boundaries below say exactly when each level applies.

The intent of "semi-trusted" is "won't take down the host process when the script misbehaves." The intent of "untrusted" is "the host process is intact even if the script is actively hostile." Those are different commitments.

Every cap is Option<T> on Config; None (the default) means unlimited. For the semi-trusted profile, set them like this:

use std::time::Duration;
use rubyrs::{Config, Runtime};

let mut rt = Runtime::with_config(Config {
    // Bounded execution cost. ~1M ops finishes a small Brewfile
    // with headroom. Adjust to your workload.
    fuel: Some(1_000_000),
    // Defends "build a giant data structure" attacks.
    max_heap_objects: Some(10_000),
    // Defends `def f; f; end; f` recursion before our Rust
    // stack overflows.
    max_frames: Some(256),
    // Wall-clock budget — fuel measures ops, this catches
    // "slow per op" cases like a host function that blocks.
    deadline: Some(Duration::from_secs(2)),
    // Cap the interner so `to_sym` in a loop can't grow the
    // symbol table without bound. The preamble + your DSL's
    // own method names already consume ~50–100 symbols, so
    // size relative to `rt.symbol_count()` after a warmup eval.
    max_symbols: Some(10_000),
    // Per-value byte cap. Catches `"a" * 10_000_000` and
    // friends. 1 MB is generous; tune to the maximum string /
    // array you actually expect.
    max_value_bytes: Some(1_048_576),
    ..Default::default()
});

Each cap can be set independently. They compose: a script that trips any of them gets a ResourceExhausted Trap and eval returns.

ResourceExhausted is the trap raised by every cap. It is deliberately rooted under Exception, not under StandardError. That placement means:

• Bare rescue => e (CRuby's default rescue StandardError => e) does not catch it. A hostile script can't loop in a rescue clause to burn through fuel.
• Even an explicit rescue Exception => e does not catch it. The trap is a host-level Result::Err(Trap) raised directly out of Vm::run — it bypasses unwind_with_exception entirely and never appears as a Ruby exception to the script. The trap is not recoverable from inside the Ruby layer by design.
• The host can choose to retry — construct a fresh Runtime::with_config(...) and re-evaluate. That's a host-side decision, where it belongs.

This is the same shape CRuby uses for SystemExit and Interrupt. See ADR 0008 for the full reasoning.

The caps cover what they cover, but there are residual risks the host should be aware of.

Runtime::new() constructs a runtime with no caps. That's the right default for the most common case — a developer running a script they wrote themselves on a workstation they own. The semi-trusted and untrusted profiles are explicit opt-in: a host that takes scripts from less-than-fully-trusted sources has to think about it.

If you find yourself reaching for "I want safe defaults", you probably want the semi-trusted profile copy-pasted above.

Security-relevant bugs (anything in the table above that you can reproduce, plus any panic reachable from a script the host fed eval) should be filed on the rubyrs issue tracker or emailed to the maintainer. Please don't disclose publicly until a fix has shipped.

The current panic audit lives in PANIC_AUDIT.md. A user-reachable panic is treated as a security bug — see also ADR 0008.