How to Use the JavaScript Sandbox for Calculations in ChocolateLMLite

ChocolateLMLite provides a secure JavaScript sandbox that allows AI models to execute arbitrary calculations using the Jint engine with strict resource limits, returning results directly to the chat.

ChocolateLMLite, an open-source LLM interface maintained by gpsnmeajp, includes a built-in JavaScript sandbox for calculations that enables safe code execution without exposing the host system to security risks. This feature leverages the Jint JavaScript engine to run isolated computations, making it ideal for arithmetic, data manipulation, or any pure logic operations that extend the AI's capabilities beyond text generation.

Enabling the JavaScript Sandbox

The sandbox is controlled by the EnableJavascript flag, which persists per persona and can be toggled through both the web interface and programmatically.

To enable the sandbox via the UI:

1. Navigate to Settings → System in the web interface.
2. Check the box labeled JavaScriptサンドボックスを有効化 (Enable JavaScript Sandbox).
3. Click 保存 (Save) to persist the changes.

This setting is handled in static/js/system.js (lines 172-179) and stored via static/js/setting.js. The flag is saved to the active persona's generalSettings.json and managed by FileManager.cs (lines 109-110), which loads the EnableJavascript boolean when assembling available tools.

How the Sandbox Works

At the core of the JavaScript sandbox is the Eval method in src/Tools.cs (lines 162-193). When invoked, this method creates an isolated Jint.Engine instance configured with strict resource constraints:

• Memory limit: Approximately 4 MiB
• Execution timeout: 15 seconds
• Maximum statements: 10,000
• Recursion depth limit: 64

The engine injects a console.log-like object to capture output streams. The evaluated code runs entirely in-process with no access to network I/O, file system operations, or external process invocation. When execution completes, Eval returns either the computed value, captured console logs, or a JSON object containing both.

Performing Calculations

Automatic Tool Invocations

When enabled, the LLM automatically discovers the Eval tool through GetAvailableTools() in src/Tools.cs (lines 93-98). You can prompt calculations naturally:

Calculate the factorial of 7.

The model may respond with a tool call structured as:

{
  "name": "Eval",
  "arguments": {
    "code": "function fact(n){return n<=1?1:n*fact(n-1);} fact(7);"
  }
}

The framework serializes the request, invokes Tools.Eval, and returns the result (5040) back to the chat thread.

Direct API Calls

You can also invoke the sandbox directly via HTTP POST to the chat API:

POST /api/chat
Content-Type: application/json

{
  "messages": [
    { "role": "user", "content": "What is 2³ + 5?" }
  ],
  "tools": [
    {
      "name": "Eval",
      "arguments": { "code": "Math.pow(2,3) + 5;" }
    }
  ]
}

Response:

{
  "toolResult": {
    "name": "Eval",
    "result": "13"
  }
}

Using JavaScript in Post-Process Scripts

The same Jint engine powers post-processing scripts stored in persona folders. In post_process_script.js, you can execute calculations after the LLM generates a message:

function postProcess(message) {
  // Perform calculation using the sandbox
  const extra = eval("2 + 3 * 4");   // Returns 14
  return message + "\n\n(計算結果: " + extra + ")";
}

FileManager.ApplyPostProcessScript loads and executes these scripts using an identically configured Jint.Engine with the same safety limits applied to chat-based evaluations.

Configuring Programmatically

To enable the sandbox programmatically in C# without using the web UI:

// Assuming 'persona' is a loaded Persona object
persona.GeneralSettings.EnableJavascript = true;
await fileManager.SavePersonaSettingsAsync(persona);

After saving via FileManager, subsequent LLM requests will automatically include the Eval tool in the available functions list defined in src/Tools.cs (lines 75-88).

Security and Limitations

The JavaScript sandbox in ChocolateLMLite implements defense-in-depth to protect the host environment:

• No system access: The sandbox cannot perform network requests, read/write files, or spawn processes.
• Resource isolation: Hard limits on memory (4 MiB), execution time (15 seconds), and statement count (10,000) prevent denial-of-service attacks.
• Pure computation only: The Jint engine executes in a closed environment with only the injected console object exposed.

These constraints ensure that even malicious or infinite-loop code cannot compromise the server or exhaust system resources.

Summary

• Enable the JavaScript sandbox via the Settings → System toggle or by setting EnableJavascript to true in the persona settings.
• The Eval method in src/Tools.cs executes code using a restricted Jint engine with 4 MiB memory limits and 15-second timeouts.
• The LLM automatically invokes the tool for calculations when enabled, or you can call it directly via the API.
• Post-process scripts in persona folders reuse the same sandbox environment for message manipulation.
• Network and file system access are explicitly blocked, ensuring secure execution of arbitrary JavaScript.

Frequently Asked Questions

How do I enable the JavaScript sandbox in ChocolateLMLite?

Navigate to Settings → System in the web UI and check JavaScriptサンドボックスを有効化, then click 保存. Alternatively, set persona.GeneralSettings.EnableJavascript = true programmatically and save via FileManager.SavePersonaSettingsAsync().

What are the resource limits for JavaScript execution?

The sandbox restricts scripts to approximately 4 MiB of memory, 15 seconds of execution time, 10,000 statements, and a recursion depth of 64. These limits are enforced by the Jint engine instantiated in src/Tools.cs.

Can I access the file system or network from the sandbox?

No. The JavaScript sandbox explicitly blocks all network I/O, file system operations, and external process invocation. Only pure computational JavaScript with basic console.log output is permitted.

Can I use the JavaScript sandbox outside of AI chat interactions?

Yes. The same Jint engine configuration is available for persona-specific post-process scripts. Create a post_process_script.js file in the persona folder, and FileManager.ApplyPostProcessScript will execute it using identical security constraints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}