--- title: Code Interpreter Kotlin SDK description: Kotlin SDK for executing code in secure, isolated OpenSandbox environments with multi-language support. --- # OpenSandbox Code Interpreter SDK for Kotlin A powerful Kotlin SDK for executing code in secure, isolated sandboxes. This SDK provides a high-level API for running Python, Java, Go, TypeScript, and other languages safely, with support for code execution contexts. ## Prerequisites This SDK requires a specific 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. ## Installation ### Gradle (Kotlin DSL) ```kotlin dependencies { implementation("com.alibaba.opensandbox:code-interpreter:{latest_version}") } ``` ### Maven ```xml com.alibaba.opensandbox code-interpreter {latest_version} ``` ## Quick Start The following example demonstrates how to initialize the client with a specific Python version and execute a simple script. ```java import com.alibaba.opensandbox.codeinterpreter.CodeInterpreter; import com.alibaba.opensandbox.codeinterpreter.domain.models.execd.executions.CodeContext; import com.alibaba.opensandbox.sandbox.domain.models.execd.executions.Execution; import com.alibaba.opensandbox.codeinterpreter.domain.models.execd.executions.RunCodeRequest; import com.alibaba.opensandbox.codeinterpreter.domain.models.execd.executions.SupportedLanguage; import com.alibaba.opensandbox.sandbox.Sandbox; import com.alibaba.opensandbox.sandbox.config.ConnectionConfig; import com.alibaba.opensandbox.sandbox.domain.exceptions.SandboxException; public class QuickStart { public static void main(String[] args) { // 1. Configure connection ConnectionConfig config = ConnectionConfig.builder() .domain("api.opensandbox.io") .apiKey("your-api-key") .build(); // 2. Create a Sandbox with specific runtime configuration // Note: You must use the code-interpreter image // Use try-with-resources to ensure sandbox is closed try (Sandbox sandbox = Sandbox.builder() .connectionConfig(config) .image("opensandbox/code-interpreter:v1.1.0") .entrypoint("/opt/code-interpreter/code-interpreter.sh") .env("PYTHON_VERSION", "3.11") // Select specific language version .build()) { // 3. Create CodeInterpreter wrapper CodeInterpreter interpreter = CodeInterpreter.builder() .fromSandbox(sandbox) .build(); // 4. Create an execution context (Python) CodeContext context = interpreter.codes().createContext(SupportedLanguage.PYTHON); // 5. Run code Execution result = interpreter.codes().run( RunCodeRequest.builder() .code("import sys; print(f'Running on Python {sys.version}')") .context(context) .build() ); // 6. Print output if (!result.getLogs().getStdout().isEmpty()) { System.out.println(result.getLogs().getStdout().get(0).getText()); } // 7. Cleanup // Note: kill() terminates the remote instance; close() (auto-called) cleans up local resources sandbox.kill(); } catch (SandboxException e) { // Handle Sandbox specific exceptions System.err.println("Sandbox Error: [" + e.getError().getCode() + "] " + e.getError().getMessage()); } catch (Exception e) { e.printStackTrace(); } } } ``` ## Runtime Configuration ### Docker Image The Code Interpreter SDK relies on a specialized environment. Ensure your sandbox provider has the `opensandbox/code-interpreter` image available. For detailed information about supported languages and versions, please refer to the [Environment Documentation](https://github.com/opensandbox-group/OpenSandbox/tree/main/sandboxes/code-interpreter). ### Troubleshooting: `pip: command not found` If you are using the Kotlin/Java client and run shell commands such as `pip install pandas`, make sure the sandbox is created from the `opensandbox/code-interpreter` image (or a derivative) and uses the Code Interpreter entrypoint: ```java Sandbox sandbox = Sandbox.builder() .image("opensandbox/code-interpreter:v1.1.0") .entrypoint("/opt/code-interpreter/code-interpreter.sh") .env("PYTHON_VERSION", "3.11") .build(); ``` The plain Sandbox SDK can also talk to generic sandbox images, but those images are not guaranteed to include Python or `pip`. In that case, commands such as `pip install ...` will fail with `pip: command not found`. Use the package manager that matches the image you launched, or switch to the Code Interpreter image when you need Python package installation/runtime behavior. ### Language Version Selection You can specify the desired version of a programming language by setting the corresponding environment variable when building the `Sandbox`. | Language | Environment Variable | Example Value | Default (if unset) | | -------- | -------------------- | ------------- | ------------------ | | Python | `PYTHON_VERSION` | `3.11` | Image default | | Java | `JAVA_VERSION` | `17` | Image default | | Node.js | `NODE_VERSION` | `20` | Image default | | Go | `GO_VERSION` | `1.24` | Image default | ```java Sandbox sandbox = Sandbox.builder() .image("opensandbox/code-interpreter:v1.1.0") .entrypoint("/opt/code-interpreter/code-interpreter.sh") .env("JAVA_VERSION", "17") .env("GO_VERSION", "1.23") .build(); ``` ## Usage Examples ### 0. Run with `language` (default language context) If you don't need to manage explicit session IDs, you can run code by specifying only `language`. When `context.id` is omitted, **execd will create/reuse a default session for that language**, so state can persist across runs: ```java import com.alibaba.opensandbox.codeinterpreter.domain.models.execd.executions.SupportedLanguage; // Default Python context: state persists across runs interpreter.codes().run("x = 42", SupportedLanguage.PYTHON); Execution execution = interpreter.codes().run("result = x\nresult", SupportedLanguage.PYTHON); System.out.println(execution.getResult().get(0).getText()); // 42 ``` ### 1. Java Code Execution Execute Java code snippets dynamically. ```java CodeContext javaContext = interpreter.codes().createContext(SupportedLanguage.JAVA); RunCodeRequest request = RunCodeRequest.builder() .code( "System.out.println(\"Calculating sum...\");\n" + "int a = 10;\n" + "int b = 20;\n" + "int sum = a + b;\n" + "System.out.println(\"Sum: \" + sum);\n" + "sum" // Return value ) .context(javaContext) .build(); Execution execution = interpreter.codes().run(request); // Handle results System.out.println("Execution ID: " + execution.getId()); execution.getLogs().getStdout().forEach(log -> System.out.println(log.getText())); ``` ### 2. Python with State Persistence Variables defined in one execution are available in subsequent executions within the same context. ```java CodeContext pythonContext = interpreter.codes().createContext(SupportedLanguage.PYTHON); // Step 1: Define variables RunCodeRequest step1 = RunCodeRequest.builder() .code( "users = ['Alice', 'Bob', 'Charlie']\n" + "print(f'Initialized {len(users)} users')" ) .context(pythonContext) .build(); interpreter.codes().run(step1); // Step 2: Use variables from previous step RunCodeRequest step2 = RunCodeRequest.builder() .code( "users.append('Dave')\n" + "print(f'Updated users: {users}')" ) .context(pythonContext) .build(); Execution result = interpreter.codes().run(step2); // Output: Updated users: ['Alice', 'Bob', 'Charlie', 'Dave'] ``` ### 3. Streaming Output Handling Handle standard output, error output, and execution events in real-time. ```java ExecutionHandlers handlers = ExecutionHandlers.builder() .onStdout(msg -> System.out.println("STDOUT: " + msg.getText())) .onStderr(msg -> System.err.println("STDERR: " + msg.getText())) .onResult(res -> System.out.println("Result: " + res.getText())) .onError(err -> System.err.println("Error: " + err.getValue())) .onExecutionComplete(complete -> System.out.println("Finished in " + complete.getExecutionTimeInMillis() + "ms") ) .build(); RunCodeRequest request = RunCodeRequest.builder() .code("import time\nfor i in range(5):\n print(i)\n time.sleep(0.5)") .context(pythonContext) .handlers(handlers) .build(); interpreter.codes().run(request); ``` ### 4. Multi-Language Context Isolation Different languages run in isolated environments. ```java CodeContext pyCtx = interpreter.codes().createContext(SupportedLanguage.PYTHON); CodeContext goCtx = interpreter.codes().createContext(SupportedLanguage.GO); // Python Context interpreter.codes().run( RunCodeRequest.builder() .code("print('Running in Python')") .context(pyCtx) .build() ); // Go Context interpreter.codes().run( RunCodeRequest.builder() .code( "package main\n" + "func main() { println(\"Running in Go\") }" ) .context(goCtx) .build() ); ```