E2B (AI Code Sandbox Runtime)

WHENWriting TypeScript SDK code that calls Sandbox (any e2b npm package consumer scenario).

ACTIONWrap each Sandbox.create() in try/finally and `await sandbox.kill()` in the finally block — the TS Sandbox class does NOT implement Symbol.dispose / Symbol.asyncDispose, so a `using` block does not auto-cleanup.

CONSEQUENCEIf a TS caller misses `await sandbox.kill()`, the sandbox keeps billing until the 5-minute default timeout reclaims it server-side; every leak adds up to 5 minutes of billable time, and long loops or exception paths multiply cost.

WHENImplementing a stateful agent loop that needs to retain in-sandbox filesystem/process/RAM state across multiple conversation turns.

ACTIONPass lifecycle={'on_timeout': 'pause', 'auto_resume': True} explicitly to Sandbox.create() — omitting it equals auto_pause=False (hard-coded at main.py:219), and on timeout the sandbox is KILLED and all state is lost.

CONSEQUENCEWithout a lifecycle config, the sandbox is destroyed at timeout, all filesystem/process/RAM state is lost, the next connect() hits a deleted sandbox raising SandboxNotFoundException, and the agent's multi-turn context chain breaks.

WHENPlanning the maximum duration of a single sandbox task / picking an E2B tier.

ACTIONDo NOT let a single Sandbox task run beyond the tier cap — Hobby tier hard cap is 1h, Pro tier is 24h, enforced server-side; the platform KILLs the sandbox regardless of any timeout the SDK passes.

CONSEQUENCEExceeding 1h on Hobby kills the task at 1h and loses all in-memory state; if the caller has no progress checkpoint, the entire task rolls back. The same applies to 24h on Pro.