Runtime Manual/Agent & Advanced/Agent Deterministic Sandbox & Hard Resource Quotas

Agent Deterministic Sandbox & Hard Resource Quotas

CPU Watchdog interrupts, V8 heap quotas, deterministic seed PRNG & frozen timestamps

When running untrusted scripts or executing autonomous AI Agent code, basic I/O sandboxing is insufficient: runaway loops like while(true){} can pin the host CPU at 100%, and unconstrained memory allocations can trigger system-wide OOM panics.

Amber provides an Agent-native deterministic sandbox and hardware-grade resource quota architecture.

1. The Four Quota Dimensions

Option FlagDimensionUnderlying Mechanism
--timeout <MS>CPU Timeout InterruptIndependent Watchdog thread + IsolateHandle::terminate_execution()
--max-memory <MB>Physical Heap QuotaV8 ResourceConstraints old-generation heap upper bound
--seed <U64>Deterministic RandomnessMulberry32 PRNG replaces standard Math.random()
--freeze-time <TS>Timestamp FreezingFreezes Date.now() to a fixed temporal anchor

2. Usage & Technical Deep-Dive

2.1 CPU Watchdog Hard Interrupt (--timeout)

In typical JavaScript runtimes, a tight CPU-bound infinite loop completely stalls the single event loop. Amber introduces an external watchdog thread architecture:

code
$ amber run --timeout 2000 infinite_loop.ts

If execution exceeds 2000 milliseconds, the watchdog thread forcibly terminates V8 execution:

code
Error: Execution timed out after 2000ms

2.2 Physical Heap Hard Limits (--max-memory)

Prevents Agent scripts from leaking or allocating unbounded buffers:

code
# Strictly cap V8 heap at 128 MB
$ amber run --max-memory 128 mem_heavy_task.ts

2.3 Deterministic Seed PRNG (--seed)

Agent evaluation and benchmark replay require reproducible randomness. Supplying --seed guarantees deterministic outputs:

code
$ amber run --seed 123456789 simulation.ts

Across any machine or platform, Math.random() will yield the exact identical sequence of values.

2.4 Frozen Timestamps (--freeze-time)

Pin the global clock to avoid wall-clock drift:

code
# Pin to 2026-01-01 00:00:00 UTC (1767225600000 ms)
$ amber run --freeze-time 1767225600000 test_date.ts

Date.now() will permanently return the specified value.

3. Production Agent Sandbox Paradigm

Recommended invocation flags for running untrusted Agent tasks:

code
$ amber run \
    --sandbox \
    --timeout 3000 \
    --max-memory 256 \
    --seed 42 \
    --allow-read ./workspace \
    --allow-write ./workspace/output \
    agent_task.ts

Guarantees Achieved:

  1. Loop Immune: Hard-terminates within 3 seconds;
  2. OOM Immune: Bounded to 256MB heap;
  3. Deterministic Replay: Fixed seed allows 100% exact trajectory replay;
  4. Isolated I/O: Access restricted exclusively to ./workspace.
PreviousVS Code Official ExtensionNextDeterministic Agent Replay Engine (amber:replay)