open_sandbox 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ff9458ad74494093739cda38472437e30b4dd0a081b68bf76f91c998b7b032e
-  data.tar.gz: 829770a3369b58e83fe541745a0a1765f5c98dbdbf680be37a21a06db4b947b8
+  metadata.gz: ad3786f0020200378180e62e770b0ca8463f666d9910e3d70257c3892734400a
+  data.tar.gz: cc0b2c9240f79f07e37a69b5e74c9ab400eebb1f969833f4d4f8fa679daa189e
 SHA512:
-  metadata.gz: 8f7bd0c0f24041a75a2ab5e6ef66ed7ac99d28a3c11317d6777c4dbeec9422a5465a48a75b9dde1042b3c26646e2c7d0f03e0835ded535a4209725c23f561751
-  data.tar.gz: 8e6740dd38a16f475b4d6a11a161259e01eebae6419ac06bb4d8905ea9de51213bcdd6c1d7b5570284087e33a8e04c780f27d72f6c7ec0db1c55ca9962024b74
+  metadata.gz: a244435b09be28039d5709d687510172618173a689bc4bfcfa83cf79840b9f05b32d97ccd3a0933e96488e3d77cf324181114a6562f7f01d97371a78b238a6de
+  data.tar.gz: 72d656009b9fc0e81faa683ffc67b44ced01731a8fc9ad41cfc0e03118084dfa7ceeec3bec2241fb15eb8a0b2f52e67467a9a360004a6365c13c183e4ba757fa

data/README.md

@@ -1,10 +1,43 @@
 # OpenSandbox
 
