Skip to content

Feature/javascript sdk #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ninan-nn wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Feature/javascript sdk #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
f6dbe6c
feat(k8s): update add task_strategy abstraction to custom strategy impl
Spground Jan 12, 2026
c3d01b0
Merge pull request #86 from Spground/feature/public-refactor-abstract…
fengcone Jan 13, 2026
3641b90
chore(components/execd): add set -x before exec "$@" for debug trace …
Pangjiping Jan 14, 2026
3d3f0a6
Merge pull request #90 from Pangjiping/hotfix/execd-envs
hittyt Jan 14, 2026
e7cf429
feat(server): support create sandbox from pool
Generalwin Jan 15, 2026
5348660
Merge pull request #81 from Generalwin/k8s-pool
Pangjiping Jan 15, 2026
f3945da
feat(sdks): javascript sdk
ninan-nn Jan 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 72 additions & 0 deletions .github/workflows/publish-js-sdks.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
name: Publish JavaScript SDKs

on:
push:
tags:
- "js/sandbox/v*"
- "js/code-interpreter/v*"

permissions:
contents: read

jobs:
publish:
name: Publish (${{ matrix.sdk.name }})
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
sdk:
- name: sandbox
tagPrefix: sandbox
workingDirectory: sdks/sandbox/javascript
packageName: "@alibaba-group/opensandbox"
- name: code-interpreter
tagPrefix: code-interpreter
workingDirectory: sdks/code-interpreter/javascript
packageName: "@alibaba-group/opensandbox-code-interpreter"

steps:
- name: Checkout code
uses: actions/checkout@v4

- name: Set up Node
uses: actions/setup-node@v4
with:
node-version: "20"
registry-url: "https://registry.npmjs.org"

- name: Set up pnpm
uses: pnpm/action-setup@v4
with:
version: latest

- name: Enable corepack
run: corepack enable

- name: Get pnpm store path
id: pnpm-store
run: echo "STORE_PATH=$(corepack pnpm store path)" >> "$GITHUB_OUTPUT"

- name: Cache pnpm store
uses: actions/cache@v4
with:
path: ${{ steps.pnpm-store.outputs.STORE_PATH }}
key: ${{ runner.os }}-pnpm-${{ hashFiles('sdks/pnpm-lock.yaml') }}
restore-keys: ${{ runner.os }}-pnpm-

- name: Install workspace dependencies
working-directory: sdks
run: corepack pnpm install --frozen-lockfile

- name: Build SDK
working-directory: sdks
run: corepack pnpm --filter ${{ matrix.sdk.packageName }}... --sort run build

- name: Publish to npm
if: startsWith(github.ref, format('refs/tags/js/{0}/v', matrix.sdk.tagPrefix))
working-directory: ${{ matrix.sdk.workingDirectory }}
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
run: |
corepack pnpm publish --access public --no-git-checks
54 changes: 54 additions & 0 deletions .github/workflows/real-e2e.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,3 +114,57 @@ jobs:
name: java-test-report
path: tests/java/build/reports/tests/test/
retention-days: 5

javascript-e2e:
name: JavaScript E2E (docker bridge)
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4

- name: Set up Node
uses: actions/setup-node@v4
with:
node-version: "20"

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.10"

- name: Install uv
run: pip install uv

- name: Run tests
env:
TAG: latest
run: |
set -e

# Create config file (match other E2E jobs)
cat <<EOF > ~/.sandbox.toml
[server]
host = "127.0.0.1"
port = 8080
log_level = "INFO"
api_key = ""
[runtime]
type = "docker"
execd_image = "opensandbox/execd:${TAG}"
[docker]
network_mode = "bridge"
EOF

bash ./scripts/javascript-e2e.sh

- name: Eval logs
if: ${{ always() }}
run: cat server/server.log

- name: Upload Test Report
if: always()
uses: actions/upload-artifact@v4
with:
name: javascript-test-report
path: tests/javascript/build/test-results/junit.xml
retention-days: 5
9 changes: 4 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ OpenSandbox is a **universal sandbox platform** for AI application scenarios, pr

## Features

- **Multi-language SDKs**: Provides sandbox SDKs in Python, Java, TypeScript (Roadmap),Go(Roadmap) and other languages.
- **Multi-language SDKs**: Provides sandbox SDKs in Python, Java/Kotlin, JavaScript/TypeScript, Go (Roadmap), and more.
- **Sandbox Protocol**: Defines sandbox lifecycle management API and sandbox execution API. You can extend your own sandbox runtime through these sandbox protocols.
- **Sandbox Runtime**: Implements sandbox lifecycle management by default, supports Docker and Kubernetes runtimes, enabling large-scale distributed sandbox scheduling.
- **Sandbox Environments**: Built-in implementations for Command, Filesystem, Code Interpreter. And provides examples for Coding Agents (Claude Code, etc.), Browser automation (Chrome, Playwright), and Desktop environments (VNC, VS Code).
Expand Down Expand Up @@ -176,7 +176,7 @@ For more details, please refer to [examples](examples/README.md) and the README
| [`components/execd/`](components/execd/README.md) | Sandbox execution daemon (commands and file operations) |
| [`components/ingress/`](components/ingress/README.md) | Sandbox traffic ingress proxy |
| [`components/egress/`](components/egress/README.md) | Sandbox network egress control |
| [`sdks/`](sdks/) | Multi-language SDKs (Python, Java/Kotlin) |
| [`sdks/`](sdks/) | Multi-language SDKs (Python, Java/Kotlin, JavaScript/TypeScript) |
| [`sandboxes/`](sandboxes/) | Sandbox runtime images (e.g., code-interpreter) |
| [`kubernetes/`](kubernetes/README.md) | Kubernetes operator and batch sandbox support |
| [`specs/`](specs/README.md) | OpenAPI specifications |
Expand All @@ -192,8 +192,8 @@ For detailed architecture, see [docs/architecture.md](docs/architecture.md).

- [docs/architecture.md](docs/architecture.md) – Overall architecture & design philosophy
- SDK
- Sandbox base SDK ([Java\Kotlin SDK](sdks/sandbox/kotlin/README.md), [Python SDK](sdks/sandbox/python/README.md)) - includes sandbox lifecycle, command execution, file operations
- Code Interpreter SDK ([Java\Kotlin SDK](sdks/code-interpreter/kotlin/README.md), [Python SDK](sdks/code-interpreter/python/README.md)) - code interpreter
- Sandbox base SDK ([Java\Kotlin SDK](sdks/sandbox/kotlin/README.md), [Python SDK](sdks/sandbox/python/README.md), [JavaScript/TypeScript SDK](sdks/sandbox/javascript/README.md)) - includes sandbox lifecycle, command execution, file operations
- Code Interpreter SDK ([Java\Kotlin SDK](sdks/code-interpreter/kotlin/README.md), [Python SDK](sdks/code-interpreter/python/README.md), [JavaScript/TypeScript SDK](sdks/code-interpreter/javascript/README.md)) - code interpreter
- [specs/README.md](specs/README.md) - Contains OpenAPI definitions for sandbox lifecycle API and sandbox execution API
- [server/README.md](server/README.md) - Contains sandbox server startup and configuration, currently supports Docker Runtime, will support Kubernetes Runtime in the future

Expand All @@ -207,7 +207,6 @@ You can use OpenSandbox for personal or commercial projects in compliance with t

### SDK

- [ ] **TypeScript SDK** - TypeScript/JavaScript client SDK for sandbox lifecycle management and command execution, file operations.
- [ ] **Go SDK** - Go client SDK for sandbox lifecycle management and command execution, file operations.

### Server Runtime
Expand Down
1 change: 1 addition & 0 deletions components/execd/bootstrap.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,5 @@ export EXECD_ENVS
echo "starting OpenSandbox execd daemon at $EXECD"
$EXECD &

set -x
exec "$@"
9 changes: 4 additions & 5 deletions docs/README_zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ OpenSandbox 是一个面向 AI 应用场景设计的「通用沙箱平台」，

## 核心特性

- **多语言 SDK**：提供 Python、Java、TypeScript (Roadmap)、Go (Roadmap) 等语言的客户端 SDK。
- **多语言 SDK**：提供 Python、Java/Kotlin、JavaScript/TypeScript 等语言的客户端 SDK，Go SDK 仍在规划中。
- **沙箱协议**：定义了沙箱生命周期管理 API 和沙箱执行 API。你可以通过这些沙箱协议扩展自己的沙箱运行时。
- **沙箱运行时**：默认实现沙箱生命周期管理，支持 Docker 和 Kubernetes 运行时，实现大规模分布式沙箱调度。
- **沙箱环境**：内置 Command、Filesystem、Code Interpreter 实现。并提供 Coding Agent（Claude Code 等）、浏览器自动化（Chrome、Playwright）和桌面环境（VNC、VS Code）等示例。
Expand Down Expand Up @@ -175,7 +175,7 @@ OpenSandbox 提供了丰富的示例来演示不同场景下的沙箱使用方
| [`components/execd/`](../components/execd/README_zh.md) | 沙箱执行守护进程，负责命令和文件操作 |
| [`components/ingress/`](../components/ingress/README.md) | 沙箱流量入口代理 |
| [`components/egress/`](../components/egress/README.md) | 沙箱网络 Egress 访问控制 |
| [`sdks/`](../sdks/) | 多语言 SDK（Python、Java/Kotlin） |
| [`sdks/`](../sdks/) | 多语言 SDK（Python、Java/Kotlin、JavaScript/TypeScript） |
| [`sandboxes/`](../sandboxes/) | 沙箱运行时镜像（如 code-interpreter） |
| [`kubernetes/`](../kubernetes/README-ZH.md) | Kubernetes Operator 和批量沙箱支持 |
| [`specs/`](../specs/README_zh.md) | OpenAPI 规范 |
Expand All @@ -191,8 +191,8 @@ OpenSandbox 提供了丰富的示例来演示不同场景下的沙箱使用方

- [docs/architecture.md](architecture.md) – 整体架构 & 设计理念
- SDK
- Sandbox 基础 SDK（[Java\Kotlin SDK](../sdks/sandbox/kotlin/README_zh.md)、[Python SDK](../sdks/sandbox/python/README_zh.md)）-包含沙箱生命周期、命令执行、文件操作
- Code Interpreter SDK（[Java\Kotlin SDK](../sdks/code-interpreter/kotlin/README_zh.md) 、[Python SDK](../sdks/code-interpreter/python/README_zh.md)）- 代码解释器
- Sandbox 基础 SDK（[Java\Kotlin SDK](../sdks/sandbox/kotlin/README_zh.md)、[Python SDK](../sdks/sandbox/python/README_zh.md)、[JavaScript/TypeScript SDK](../sdks/sandbox/javascript/README_zh.md)）- 包含沙箱生命周期、命令执行、文件操作
- Code Interpreter SDK（[Java\Kotlin SDK](../sdks/code-interpreter/kotlin/README_zh.md) 、[Python SDK](../sdks/code-interpreter/python/README_zh.md)、[JavaScript/TypeScript SDK](../sdks/code-interpreter/javascript/README_zh.md)）- 代码解释器
- [specs/README.md](../specs/README_zh.md) - 包含沙箱生命周期 API 和沙箱执行 API 的 OpenAPI 定义
- [server/README.md](../server/README_zh.md) - 包含沙箱 Server 的启动和配置，目前支持 Docker Runtime，后续将支持 Kubernetes Runtime

Expand All @@ -206,7 +206,6 @@ OpenSandbox 提供了丰富的示例来演示不同场景下的沙箱使用方

### SDK

- [ ] **TypeScript SDK** - TypeScript/JavaScript 客户端 SDK，用于沙箱生命周期管理、命令执行和文件操作
- [ ] **Go SDK** - Go 客户端 SDK，用于沙箱生命周期管理、命令执行和文件操作

