README.md
1 # OpenSandbox Code Interpreter Environment 2 3 English | [中文](README_zh.md) 4 5 This directory contains the Docker build files for the Code Interpreter sandbox. The image is based on `Ubuntu 24.04` 6 and comes pre-installed with multiple mainstream programming languages and their multi-version environments, designed to 7 provide an out-of-the-box multi-language code execution environment. 8 9 ## Features 10 11 - **Multi-Language Support**: Pre-installed Python, Java, Node.js, and Go with multiple versions 12 - **Version Switching**: Easy runtime version switching without rebuilding 13 - **Jupyter Integration**: Built-in Jupyter Notebook with multi-language kernels 14 - **Multi-Architecture**: Supports both amd64 and arm64 architectures 15 - **clone3-workaround (amd64)**: The image installs [AkihiroSuda/clone3-workaround](https://github.com/AkihiroSuda/clone3-workaround) v1.0.0 as `/usr/local/bin/clone3-workaround` on **linux/amd64** only (upstream ships no arm64 binary), plus **`libseccomp2`** because the upstream binary is dynamically linked to `libseccomp`. Use it to wrap commands on very old Docker/containerd hosts, e.g. `clone3-workaround apt-get update`. 16 - **Production Ready**: Optimized for containerized execution environments 17 18 ## Supported Languages & Versions 19 20 The image comes pre-installed with the following languages and versions: 21 22 | Language | Supported Versions | Installation Path | Notes | 23 |:------------|:------------------------------|:-----------------------|:-----------------------------------------| 24 | **Python** | 3.10, 3.11, 3.12, 3.13, 3.14* | `/opt/python/versions` | Installed via `uv`; 3.14 is experimental | 25 | **Java** | 8, 11, 17, 21 | `/usr/lib/jvm` | OpenJDK; includes Maven 3.9.2 | 26 | **Node.js** | v18, v20, v22 | `/opt/node` | Official Linux binaries | 27 | **Go** | 1.23, 1.24, 1.25 | `/opt/go` | Official Linux binaries | 28 29 *> Note: Version numbers may be updated to the latest patch versions at build time.* 30 31 ## Quick Start 32 33 ### 1. Build the Image 34 35 Since multi-architecture (amd64/arm64) is supported, it's recommended to use Docker Buildx: 36 37 ```bash 38 # Navigate to the directory 39 cd sandboxes/code-interpreter 40 41 # Build local image 42 docker build -t opensandbox/code-interpreter:latest . 43 44 # For multi-architecture builds (requires Docker Buildx) 45 docker buildx build --platform linux/amd64,linux/arm64 \ 46 -t opensandbox/code-interpreter:latest . 47 ``` 48 49 ### 2. Run the Container 50 51 **With Custom Version Selection:** 52 53 ```bash 54 docker run -it --rm \ 55 -e PYTHON_VERSION=3.11 \ 56 -e JAVA_VERSION=17 \ 57 -e NODE_VERSION=20 \ 58 -e GO_VERSION=1.24 \ 59 opensandbox/code-interpreter:latest 60 ``` 61 62 ### `EXECD_CLONE3_COMPAT` (clone3-workaround) 63 64 If you set `EXECD_CLONE3_COMPAT` to `1`, `true`, `yes`, `on`, or `reexec` (same semantics as [execd](../../components/execd/README.md#linux-clone3-compatibility-inside-sandboxes)), the entrypoint script **re-executes itself** under `/usr/local/bin/clone3-workaround` before Jupyter and kernel setup. That binary is included on **linux/amd64** only; on **arm64** builds the script prints a warning and continues without wrapping. After a successful wrap, the script **unsets** `EXECD_CLONE3_COMPAT` in the running process tree. Use `0`, `false`, `off`, `no`, or leave unset to disable. 65 66 ## Version Switching 67 68 The image includes a built-in version switching script `/opt/opensandbox/code-interpreter-env.sh`. You need to use the 69 `source` command to load it to modify the current shell's environment variables. 70 71 ### Basic Usage 72 73 ```bash 74 source /opt/opensandbox/code-interpreter-env.sh <language> <version> 75 ``` 76 77 ### Examples 78 79 **Switch Python Version:** 80 81 ```bash 82 # Switch to Python 3.11 83 source /opt/opensandbox/code-interpreter-env.sh python 3.11 84 python3 --version 85 # Output: Python 3.11.x 86 ``` 87 88 **Switch Java Version:** 89 90 ```bash 91 # Switch to Java 8 92 source /opt/opensandbox/code-interpreter-env.sh java 8 93 java -version 94 ``` 95 96 **Switch Node.js Version:** 97 98 ```bash 99 # Switch to Node 22 100 source /opt/opensandbox/code-interpreter-env.sh node 22 101 node -v 102 ``` 103 104 **Switch Go Version:** 105 106 ```bash 107 # Switch to Go 1.25 108 source /opt/opensandbox/code-interpreter-env.sh go 1.25 109 go version 110 ``` 111 112 ### List Available Versions 113 114 If you don't specify a version number, the script will list all available versions installed in the current image: 115 116 ```bash 117 # List all Python versions 118 source /opt/opensandbox/code-interpreter-env.sh python 119 120 # List all Java versions 121 source /opt/opensandbox/code-interpreter-env.sh java 122 123 # List all Node.js versions 124 source /opt/opensandbox/code-interpreter-env.sh node 125 126 # List all Go versions 127 source /opt/opensandbox/code-interpreter-env.sh go 128 ``` 129 130 ## Default Versions 131 132 The default version configuration when the container starts: 133 134 - **Python**: 3.14 135 - **Java**: 21 136 - **Node.js**: 22 137 - **Go**: 1.25 138 139 To permanently modify the default version at the Dockerfile level, adjust the `ENV PATH` settings at the bottom of the 140 Dockerfile. 141 142 ## Jupyter Notebook Integration 143 144 ### Available Kernels 145 146 The image comes with pre-configured Jupyter kernels for all supported languages: 147 148 - **Python**: ipykernel for all Python versions 149 - **Java**: IJava kernel 150 - **TypeScript/JavaScript**: tslab kernel 151 - **Go**: gonb kernel 152 - **Bash**: bash_kernel 153 154 ### Starting Jupyter 155 156 ```bash 157 /opt/opensandbox/code-interpreter.sh 158 ``` 159 160 ### Environment Variables 161 162 - `JUPYTER_HOST`: Jupyter server host (default: `http://127.0.0.1:44771`) 163 - `JUPYTER_PORT`: Jupyter server port (default: `44771`) 164 - `JUPYTER_TOKEN`: Access token (default: `opensandboxcodeinterpreterjupyter`) 165 166 ## Advanced Usage 167 168 ### Persistent Workspace 169 170 Mount a local directory to persist your work: 171 172 ```bash 173 docker run -it --rm \ 174 -v $(pwd)/workspace:/workspace \ 175 opensandbox/code-interpreter:latest 176 ``` 177 178 ### Custom Configuration 179 180 Override Jupyter configuration: 181 182 ```bash 183 docker run -it --rm \ 184 -v $(pwd)/jupyter_config.py:/root/.jupyter/jupyter_notebook_config.py \ 185 opensandbox/code-interpreter:latest 186 ``` 187 188 ### Install Additional Packages 189 190 **Python:** 191 192 ```bash 193 python3 -m pip install pandas numpy --break-system-packages 194 ``` 195 196 **Node.js:** 197 198 ```bash 199 npm install -g typescript 200 ``` 201 202 **Go:** 203 204 ```bash 205 go install github.com/user/package@latest 206 ``` 207 208 **Java:** 209 210 ```bash 211 mvn install dependency:copy-dependencies 212 ``` 213 214 ## Architecture 215 216 ``` 217 code-interpreter/ 218 ├── Dockerfile # Main build file 219 ├── Dockerfile_base # Base build file 220 ├── README.md # This file 221 ├── README_zh.md # Chinese README 222 └── scripts/ 223 ├── code-interpreter-env.sh # Version switching script 224 ├── code-interpreter.sh # Jupyter startup script 225 └── jupyter_notebook_config.py # Jupyter configuration 226 ``` 227 228 ## Troubleshooting 229 230 If a specific version is not found, list available versions: 231 232 ```bash 233 source /opt/opensandbox/code-interpreter-env.sh <language> 234 ``` 235 236 ## License 237 238 This project is part of the OpenSandbox suite. See the main [LICENSE](../../LICENSE) file for details. 239 240 ## Support 241 242 For issues and questions: 243 244 - GitHub Issues: [OpenSandbox Issues](https://github.com/alibaba/OpenSandbox/issues) 245 246 ## Related Projects 247 248 - [OpenSandbox](../../) - Main project 249 - [Server](../../server/) - Server implementation 250 - [Execd](../../components/execd/) - Runtime execution engine