Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

fix(execd): discover standalone Jupyter runtime token

yutian.taoytec741d561c27
diff --git a/components/execd/pkg/runtime/context.go b/components/execd/pkg/runtime/context.go
index 892745426..3adc3ccef 100644
--- a/components/execd/pkg/runtime/context.go
+++ b/components/execd/pkg/runtime/context.go
@@ -108,10 +108,15 @@ func (c *Controller) DeleteLanguageContext(language Language) error {
}
func (c *Controller) deleteSessionAndCleanup(session string) error {
- if c.getJupyterKernel(session) == nil {
+ kernel := c.getJupyterKernel(session)
+ if kernel == nil {
return ErrContextNotFound
}
- if err := c.jupyterClient().DeleteSession(session); err != nil {
+ client := kernel.client
+ if client == nil {
+ client = c.jupyterClient()
+ }
+ if err := client.DeleteSession(session); err != nil {
return err
}
c.jupyterClientMap.Delete(session)
@@ -174,7 +179,11 @@ func (c *Controller) createDefaultLanguageJupyterContext(language Language) erro
// createJupyterContext performs the actual context creation workflow.
func (c *Controller) createJupyterContext(request CreateContextRequest) (*jupyter.Client, *jupytersession.Session, error) {
- client := c.jupyterClient()
+ token := c.jupyterToken()
+ if c.baseURL == "" || token == "" {
+ return nil, nil, errJupyterNotConfigured
+ }
+ client := c.jupyterClientWithToken(token)
kernel, err := c.searchKernel(client, request.Language)
if err != nil {
@@ -216,15 +225,19 @@ func (c *Controller) storeJupyterKernel(sessionID string, kernel *jupyterKernel)
}
func (c *Controller) jupyterClient() *jupyter.Client {
+ return c.jupyterClientWithToken(c.jupyterToken())
+}
+
+func (c *Controller) jupyterClientWithToken(token string) *jupyter.Client {
httpClient := &http.Client{
Transport: &jupyter.AuthTransport{
- Token: c.token,
+ Token: token,
Base: http.DefaultTransport,
},
}
return jupyter.NewClient(c.baseURL,
- jupyter.WithToken(c.token),
+ jupyter.WithToken(token),
jupyter.WithHTTPClient(httpClient))
}
diff --git a/components/execd/pkg/runtime/context_test.go b/components/execd/pkg/runtime/context_test.go
index 605842ab4..00f603c80 100644
--- a/components/execd/pkg/runtime/context_test.go
+++ b/components/execd/pkg/runtime/context_test.go
@@ -15,12 +15,14 @@
package runtime
import (
+ "encoding/json"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"testing"
+ "time"
"github.com/stretchr/testify/require"
)
@@ -162,3 +164,100 @@ func TestDeleteLanguageContext_RemovesCacheOnSuccess(t *testing.T) {
require.Equal(t, 1, deleteCalls[session1])
require.Equal(t, 1, deleteCalls[session2])
}
+
+func writeJupyterServerFile(t *testing.T, rootDir, dirName, fileName string, info jupyterRuntimeServerInfo) string {
+ t.Helper()
+ runtimeDir := filepath.Join(rootDir, dirName)
+ require.NoError(t, os.MkdirAll(runtimeDir, 0o700))
+ serverFile := filepath.Join(runtimeDir, fileName)
+ data, err := json.Marshal(info)
+ require.NoError(t, err)
+ require.NoError(t, os.WriteFile(serverFile, data, 0o600))
+ return serverFile
+}
+
+func TestCreateAndDeleteContext_DiscoversStandaloneJupyterRuntimeToken(t *testing.T) {
+ const discoveredToken = "standalone-random-token-64hex"
+
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ require.Equal(t, "Token "+discoveredToken, r.Header.Get("Authorization"))
+ w.Header().Set("Content-Type", "application/json")
+ switch {
+ case r.Method == http.MethodGet && strings.HasSuffix(r.URL.Path, "/api/kernelspecs"):
+ _, _ = w.Write([]byte(`{"default":"python","kernelspecs":{"python":{"name":"python","spec":{"language":"python","display_name":"Python"}}}}`))
+ case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, "/api/sessions"):
+ w.WriteHeader(http.StatusCreated)
+ _, _ = w.Write([]byte(`{"id":"sess-discovered","kernel":{"id":"kernel-1","name":"python"}}`))
+ case r.Method == http.MethodGet && strings.HasSuffix(r.URL.Path, "/api/kernels"):
+ _, _ = w.Write([]byte(`[{"id":"kernel-1","name":"python"}]`))
+ case r.Method == http.MethodDelete && strings.HasSuffix(r.URL.Path, "/api/sessions/sess-discovered"):
+ w.WriteHeader(http.StatusNoContent)
+ default:
+ require.Failf(t, "unexpected request", "%s %s", r.Method, r.URL.Path)
+ }
+ }))
+ defer server.Close()
+
+ runtimeRoot := t.TempDir()
+ port := jupyterPortFromBaseURL(server.URL)
+ require.Greater(t, port, 0)
+ writeJupyterServerFile(t, runtimeRoot, "opensandbox-jupyter.abc123", "jpserver-1.json", jupyterRuntimeServerInfo{
+ Port: port,
+ Token: discoveredToken,
+ })
+
+ c := NewController(server.URL, "")
+ c.jupyterRuntimeRoot = runtimeRoot
+
+ sessionID, err := c.CreateContext(&CreateContextRequest{
+ Language: Python,
+ Cwd: t.TempDir(),
+ })
+ require.NoError(t, err)
+ require.Equal(t, "sess-discovered", sessionID)
+ require.NoError(t, c.DeleteContext(sessionID))
+}
+
+func TestJupyterTokenDiscovery_FiltersAndPrecedence(t *testing.T) {
+ const (
+ port = 44771
+ baseURL = "http://127.0.0.1:44771"
+ oldToken = "older-valid-token"
+ newToken = "newer-valid-token"
+ initToken = "explicit-bootstrap-token"
+ )
+
+ runtimeRoot := t.TempDir()
+
+ // 1. Mismatched port is ignored.
+ writeJupyterServerFile(t, runtimeRoot, "opensandbox-jupyter.wrongport", "jpserver-1.json", jupyterRuntimeServerInfo{
+ Port: 44772,
+ Token: "wrong-port-token",
+ })
+
+ c := NewController(baseURL, "")
+ c.jupyterRuntimeRoot = runtimeRoot
+ require.Empty(t, c.jupyterToken())
+
+ // 2. Newest valid server file wins.
+ oldFile := writeJupyterServerFile(t, runtimeRoot, "opensandbox-jupyter.old", "jpserver-2.json", jupyterRuntimeServerInfo{
+ Port: port,
+ Token: oldToken,
+ })
+ oldTime := time.Now().Add(-10 * time.Second)
+ require.NoError(t, os.Chtimes(oldFile, oldTime, oldTime))
+
+ newFile := writeJupyterServerFile(t, runtimeRoot, "opensandbox-jupyter.new", "jpserver-3.json", jupyterRuntimeServerInfo{
+ Port: port,
+ Token: newToken,
+ })
+ newTime := time.Now().Add(-2 * time.Second)
+ require.NoError(t, os.Chtimes(newFile, newTime, newTime))
+
+ require.Equal(t, newToken, c.jupyterToken())
+
+ // 3. Explicit token always takes precedence over runtime discovery.
+ configured := NewController(baseURL, initToken)
+ configured.jupyterRuntimeRoot = runtimeRoot
+ require.Equal(t, initToken, configured.jupyterToken())
+}
diff --git a/components/execd/pkg/runtime/ctrl.go b/components/execd/pkg/runtime/ctrl.go
index 1efb7b9e1..cf0e8f465 100644
--- a/components/execd/pkg/runtime/ctrl.go
+++ b/components/execd/pkg/runtime/ctrl.go
@@ -37,6 +37,7 @@ var kernelWaitingBackoff = wait.Backoff{
type Controller struct {
baseURL string
token string
+ jupyterRuntimeRoot string
mu sync.RWMutex
jupyterClientMap sync.Map // map[sessionID]*jupyterKernel
defaultLanguageSessions sync.Map // map[Language]string
diff --git a/components/execd/pkg/runtime/jupyter.go b/components/execd/pkg/runtime/jupyter.go
index 782be5787..bd7f7c5bc 100644
--- a/components/execd/pkg/runtime/jupyter.go
+++ b/components/execd/pkg/runtime/jupyter.go
@@ -16,17 +16,31 @@ package runtime
import (
"context"
+ "encoding/json"
"errors"
+ "net/url"
+ "os"
+ "path/filepath"
+ "strconv"
+ "strings"
+ "time"
"github.com/alibaba/opensandbox/execd/pkg/jupyter"
"github.com/alibaba/opensandbox/execd/pkg/jupyter/execute"
"github.com/alibaba/opensandbox/execd/pkg/log"
)
+var errJupyterNotConfigured = errors.New("language runtime server not configured, please check your image runtime")
+
+type jupyterRuntimeServerInfo struct {
+ Port int `json:"port"`
+ Token string `json:"token"`
+}
+
// runJupyter executes code through a Jupyter kernel.
func (c *Controller) runJupyter(ctx context.Context, request *ExecuteCodeRequest) error {
- if c.baseURL == "" || c.token == "" {
- return errors.New("language runtime server not configured, please check your image runtime")
+ if c.baseURL == "" {
+ return errJupyterNotConfigured
}
if request.Context == "" {
if c.getDefaultLanguageSession(request.Language) == "" {
@@ -45,6 +59,9 @@ func (c *Controller) runJupyter(ctx context.Context, request *ExecuteCodeRequest
kernel := c.getJupyterKernel(targetSessionID)
if kernel == nil {
+ if c.jupyterToken() == "" {
+ return errJupyterNotConfigured
+ }
return ErrContextNotFound
}
@@ -165,3 +182,88 @@ func (c *Controller) searchKernel(client *jupyter.Client, language Language) (st
return kernelName, nil
}
+
+func (c *Controller) jupyterToken() string {
+ if c.token != "" {
+ return c.token
+ }
+ return c.discoverJupyterToken()
+}
+
+// discoverJupyterToken reads the token written by a standalone code-interpreter
+// entrypoint in /tmp/opensandbox-jupyter.*/jpserver-*.json when execd is
+// launched without bootstrap.sh (for example via fast-sandbox infraComponents).
+func (c *Controller) discoverJupyterToken() string {
+ targetPort := jupyterPortFromBaseURL(c.baseURL)
+ if targetPort <= 0 {
+ return ""
+ }
+ root := c.jupyterRuntimeRoot
+ if root == "" {
+ root = "/tmp"
+ }
+ matches, err := filepath.Glob(filepath.Join(root, "opensandbox-jupyter.*", "jpserver-*.json"))
+ if err != nil {
+ return ""
+ }
+
+ var (
+ bestToken string
+ bestModTime time.Time
+ )
+ for _, match := range matches {
+ token, modTime, ok := readJupyterRuntimeToken(match, targetPort)
+ if !ok {
+ continue
+ }
+ if bestToken == "" || modTime.After(bestModTime) {
+ bestToken = token
+ bestModTime = modTime
+ }
+ }
+ return bestToken
+}
+
+func readJupyterRuntimeToken(filePath string, targetPort int) (string, time.Time, bool) {
+ fileInfo, err := os.Lstat(filePath)
+ if err != nil || !fileInfo.Mode().IsRegular() {
+ return "", time.Time{}, false
+ }
+
+ data, err := os.ReadFile(filePath)
+ if err != nil {
+ return "", time.Time{}, false
+ }
+
+ var info jupyterRuntimeServerInfo
+ if err := json.Unmarshal(data, &info); err != nil {
+ return "", time.Time{}, false
+ }
+ token := strings.TrimSpace(info.Token)
+ if token == "" || info.Port != targetPort {
+ return "", time.Time{}, false
+ }
+ return token, fileInfo.ModTime(), true
+}
+
+func jupyterPortFromBaseURL(baseURL string) int {
+ parsed, err := url.Parse(baseURL)
+ if err != nil {
+ return 0
+ }
+ if portStr := parsed.Port(); portStr != "" {
+ port, err := strconv.Atoi(portStr)
+ if err != nil || port <= 0 {
+ return 0
+ }
+ return port
+ }
+ switch strings.ToLower(parsed.Scheme) {
+ case "http":
+ return 80
+ case "https":
+ return 443
+ default:
+ return 0
+ }
+}
diff --git a/docs/reference/code-interpreter-image-migration.md b/docs/reference/code-interpreter-image-migration.md
index 8d9504e97..7ddc9a3bb 100644
--- a/docs/reference/code-interpreter-image-migration.md
+++ b/docs/reference/code-interpreter-image-migration.md
@@ -46,6 +46,10 @@ This migration is purely structural for monorepo maintenance. Container image co
| **Environment Variables** | Unchanged | Language version selection via `PYTHON_VERSION`, `JAVA_VERSION`, `NODE_VERSION`, `GO_VERSION` remains identical |
| **SDK Usage** | Unchanged | Client code using `CodeInterpreter` classes requires no modifications |
+### Jupyter Authentication
+
+When `JUPYTER_TOKEN` is not explicitly configured, the `code-interpreter` entrypoint generates a per-sandbox random token on startup and writes its server metadata to an owner-only `/tmp/opensandbox-jupyter.*/jpserver-*.json` runtime file, which `execd` discovers automatically. An explicit nonempty `JUPYTER_TOKEN` remains supported and takes precedence. When pairing a new image with an older `execd` release that does not discover runtime tokens, supply an explicit `JUPYTER_TOKEN` at sandbox creation.
+
### Signature and Provenance Verification
Operators and users who verify container image signatures or build provenance should note the workflow identity: