🔒 slopjail

slopjail is a sandbox for running untrusted JavaScript in the browser. It can be used to safely implement a code execution tool for browser-based AI agents, among other use cases.

Status: Alpha ⚡

Features

• Tiny (~3 KB gzipped)
• Simple API: createSandbox() → run() → dispose().
• Expose variables and functions for untrusted code to access.
• Pretty good security:
  • Code runs in a Web Worker on an opaque origin: no access to the host page's storage, cookies, or DOM.
  • Network access is blocked by default using a strict Content-Security-Policy.
  • Disables APIs like navigator to resist device fingerprinting.

Quickstart

Install:

npm install slopjail

Create a sandbox, run some code, and clean up:

import { createSandbox } from "slopjail";

const sandbox = await createSandbox({
  globals: {
    twenty: 20,
    add: (a: number, b: number) => a + b,
  },
});

try {
  await sandbox.run("console.log(await add(twenty, 5))"); // 25
} finally {
  sandbox.dispose();
}

How it works

slopjail creates a hidden <iframe> with an opaque origin and a restrictive CSP. A small relay script inside the iframe spawns a Web Worker and bridges a MessagePort back to the host for RPC. Untrusted code runs in the Worker, completely isolated from the main page. Any functions you provide as globals are replaced with RPC proxies — when the sandbox calls them, they execute in the host context and the result is sent back.

Host (main thread)
 └─ iframe (sandbox="allow-scripts", opaque origin, strict CSP)
     └─ Worker (runs untrusted code)
         └─ RPC proxy functions → call back to host via MessagePort

Advanced

Nested globals

Objects are traversed recursively, so nested functions work the same way:

const sandbox = await createSandbox({
  globals: {
    math: {
      add: (a: number, b: number) => a + b,
      multiply: (a: number, b: number) => a * b,
    },
    version: "1.0.0",
  },
});

try {
  await sandbox.run(`
    const sum = await math.add(2, 3)
    const product = await math.multiply(sum, 4)
    console.log(version, product) // "1.0.0" 20
  `);
} finally {
  sandbox.dispose();
}

Timeouts

run() enforces a 3-second execution timeout by default. If the code doesn't finish in time, the returned promise rejects with an error. You can override it per call:

await sandbox.run(code, { timeout: 10_000 }); // 10 seconds

Content-Security-Policy

By default, the sandbox blocks all network access.

Use the contentSecurityPolicy option to relax specific CSP directives:

const sandbox = await createSandbox({
  contentSecurityPolicy: {
    // Allow access to the GitHub API
    connectSrc: ["https://api.github.com"],
  },
});

await sandbox.run(`
  const res = await fetch('https://api.github.com/zen')
  console.log(await res.text())
`);

You can allow ESM import statements by using scriptSrc:

const sandbox = await createSandbox({
  contentSecurityPolicy: {
    // Allow importing ES modules from esm.sh
    scriptSrc: ["https://esm.sh"],
  },
});

await sandbox.run(`
  import _ from 'https://esm.sh/underscore'
  console.log(_.uniq([1, 2, 1, 4, 1, 3])) // [1, 2, 4, 3]
`);

Naming sandboxes

Give a sandbox a name for easier debugging:

const sandbox = await createSandbox({
  name: `ai-code-tool-${Date.now()}`,
});

Automatic disposal

Sandbox implements Symbol.dispose, so you can use using to automatically clean up when leaving scope:

using sandbox = await createSandbox();
await sandbox.run(code);

Which is equivalent to:

const sandbox = await createSandbox();
try {
  await sandbox.run(code);
} finally {
  sandbox.dispose();
}

FAQ

How do I capture console.log messages?

Simply expose your own console global to capture them:

const sandbox = await createSandbox({
  globals: {
    console: {
      log: (...args: unknown[]) => {
        document.getElementById("output")!.textContent += args.join(" ") + "\n";
      },
    },
  },
});

try {
  await sandbox.run('console.log("hello from the sandbox!")');
} finally {
  sandbox.dispose();
}

How do I read state back out of the sandbox?

You can either expose a global callback for sandboxed code to call, or use evaluate() to return the value of a JS expression:

const sandbox = await createSandbox({
  // Globals are copied into the sandbox, references are not shared
  globals: { fruit: ["apple", "banana"] },
});

try {
  await sandbox.run('fruit.push("cherry")');

  const updatedFruit = await sandbox.evaluate("fruit");
  console.log(updatedFruit); // ['apple', 'banana', 'cherry']
} finally {
  sandbox.dispose();
}

API

createSandbox(opts): Promise<Sandbox>

Create a new sandboxed execution environment.

Creation options:

Option	Type	Description
globals	Record<string, unknown>	Variables and functions to expose inside the sandbox.
contentSecurityPolicy	object	Additional CSP directives appended to the default policy.
name	string	Name for debugging.

Sandbox

Method	Description
run(code: string, options?): Promise<void>	Execute JavaScript inside the sandbox.
evaluate(expr: string, options?): Promise<unknown>	Evaluate a single JavaScript expression inside the sandbox and return its value.
dispose(): void	Terminate the worker and clean up all resources.

Execution options:

Option	Type	Description
timeout	number	Maximum time in milliseconds to wait before rejecting with a timeout error. Defaults to 3000.