+[中文版](README.zh-CN.md)
+
 Ruby SDK for the [open-sandbox.ai](https://open-sandbox.ai) API — manage isolated container sandboxes for secure code execution.
 
+> ⚠️ **This is an unofficial Ruby gem**, not affiliated with or maintained by the OpenSandbox team.
+> Official project: [alibaba/OpenSandbox](https://github.com/alibaba/OpenSandbox)
+
 [![Gem Version](https://badge.fury.io/rb/open_sandbox.svg)](https://rubygems.org/gems/open_sandbox)
 [![CI](https://github.com/graysonchen/open_sandbox-sdk-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/graysonchen/open_sandbox-sdk-ruby/actions)
 
+## What is OpenSandbox?
+
+[OpenSandbox](https://github.com/alibaba/OpenSandbox) is a **general-purpose sandbox platform for AI applications**, open-sourced by Alibaba and listed in the [CNCF Landscape](https://landscape.cncf.io/?item=orchestration-management--scheduling-orchestration--opensandbox).
+
+### The Problem It Solves
+
+Modern AI applications — coding agents, browser automation, RL training, AI code execution — need to **run untrusted or model-generated code safely**. Spinning up ephemeral containers manually, wiring up lifecycle management, handling networking, streaming logs, and tearing everything down reliably is complex and error-prone.
+
+OpenSandbox solves this by providing:
+
+- **Isolated runtime environments** — each sandbox runs in its own container, fully isolated from the host and other workloads. Supports secure runtimes like gVisor, Kata Containers, and Firecracker microVM.
+- **Unified sandbox lifecycle API** — provision, monitor, pause, resume, renew, and terminate sandboxes via a single consistent API, backed by Docker or Kubernetes.
+- **In-sandbox execution** — run shell commands, execute multi-language code (Python, Node.js, etc.), manage files, expose ports, and stream logs/metrics from inside the sandbox.
+- **Resource Pools** — pre-warm sandbox pools to eliminate cold-start latency for high-throughput workloads.
+- **Network policy** — per-sandbox ingress/egress controls with unified gateway routing.
+
+### Typical Use Cases
+
+| Scenario | Description |
+|---|---|
+| **Coding Agents** | Run Claude Code, Gemini CLI, Codex, and other agent tools in isolated sandboxes |
+| **AI Code Execution** | Safely execute model-generated code, stream outputs, iterate with reproducible environments |
+| **Browser Automation** | Run Chrome / Playwright workloads with controlled runtime and networking |
+| **Remote Development** | Host VS Code Web and cloud desktop environments securely |
+| **RL Training** | Launch reinforcement learning tasks with managed sandbox lifecycle and resource controls |
+
+This Ruby gem wraps the OpenSandbox HTTP API so you can use all of the above from your Ruby or Rails application.
+
 ## Installation
 
 Add to your Gemfile:
@@ -181,6 +214,10 @@ bundle install
 bundle exec rake test     # run all tests
 ```
 
+## Other SDKs
+
+OpenSandbox provides official SDKs for multiple languages. See the full list at [alibaba/OpenSandbox — SDKs](https://github.com/alibaba/OpenSandbox/tree/main#sdks).
+
 ## License
 
 MIT

data/lib/open_sandbox/execd/code_interpreter.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "json"
+
+module OpenSandbox
+  class Execd
+    class CodeInterpreter
+      CodeResult = Data.define(:stdout, :stderr, :result, :error, :execution_count, :execution_time_ms)
+      Context = Data.define(:id, :language)
+
+      def initialize(execd)
+        @execd = execd
+      end
+
+      # Create a new code execution context.
+      def create_context(language: "python")
+        response = @execd.proxy(method: :post, path: "/code/context", body: { language: language })
+        data = JSON.parse(response.body)
+        Context.new(id: data["contextId"] || data["id"], language: language)
+      end
+
+      # List active contexts.
+      def list_contexts(language: nil)
+        query_path = "/code/contexts"
+        query_path += "?language=#{language}" if language
+        response = @execd.proxy(method: :get, path: query_path)
+        data = JSON.parse(response.body)
+        contexts = data.is_a?(Array) ? data : (data["contexts"] || [])
+        contexts.map { |c| Context.new(id: c["id"], language: c["language"]) }
+      end
+
+      # Delete a context.
+      def delete_context(context_id)
+        @execd.proxy(method: :delete, path: "/code/contexts/#{context_id}")
+      end
+
+      # Execute code in a context. Returns parsed result from streaming JSON/SSE response.
+      # If a block is given, yields each parsed event as it arrives.
+      def run(code, context_id: nil, language: "python", &block)
+        context = { language: language }
+        context[:id] = context_id if context_id
+        body = { code: code, context: context }
+
+        if block_given?
+          parse_streaming_response(block) do |chunk_handler|
+            @execd.proxy_stream(method: :post, path: "/code", body: body, &chunk_handler)
+          end
+        else
+          response = @execd.proxy(method: :post, path: "/code", body: body)
+          parse_sse_code_response(response.body)
+        end
+      end
+
+      private
+
+      def parse_streaming_response(event_callback)
+        buffer = +""
+        events = []
+
+        handler = lambda do |chunk|
+          buffer << chunk
+          while (newline_index = buffer.index("\n"))
+            line = buffer.slice!(0..newline_index).strip
+            next if line.empty?
+
+            event = parse_event_line(line)
+            next unless event
+
+            events << event
+            event_callback.call(event)
+          end
+        end
+
+        yield handler
+        unless buffer.strip.empty?
+          event = parse_event_line(buffer.strip)
+          if event
+            events << event
+            event_callback.call(event)
+          end
+        end
+        build_result_from_events(events)
+      end
+
+      private
+
+      def parse_sse_code_response(body)
+        events = body.to_s.each_line.filter_map { |line| parse_event_line(line.strip) }
+        build_result_from_events(events)
+      end
+
+      def parse_event_line(line)
+        return nil if line.empty?
+
+        json_str = line.start_with?("data:") ? line.sub(/\Adata:\s*/, "") : line
+        return nil if json_str.empty?
+
+        JSON.parse(json_str)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def build_result_from_events(events)
+        stdout_lines = []
+        stderr_lines = []
+        result_text = nil
+        error_text = nil
+        exec_count = nil
+        exec_time = nil
+
+        events.each do |data|
+          case data["type"]
+          when "stdout"
+            stdout_lines << data["text"]
+          when "stderr"
+            stderr_lines << data["text"]
+          when "result"
+            result_text = data["text"]
+          when "error"
+            error = data["error"]
+            error_text = data["text"] || data["message"] || error&.dig("evalue") || error&.dig("ename")
+          when "execution_complete"
+            exec_time = data["executionTimeInMillis"] || data["execution_time"]
+          when "execution_count"
+            exec_count = data["count"]
+          end
+        end
+
+        CodeResult.new(
+          stdout: stdout_lines.join,
+          stderr: stderr_lines.join,
+          result: result_text,
+          error: error_text,
+          execution_count: exec_count,
+          execution_time_ms: exec_time
+        )
+      end
+    end
+  end
+end

data/lib/open_sandbox/execd/commands.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module OpenSandbox
+  class Execd
+    class Commands
+      CommandResult = Data.define(:stdout, :stderr, :exit_code, :execution_time_ms)
+
+      def initialize(execd)
+        @execd = execd
+      end
+
+      # Run a shell command and wait for completion.
+      # The execd API returns SSE-formatted response.
+      def run(command, timeout: 60)
+        response = @execd.proxy(
+          method: :post,
+          path: "/command",
+          body: { command: command, timeout: timeout, background: false }
+        )
+        parse_sse_response(response.body)
+      end
+
+      private
+
+      def parse_sse_response(body)
+        stdout_lines = []
+        stderr_lines = []
+        exit_code = nil
+        exec_time = nil
+
+        body.to_s.each_line do |line|
+          line = line.strip
+          next if line.empty?
+          json_str = line.start_with?("data:") ? line.sub(/\Adata:\s*/, "") : line
+          next if json_str.empty?
+
+          data = JSON.parse(json_str)
+          case data["type"]
+          when "stdout"
+            stdout_lines << data["text"]
+          when "stderr"
+            stderr_lines << data["text"]
+          when "execution_complete"
+            exit_code = data["exitCode"] || data["exit_code"] || 0
+            exec_time = data["executionTimeInMillis"] || data["execution_time"]
+          end
+        rescue JSON::ParserError
+          next
+        end
+
+        CommandResult.new(
+          stdout: stdout_lines.join,
+          stderr: stderr_lines.join,
+          exit_code: exit_code || 0,
+          execution_time_ms: exec_time
+        )
+      end
+    end
+  end
+end

data/lib/open_sandbox/execd/files.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "base64"
+require "cgi"
+require "json"
+require "securerandom"
+
+module OpenSandbox
+  class Execd
+    class Files
+      FileInfo = Data.define(:path, :size, :mode, :is_dir, :mod_time)
+      WriteEntry = Data.define(:path, :data, :mode)
+
+      def initialize(execd)
+        @execd = execd
+      end
+
+      # Write one or more files into the sandbox.
+      def write_files(entries)
+        boundary = "----OpenSandboxRuby#{SecureRandom.hex(12)}"
+        body = build_multipart_body(entries, boundary)
+        response = @execd.proxy(
+          method: :post,
+          path: "/files/upload",
+          raw_body: body,
+          headers: { "Content-Type" => "multipart/form-data; boundary=#{boundary}" }
+        )
+        response.code >= 200 && response.code < 300
+      end
+
+      # Read a file from the sandbox.
+      def read_file(path)
+        response = @execd.proxy(
+          method: :get,
+          path: "/files/download?path=#{escape(path)}"
+        )
+        response.body
+      end
+
+      # Search for files matching a pattern.
+      def search(path:, pattern: "*")
+        response = @execd.proxy(
+          method: :get,
+          path: "/files/search?path=#{escape(path)}&pattern=#{escape(pattern)}"
+        )
+        data = JSON.parse(response.body)
+        files = data.is_a?(Array) ? data : (data["files"] || [])
+        files.map do |f|
+          FileInfo.new(
+            path: f["path"],
+            size: f["size"],
+            mode: f["mode"],
+            is_dir: f["isDir"],
+            mod_time: f["modTime"]
+          )
+        end
+      end
+
+      # Get file metadata.
+      def info(path)
+        response = @execd.proxy(
+          method: :get,
+          path: "/files/info?path=#{escape(path)}"
+        )
+        data = JSON.parse(response.body)
+        FileInfo.new(
+          path: data["path"],
+          size: data["size"],
+          mode: data["mode"],
+          is_dir: data["isDir"],
+          mod_time: data["modTime"]
+        )
+      end
+
+      # Delete files.
+      def delete(paths)
+        @execd.proxy(method: :delete, path: "/files", body: { paths: paths })
+      end
+
+      # Create directories (mkdir -p semantics).
+      def mkdir(paths, mode: 755)
+        body = paths.to_h { |path| [ path, { mode: mode } ] }
+        @execd.proxy(method: :post, path: "/directories", body: body)
+      end
+
+      private
+
+      def build_multipart_body(entries, boundary)
+        body = +"".b
+        entries.each do |entry|
+          metadata = { path: entry.path, mode: entry.mode || 644 }.to_json
+          data = entry.data.to_s.b
+
+          append_binary(body, "--#{boundary}\r\n")
+          append_binary(body, "Content-Disposition: form-data; name=\"metadata\"; filename=\"metadata\"\r\n")
+          append_binary(body, "Content-Type: application/json\r\n\r\n")
+          append_binary(body, metadata)
+          append_binary(body, "\r\n")
+
+          append_binary(body, "--#{boundary}\r\n")
+          append_binary(body, "Content-Disposition: form-data; name=\"file\"; filename=\"#{File.basename(entry.path)}\"\r\n")
+          append_binary(body, "Content-Type: application/octet-stream\r\n\r\n")
+          body << data
+          append_binary(body, "\r\n")
+        end
+        append_binary(body, "--#{boundary}--\r\n")
+        body
+      end
+
+      def append_binary(body, value)
+        body << value.to_s.b
+      end
+
+      def escape(value)
+        CGI.escape(value.to_s)
+      end
+    end
+  end
+end

data/lib/open_sandbox/execd.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "execd/commands"
+require_relative "execd/files"
+require_relative "execd/code_interpreter"
+
+module OpenSandbox
+  class Execd
+    EXECD_PORT = 44772
+
+    attr_reader :sandbox_id
+
+    def initialize(sandbox_id:, client: OpenSandbox.client)
+      @sandbox_id = sandbox_id
+      @client = client
+    end
+
+    def commands
+      @commands ||= Execd::Commands.new(self)
+    end
+
+    def files
+      @files ||= Execd::Files.new(self)
+    end
+
+    def code_interpreter
+      @code_interpreter ||= Execd::CodeInterpreter.new(self)
+    end
+
+    # Low-level proxy helper — routes HTTP requests through the OpenSandbox server proxy
+    def proxy(method:, path:, body: nil, headers: {}, raw_body: nil)
+      @client.sandboxes.proxy(
+        @sandbox_id,
+        port: EXECD_PORT,
+        method: method,
+        path: path,
+        body: body,
+        headers: headers,
+        raw_body: raw_body
+      )
+    end
+
+    def proxy_stream(method:, path:, body: nil, headers: {}, raw_body: nil, &block)
+      @client.sandboxes.proxy_stream(
+        @sandbox_id,
+        port: EXECD_PORT,
+        method: method,
+        path: path,
+        body: body,
+        headers: headers,
+        raw_body: raw_body,
+        &block
+      )
+    end
+
+    def ping
+      response = proxy(method: :get, path: "/ping")
+      response.code == 200
+    rescue OpenSandbox::Error
+      false
+    end
+  end
+end

data/lib/open_sandbox/http_client.rb

@@ -2,6 +2,8 @@
 
 require "json"
 require "httparty"
+require "net/http"
+require "uri"
 
 module OpenSandbox
   # Low-level HTTP client for the OpenSandbox API.
@@ -38,13 +40,18 @@ module OpenSandbox
 
     # Proxy raw HTTP request to sandbox internal service
     # Returns the raw HTTParty response
-    def proxy(method, path, body: nil, headers: {})
-      request(method, path, body: body, headers: headers, raw: true)
+    def proxy(method, path, body: nil, headers: {}, raw_body: nil)
+      request(method, path, body: body, headers: headers, raw: true, raw_body: raw_body)
+    end
+
+    # Stream raw HTTP response body chunks. Intended for SSE/JSONL execd proxy endpoints.
+    def proxy_stream(method, path, body: nil, headers: {}, raw_body: nil, &block)
+      stream_request(method, path, body: body, headers: headers, raw_body: raw_body, &block)
     end
 
     private
 
-    def request(method, path, query: {}, body: nil, headers: {}, raw: false)
+    def request(method, path, query: {}, body: nil, headers: {}, raw: false, raw_body: nil)
       url = "#{base_url}#{path}"
       options = {
         timeout:      timeout,
@@ -53,7 +60,9 @@ module OpenSandbox
       }
       options[:query] = query if query && !query.empty?
 
-      if body
+      if raw_body
+        options[:body] = raw_body
+      elsif body
         options[:body]    = body.to_json
         options[:headers] = (options[:headers] || {}).merge("Content-Type" => "application/json")
       end
@@ -70,10 +79,53 @@ module OpenSandbox
 
     def build_headers(extra = {})
       headers = { "Accept" => "application/json" }
-      headers["Authorization"] = "Bearer #{api_key}" if api_key && !api_key.empty?
+      headers["OPEN-SANDBOX-API-KEY"] = api_key if api_key && !api_key.empty?
       headers.merge(extra)
     end
 
+    def stream_request(method, path, body: nil, headers: {}, raw_body: nil)
+      uri = URI("#{base_url}#{path}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = DEFAULT_OPEN_TIMEOUT
+      http.read_timeout = timeout
+
+      request_class = case method.to_sym
+      when :get then Net::HTTP::Get
+      when :post then Net::HTTP::Post
+      when :put then Net::HTTP::Put
+      when :delete then Net::HTTP::Delete
+      else
+        raise InvalidRequestError, "Unsupported streaming method: #{method}"
+      end
+
+      req = request_class.new(uri)
+      build_headers(headers).each { |key, value| req[key] = value }
+
+      if raw_body
+        req.body = raw_body
+      elsif body
+        req.body = body.to_json
+        req["Content-Type"] ||= "application/json"
+      end
+
+      http.request(req) do |response|
+        unless response.code.to_i.between?(200, 299)
+          error_body = +""
+          response.read_body { |chunk| error_body << chunk }
+          raise Error, "Unexpected status #{response.code}: #{error_body}"
+        end
+
+        response.read_body do |chunk|
+          yield chunk.force_encoding("UTF-8")
+        end
+      end
+    rescue ::Net::OpenTimeout, ::Net::ReadTimeout => e
+      raise ConnectionError, "Request timed out: #{e.message}"
+    rescue ::SocketError, ::Errno::ECONNREFUSED => e
+      raise ConnectionError, "Cannot connect to sandbox server at #{base_url}: #{e.message}"
+    end
+
     def handle_response(response)
       case response.code
       when 200, 201, 202

data/lib/open_sandbox/sandboxes.rb

@@ -137,12 +137,12 @@ module OpenSandbox
     # @param body [Hash, nil] request body
     # @param headers [Hash] additional headers
     # @return [HTTParty::Response] raw response
-    def proxy(sandbox_id, port:, method: :get, path: "/", body: nil, headers: {})
-      proxy_path = path == "/" || path.empty? \
-        ? "/v1/sandboxes/#{sandbox_id}/proxy/#{port}" \
-        : "/v1/sandboxes/#{sandbox_id}/proxy/#{port}/#{path.delete_prefix('/')}"
+    def proxy(sandbox_id, port:, method: :get, path: "/", body: nil, headers: {}, raw_body: nil)
+      @http.proxy(method, proxy_path(sandbox_id, port, path), body: body, headers: headers, raw_body: raw_body)
+    end
 
-      @http.proxy(method, proxy_path, body: body, headers: headers)
+    def proxy_stream(sandbox_id, port:, method: :get, path: "/", body: nil, headers: {}, raw_body: nil, &block)
+      @http.proxy_stream(method, proxy_path(sandbox_id, port, path), body: body, headers: headers, raw_body: raw_body, &block)
     end
 
     # ── Diagnostics ─────────────────────────────────────────────────────────
@@ -220,6 +220,12 @@ module OpenSandbox
 
     private
 
+    def proxy_path(sandbox_id, port, path)
+      path == "/" || path.empty? \
+        ? "/v1/sandboxes/#{sandbox_id}/proxy/#{port}" \
+        : "/v1/sandboxes/#{sandbox_id}/proxy/#{port}/#{path.delete_prefix('/')}"
+    end
+
     def build_image_spec(image, auth)
       spec = { "uri" => image }
       if auth

data/lib/open_sandbox/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenSandbox
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/open_sandbox.rb

@@ -3,3 +3,4 @@
 require_relative "open_sandbox/version"
 require_relative "open_sandbox/client"
 require_relative "open_sandbox/runner"
+require_relative "open_sandbox/execd"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: open_sandbox
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Grayson Chen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-29 00:00:00.000000000 Z
+date: 2026-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -48,6 +48,10 @@ files:
 - lib/open_sandbox.rb
 - lib/open_sandbox/client.rb
 - lib/open_sandbox/errors.rb
+- lib/open_sandbox/execd.rb
+- lib/open_sandbox/execd/code_interpreter.rb
+- lib/open_sandbox/execd/commands.rb
+- lib/open_sandbox/execd/files.rb
 - lib/open_sandbox/http_client.rb
 - lib/open_sandbox/models.rb
 - lib/open_sandbox/pools.rb
@@ -71,7 +75,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="