javascript-sandbox

name	javascript-sandbox
description	Best practices for using the stagewise built-in JavaScript sandbox. Explains how to access APIs for browser debugging/interaction, use external dependencies, file system access, running mini-apps, etc.

JavaScript Sandbox

The sandbox is an isolated, persistent Node.js VM context. Data and functions stored on globalThis survive across calls and messages. Scripts run inside an async IIFE. The sandbox offers a standard stagewise runtime API through the global object API.

---

Timeouts

• Inactivity timeout: 45 seconds. Each call to API.output() or API.createAttachment() resets the timer.
• Hard cap: 3 minutes wall-clock (non-resettable).
• NEVER use await Promise.resolve() or unbounded while(true) loops — these permanently block the sandbox worker.
• In loops, yield with await new Promise(r => setTimeout(r, 0)) every ~1000 sync iterations.
• Always use bounded loops. Return partial results if hitting the limit.
• For long-running tasks, call API.output() periodically as a heartbeat. Split work across multiple invocations if needed.

---

Creating Outputs

Use API.output(data: any): void to generate outputs. Can be called multiple times; outputs are concatenated. NEVER use console.log() or other console methods.

---

Creating Attachments

Use API.createAttachment(originalFileName: string, data: Buffer | string): Promise<string>.

• originalFileName: user-visible name with extension (e.g. screenshot.png)
• data: binary content or base64-encoded string
• Returns the obfuscated file name in att/ — always use this returned name when referencing the attachment afterwards.

---

Chrome DevTools Protocol (CDP)

Send commands via API.sendCDP(tabId, method, params?): Promise<any>. Listen to events via API.onCDPEvent(tabId, event, callback): void (listeners persist across IIFEs; use globalThis to accumulate).

• Pre-enabled (do NOT call .enable): DOM, CSS, Page, Runtime, Log, Console
• No enable method (use directly): Input, Emulation, IO, Target, Browser, SystemInfo, Schema
• All others (e.g. Network, Overlay, Debugger, Fetch): call <Domain>.enable first.

---

Filesystem Access

Sandboxed fs and fsPromises globals are available directly (also via require('fs')). Scoped to mounted workspaces.

• Paths use mount prefixes: w1/src/index.ts, w2/package.json. Optional if one workspace mounted.
• All mounts (w1/, att/, apps/, plugins/) share the same API — cross-mount copy/move works.
• All standard fs methods available (callback, sync, and promise APIs).
• att/ — read-only access to attachments. Create with API.createAttachment().
• plugins/ — read-only access to plugin files.
• Sandbox fs is well-suited for binary operations and cross-mount copies.

---

Credentials

Use API.getCredential(typeId): Promise<string> to retrieve stored credentials. Secret fields contain opaque placeholders auto-substituted in outgoing fetch calls. Plain fields contain real values.

---

Mini Apps

Mini apps are interactive web UIs rendered in dedicated browser tabs. Use API.openApp(appId, opts?) to open one. See the mini-apps skill for full details on building, messaging, and best practices.

---

Available Runtime

Global APIs: Promise, Map, Set, Array, Object, JSON, Math, RegExp, Date, Error, typed arrays, setTimeout, setInterval, setImmediate, fetch, Headers, Request, Response, AbortController, URL, TextEncoder, TextDecoder, atob, btoa, Buffer, Blob, FormData, structuredClone, queueMicrotask, crypto.randomUUID(), process (shim: env.NODE_ENV, nextTick). NO DOM or Navigator APIs — use CDP for tab interaction.

Node.js built-ins (via require()): buffer, crypto, events, path, querystring, stream, string_decoder, url, util, zlib, assert. Blocked: net, http, https, child_process, worker_threads, vm.

Dynamic imports (via importModule(url)): HTTPS only, prefer https://esm.sh/{package}?target=node. Modules cached per session. Do NOT use await import().

---

Important Rules

• Check docs of imported modules BEFORE using them.
• Handle both default and named exports when format is unknown.
• Use API.output() instead of console logging.
• Use fetch for all network requests.
• Implement error handling with fallbacks and sensible retries.
• Split multi-step scripts into separate invocations.
• After writing or updating mini app files, use API.openApp to reload the app and API.sendMessage / API.onMessage for messaging.

References

For detailed usage examples, see:

• references/examples.md — Common sandbox patterns (filesystem, CDP, attachments, data processing, long-running tasks)