### Server Runtime
Expand Down
135 changes: 135 additions & 0 deletions examples/code-interpreter/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,141 @@ The script creates a Sandbox + CodeInterpreter, runs a Python code snippet and p
3 + 4 = 7


=== TypeScript example ===
[TypeScript stdout] Hello from TypeScript!

[TypeScript stdout] sum = 6
```

# Code Interpreter Sandbox from pool

## Start OpenSandbox server [k8s]

Install the k8s OpenSandbox operator, and create a pool:
```yaml
apiVersion: sandbox.opensandbox.io/v1alpha1
kind: Pool
metadata:
labels:
app.kubernetes.io/name: sandbox-k8s
app.kubernetes.io/managed-by: kustomize
name: pool-sample
namespace: opensandbox
spec:
template:
metadata:
labels:
app: example
spec:
volumes:
- name: sandbox-storage
emptyDir: { }
- name: opensandbox-bin
emptyDir: { }
initContainers:
- name: task-executor-installer
image: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/task-executor:latest
command: [ "/bin/sh", "-c" ]
args:
- |
cp /workspace/server /opt/opensandbox/bin/task-executor &&
chmod +x /opt/opensandbox/bin/task-executor
volumeMounts:
- name: opensandbox-bin
mountPath: /opt/opensandbox/bin
- name: execd-installer
image: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/execd:latest
command: [ "/bin/sh", "-c" ]
args:
- |
cp ./execd /opt/opensandbox/bin/execd &&
cp ./bootstrap.sh /opt/opensandbox/bin/bootstrap.sh &&
chmod +x /opt/opensandbox/bin/execd &&
chmod +x /opt/opensandbox/bin/bootstrap.sh
volumeMounts:
- name: opensandbox-bin
mountPath: /opt/opensandbox/bin
containers:
- name: sandbox
image: sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:latest
command:
- "/bin/sh"
- "-c"
- |
/opt/opensandbox/bin/task-executor -listen-addr=0.0.0.0:5758 >/tmp/task-executor.log 2>&1
env:
- name: SANDBOX_MAIN_CONTAINER
value: main
- name: EXECD_ENVS
value: /opt/opensandbox/.env
- name: EXECD
value: /opt/opensandbox/bin/execd
volumeMounts:
- name: sandbox-storage
mountPath: /var/lib/sandbox
- name: opensandbox-bin
mountPath: /opt/opensandbox/bin
tolerations:
- operator: "Exists"
capacitySpec:
bufferMax: 3
bufferMin: 1
poolMax: 5
poolMin: 0
```

Start the k8s OpenSandbox server:

```shell
git clone [email protected]:alibaba/OpenSandbox.git
cd OpenSandbox/server

# replace with your k8s cluster config, kubeconfig etc.
cp example.config.k8s.toml ~/.sandbox.toml
cp example.batchsandbox-template.yaml ~/batchsandbox-template.yaml

uv sync
uv run python -m src.main
```

## Create and access the Code Interpreter Sandbox

```shell
# Install OpenSandbox packages
uv pip install opensandbox opensandbox-code-interpreter

# Run the example (requires SANDBOX_DOMAIN / SANDBOX_API_KEY)
uv run python examples/code-interpreter/main_use_pool.py
```

The script creates a Sandbox + CodeInterpreter, runs a Python code snippet and prints stdout/result, then terminates the remote instance.

## Environment variables

- `SANDBOX_DOMAIN`: Sandbox service address (default: `localhost:8080`)
- `SANDBOX_API_KEY`: API key if your server requires authentication
- `SANDBOX_IMAGE`: Sandbox image to use (default: `sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:latest`)

## Example output

```text
=== Verify Environment Variable ===
[ENV Check] TEST_ENV value: test

[ENV Result] 'test'

=== Java example ===
[Java stdout] Hello from Java!

[Java stdout] 2 + 3 = 5

[Java result] 5

=== Go example ===
[Go stdout] Hello from Go!
3 + 4 = 7


=== TypeScript example ===
[TypeScript stdout] Hello from TypeScript!

Expand Down
Loading
Loading