|
| 1 | +# Alibaba Code Interpreter SDK for JavaScript/TypeScript |
| 2 | + |
| 3 | +English | [中文](README_zh.md) |
| 4 | + |
| 5 | +A TypeScript/JavaScript SDK for executing code in secure, isolated sandboxes. It provides a high-level API for running Python, Java, Go, TypeScript, and other languages safely, with support for code execution contexts. |
| 6 | + |
| 7 | +## Prerequisites |
| 8 | + |
| 9 | +This SDK requires a Docker image containing the Code Interpreter runtime environment. You must use the `opensandbox/code-interpreter` image (or a derivative) which includes pre-installed runtimes for Python, Java, Go, Node.js, etc. |
| 10 | + |
| 11 | +For detailed information about supported languages and versions, please refer to the [Environment Documentation](../../../sandboxes/code-interpreter/README.md). |
| 12 | + |
| 13 | +## Installation |
| 14 | + |
| 15 | +### npm |
| 16 | + |
| 17 | +```bash |
| 18 | +npm install @alibaba/opensandbox-code-interpreter |
| 19 | +``` |
| 20 | + |
| 21 | +### pnpm |
| 22 | + |
| 23 | +```bash |
| 24 | +pnpm add @alibaba/opensandbox-code-interpreter |
| 25 | +``` |
| 26 | + |
| 27 | +### yarn |
| 28 | + |
| 29 | +```bash |
| 30 | +yarn add @alibaba/opensandbox-code-interpreter |
| 31 | +``` |
| 32 | + |
| 33 | +## Quick Start |
| 34 | + |
| 35 | +The following example demonstrates how to create a sandbox with a specific runtime configuration and execute a simple script. |
| 36 | + |
| 37 | +> **Note**: Before running this example, ensure the OpenSandbox service is running. See the root [README.md](../../../README.md) for startup instructions. |
| 38 | +
|
| 39 | +```ts |
| 40 | +import { ConnectionConfig, Sandbox } from "@alibaba/opensandbox"; |
| 41 | +import { CodeInterpreter, SupportedLanguages } from "@alibaba/opensandbox-code-interpreter"; |
| 42 | + |
| 43 | +// 1. Configure connection |
| 44 | +const config = new ConnectionConfig({ |
| 45 | + domain: "api.opensandbox.io", |
| 46 | + apiKey: "your-api-key", |
| 47 | +}); |
| 48 | + |
| 49 | +// 2. Create a Sandbox with the code-interpreter image + runtime versions |
| 50 | +const sandbox = await Sandbox.create({ |
| 51 | + connectionConfig: config, |
| 52 | + image: "opensandbox/code-interpreter:latest", |
| 53 | + entrypoint: ["/opt/opensandbox/code-interpreter.sh"], |
| 54 | + env: { |
| 55 | + PYTHON_VERSION: "3.11", |
| 56 | + JAVA_VERSION: "17", |
| 57 | + NODE_VERSION: "20", |
| 58 | + GO_VERSION: "1.24", |
| 59 | + }, |
| 60 | + timeoutSeconds: 15 * 60, |
| 61 | +}); |
| 62 | + |
| 63 | +// 3. Create CodeInterpreter wrapper |
| 64 | +const ci = await CodeInterpreter.create(sandbox); |
| 65 | + |
| 66 | +// 4. Create an execution context (Python) |
| 67 | +const ctx = await ci.codes.createContext(SupportedLanguages.PYTHON); |
| 68 | + |
| 69 | +// 5. Run code |
| 70 | +const result = await ci.codes.run("import sys\nprint(sys.version)\nresult = 2 + 2\nresult", { |
| 71 | + context: ctx, |
| 72 | +}); |
| 73 | + |
| 74 | +// 6. Print output |
| 75 | +console.log(result.result[0]?.text); |
| 76 | + |
| 77 | +// 7. Cleanup remote instance (optional but recommended) |
| 78 | +await sandbox.kill(); |
| 79 | +``` |
| 80 | + |
| 81 | +## Runtime Configuration |
| 82 | + |
| 83 | +### Docker Image |
| 84 | + |
| 85 | +The Code Interpreter SDK relies on a specialized environment. Ensure your sandbox provider has the `opensandbox/code-interpreter` image available. |
| 86 | + |
| 87 | +### Language Version Selection |
| 88 | + |
| 89 | +You can specify the desired version of a programming language by setting the corresponding environment variable when creating the `Sandbox`. |
| 90 | + |
| 91 | +| Language | Environment Variable | Example Value | Default (if unset) | |
| 92 | +| --- | --- | --- | --- | |
| 93 | +| Python | `PYTHON_VERSION` | `3.11` | Image default | |
| 94 | +| Java | `JAVA_VERSION` | `17` | Image default | |
| 95 | +| Node.js | `NODE_VERSION` | `20` | Image default | |
| 96 | +| Go | `GO_VERSION` | `1.24` | Image default | |
| 97 | + |
| 98 | +```ts |
| 99 | +const sandbox = await Sandbox.create({ |
| 100 | + connectionConfig: config, |
| 101 | + image: "opensandbox/code-interpreter:latest", |
| 102 | + entrypoint: ["/opt/opensandbox/code-interpreter.sh"], |
| 103 | + env: { |
| 104 | + JAVA_VERSION: "17", |
| 105 | + GO_VERSION: "1.24", |
| 106 | + }, |
| 107 | +}); |
| 108 | +``` |
| 109 | + |
| 110 | +## Usage Examples |
| 111 | + |
| 112 | +### 0. Run with `language` (default language context) |
| 113 | + |
| 114 | +If you don't need to manage explicit context IDs, you can run code by specifying only `language`. |
| 115 | +When `context.id` is omitted, execd can create/reuse a default session for that language, so state can persist across runs. |
| 116 | + |
| 117 | +```ts |
| 118 | +import { SupportedLanguages } from "@alibaba/opensandbox-code-interpreter"; |
| 119 | + |
| 120 | +await ci.codes.run("x = 42", { language: SupportedLanguages.PYTHON }); |
| 121 | +const execution = await ci.codes.run("result = x\nresult", { language: SupportedLanguages.PYTHON }); |
| 122 | +console.log(execution.result[0]?.text); // "42" |
| 123 | +``` |
| 124 | + |
| 125 | +### 1. Java Code Execution |
| 126 | + |
| 127 | +```ts |
| 128 | +import { SupportedLanguages } from "@alibaba/opensandbox-code-interpreter"; |
| 129 | + |
| 130 | +const javaCtx = await ci.codes.createContext(SupportedLanguages.JAVA); |
| 131 | +const execution = await ci.codes.run( |
| 132 | + [ |
| 133 | + 'System.out.println("Calculating sum...");', |
| 134 | + "int a = 10;", |
| 135 | + "int b = 20;", |
| 136 | + "int sum = a + b;", |
| 137 | + 'System.out.println("Sum: " + sum);', |
| 138 | + "sum", |
| 139 | + ].join("\n"), |
| 140 | + { context: javaCtx }, |
| 141 | +); |
| 142 | +console.log(execution.logs.stdout.map((m) => m.text)); |
| 143 | +``` |
| 144 | + |
| 145 | +### 2. Streaming Output Handling |
| 146 | + |
| 147 | +Handle stdout/stderr and execution events in real-time. |
| 148 | + |
| 149 | +```ts |
| 150 | +import type { ExecutionHandlers } from "@alibaba/opensandbox"; |
| 151 | +import { SupportedLanguages } from "@alibaba/opensandbox-code-interpreter"; |
| 152 | + |
| 153 | +const handlers: ExecutionHandlers = { |
| 154 | + onStdout: (m) => console.log("STDOUT:", m.text), |
| 155 | + onStderr: (m) => console.error("STDERR:", m.text), |
| 156 | + onResult: (r) => console.log("RESULT:", r.text), |
| 157 | +}; |
| 158 | + |
| 159 | +const pyCtx = await ci.codes.createContext(SupportedLanguages.PYTHON); |
| 160 | +await ci.codes.run("import time\nfor i in range(5):\n print(i)\n time.sleep(0.2)", { |
| 161 | + context: pyCtx, |
| 162 | + handlers, |
| 163 | +}); |
| 164 | +``` |
| 165 | + |
| 166 | +## Notes |
| 167 | + |
| 168 | +- **Lifecycle**: `CodeInterpreter` wraps an existing `Sandbox` instance and reuses its connection configuration. |
| 169 | +- **Default context**: `codes.run(..., { language })` uses a language default context (state can persist across runs). |
| 170 | + |
0 commit comments