open_sandbox 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ff9458ad74494093739cda38472437e30b4dd0a081b68bf76f91c998b7b032e
+  data.tar.gz: 829770a3369b58e83fe541745a0a1765f5c98dbdbf680be37a21a06db4b947b8
+SHA512:
+  metadata.gz: 8f7bd0c0f24041a75a2ab5e6ef66ed7ac99d28a3c11317d6777c4dbeec9422a5465a48a75b9dde1042b3c26646e2c7d0f03e0835ded535a4209725c23f561751
+  data.tar.gz: 8e6740dd38a16f475b4d6a11a161259e01eebae6419ac06bb4d8905ea9de51213bcdd6c1d7b5570284087e33a8e04c780f27d72f6c7ec0db1c55ca9962024b74

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-04-29
+
+### Added
+- Initial release
+- `OpenSandbox::Client` with global `configure` block and singleton `OpenSandbox.client`
+- `Sandboxes` resource: `list`, `get`, `create`, `delete`, `pause`, `resume`, `renew_expiration`, `endpoint`, `proxy`, `wait_until`
+- `Sandboxes` diagnostics: `logs`, `inspect_container`, `events`, `diagnostics`
+- `Pools` resource: `list`, `get`, `create`, `update`, `delete`
+- Typed value objects: `Sandbox`, `SandboxStatus`, `Endpoint`, `Pool`, `PoolCapacitySpec`, `SandboxList`, `PaginationInfo`
+- Full error hierarchy: `InvalidRequestError`, `AuthenticationError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `ValidationError`, `ServerError`, `ConnectionError`
+- Configurable `Logger` (silent by default)
+- Docker timestamp stripping utility (`OpenSandbox::LogUtils.strip_timestamps`)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leonx AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,186 @@
+# OpenSandbox
+
+Ruby SDK for the [open-sandbox.ai](https://open-sandbox.ai) API — manage isolated container sandboxes for secure code execution.
+
+[![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)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "open_sandbox", path: "../open_sandbox"   # local development
+# or, once published:
+gem "open_sandbox", "~> 0.1"
+```
+
+## Rails
+
+Generate the initializer in your Rails app:
+
+```bash
+rails generate open_sandbox:install
+```
+
+This creates `config/initializers/open_sandbox.rb`:
+
+```ruby
+OpenSandbox.configure do |config|
+  # config.base_url = ENV.fetch("SANDBOX_DOMAIN", "https://api.open-sandbox.ai")
+  # config.api_key  = ENV.fetch("SANDBOX_API_KEY")
+  # config.timeout  = 300
+  # config.logger   = Rails.logger
+end
+```
+
+Uncomment and adjust the options you need. By default the SDK reads `SANDBOX_DOMAIN` and `SANDBOX_API_KEY` from ENV, so the initializer can stay empty for most setups.
+
+## Quick Start
+
+```ruby
+require "open_sandbox"
+
+# Configure (picks up SANDBOX_DOMAIN / SANDBOX_API_KEY from ENV by default)
+OpenSandbox.configure do |c|
+  c.base_url = "http://localhost:8787"   # or "https://api.open-sandbox.ai"
+  c.api_key  = "sk-..."                  # omit for local dev
+  c.logger   = Logger.new($stdout, level: :debug)
+end
+```
+
+
+## Runner — one-shot code execution
+
+```ruby
+# Python
+result = OpenSandbox::Runner.python("print(2 ** 10)")
+result.output    # => "1024\n"
+result.success?  # => true
+result.elapsed   # => 3.14
+
+# Node.js
+result = OpenSandbox::Runner.node("console.log('hi')")
+
+# Shell
+result = OpenSandbox::Runner.shell("echo $((6 * 7))")
+
+# Custom image
+result = OpenSandbox::Runner.call(
+  image:   "ubuntu:24.04",
+  command: ["bash", "-c", "ls /"],
+  timeout: 60
+)
+```
+
+The sandbox is always deleted after the run (even on error).
+`Runner` uses `OpenSandbox.logger` — set it to `Rails.logger` in your initializer to get structured logs.
+
+Timeout resolution order: explicit `timeout:` argument → `SANDBOX_TIMEOUT` ENV → `300` s (default).
+
+## OpenSandbox client
+
+```
+client = OpenSandbox.client
+
+# Create a sandbox
+sandbox = client.sandboxes.create(
+  image:           "python:3.11-slim",
+  entrypoint:      ["python", "-c", "print(2 ** 10)"],
+  timeout:         300,
+  resource_limits: { "cpu" => "500m", "memory" => "256Mi" }
+)
+puts sandbox.id        # => "c9a03139-..."
+puts sandbox.status.state  # => "Running"
+
+# Wait until Running
+client.sandboxes.wait_until(sandbox.id, target_state: OpenSandbox::SandboxState::RUNNING)
+
+# Get endpoint for a service on port 8080
+ep = client.sandboxes.endpoint(sandbox.id, port: 8080)
+puts ep.url   # => "http://sb-xxx.sandbox.local:8080"
+
+# Proxy an HTTP request directly to the sandbox
+response = client.sandboxes.proxy(sandbox.id, port: 8080, method: :post,
+                                  path: "/run", body: { code: "print(1)" })
+
+# Fetch logs (Docker timestamps stripped automatically)
+puts client.sandboxes.logs(sandbox.id, tail: 100)
+
+# Lifecycle management
+client.sandboxes.pause(sandbox.id)
+client.sandboxes.resume(sandbox.id)
+client.sandboxes.renew_expiration(sandbox.id, expires_at: Time.now + 3600)
+client.sandboxes.delete(sandbox.id)
+```
+
+## Resource Pools (pre-warm for low cold-start)
+
+```ruby
+pool = client.pools.create(
+  name:     "python-pool",
+  template: { spec: { containers: [{ name: "main", image: "python:3.11-slim" }] } },
+  capacity_spec: OpenSandbox::PoolCapacitySpec.new(
+    buffer_max: 5, buffer_min: 2, pool_max: 20, pool_min: 2
+  )
+)
+
+# Use the pool when creating a sandbox
+client.sandboxes.create(
+  image:      "python:3.11-slim",
+  entrypoint: ["python", "app.py"],
+  resource_limits: { "cpu" => "1", "memory" => "512Mi" },
+  extensions: { "poolRef" => "python-pool" }
+)
+```
+
+## Diagnostics
+
+```ruby
+puts client.sandboxes.logs(id, tail: 200, since: "10m")
+puts client.sandboxes.events(id, limit: 50)
+puts client.sandboxes.diagnostics(id)     # inspect + events + logs combined
+```
+
+## Configuration
+
+| Option     | ENV var           | Default                    |
+|------------|-------------------|----------------------------|
+| `base_url` | `SANDBOX_DOMAIN`  | `http://localhost:8787`    |
+| `api_key`  | `SANDBOX_API_KEY` | `nil` (optional for local) |
+| `timeout`  | `SANDBOX_TIMEOUT` | `300` (seconds)            |
+| `logger`   | —                 | `Logger.new(nil)` (silent) |
+
+## Error Handling
+
+```ruby
+rescue OpenSandbox::NotFoundError   => e  # 404
+rescue OpenSandbox::AuthenticationError   # 401
+rescue OpenSandbox::ForbiddenError        # 403
+rescue OpenSandbox::ConflictError         # 409
+rescue OpenSandbox::ValidationError       # 422
+rescue OpenSandbox::ServerError           # 5xx
+rescue OpenSandbox::ConnectionError       # network / timeout
+rescue OpenSandbox::Error                 # catch-all
+```
+
+## Log Utility
+
+Strip Docker-style timestamp prefixes from raw log strings:
+
+```ruby
+raw = "2026-04-29T13:37:33.993Z 1024\n"
+OpenSandbox::LogUtils.strip_timestamps(raw)
+# => "1024\n"
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test     # run all tests
+```
+
+## License
+
+MIT

data/lib/generators/open_sandbox/install_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module OpenSandbox
+  module Generators
+    # Generates config/initializers/open_sandbox.rb in the host Rails app.
+    #
+    # Usage:
+    #   rails generate open_sandbox:install
+    #
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an OpenSandbox initializer in config/initializers/"
+
+      def copy_initializer
+        template "initializer.rb", "config/initializers/open_sandbox.rb"
+      end
+    end
+  end
+end

data/lib/generators/open_sandbox/templates/initializer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "open_sandbox"
+
+# Configuration reference:
+#   base_url — API endpoint (default: ENV["SANDBOX_DOMAIN"] || "http://localhost:8787")
+#   api_key  — Authentication key (default: ENV["SANDBOX_API_KEY"])
+#   timeout  — HTTP request timeout in seconds (default: 30)
+#   logger   — Ruby Logger instance (default: silent)
+#
+OpenSandbox.configure do |config|
+  # Set via Rails credentials: Rails.application.credentials.sandbox_domain
+  config.base_url = ENV.fetch("SANDBOX_DOMAIN", "http://localhost:8080")
+
+  # API Key: optional for local dev, required for production
+  # Set via Rails credentials: Rails.application.credentials.sandbox_api_key
+  config.api_key  = ENV.fetch("SANDBOX_API_KEY", nil)
+
+  # HTTP timeout in seconds
+  config.timeout  = ENV.fetch("SANDBOX_TIMEOUT", 300).to_i
+
+  # config.logger   = Logger.new($stdout, level: :debug)
+end

data/lib/open_sandbox/client.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "logger"
+require_relative "errors"
+require_relative "models"
+require_relative "http_client"
+require_relative "sandboxes"
+require_relative "pools"
+
+# OpenSandbox Ruby SDK
+#
+# Wraps the open-sandbox.ai REST API for managing isolated container sandboxes.
+#
+# == Quick Start
+#
+#   client = OpenSandbox::Client.new
+#
+#   sandbox = client.sandboxes.create(
+#     image:      "python:3.11-slim",
+#     entrypoint: ["python", "-c", "print('hello')"],
+#     timeout:    300
+#   )
+#
+#   client.sandboxes.wait_until(sandbox.id, target_state: OpenSandbox::SandboxState::RUNNING)
+#   endpoint = client.sandboxes.endpoint(sandbox.id, port: 8080)
+#   client.sandboxes.delete(sandbox.id)
+#
+# == Configuration
+#
+#   OpenSandbox.configure do |c|
+#     c.base_url = "https://api.open-sandbox.ai"
+#     c.api_key  = "sk-..."
+#     c.timeout  = 300
+#     c.logger   = Logger.new($stdout, level: :info)
+#   end
+#
+module OpenSandbox
+  # Global configuration object
+  class Configuration
+    attr_accessor :base_url, :api_key, :timeout, :logger
+
+    def initialize
+      @base_url = ENV.fetch("SANDBOX_DOMAIN", "http://localhost:8787")
+      @api_key  = ENV.fetch("SANDBOX_API_KEY", nil)
+      @timeout  = ENV.fetch("SANDBOX_TIMEOUT", 300).to_i
+      @logger   = Logger.new(nil) # silent by default
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+      reset_client!
+    end
+
+    # Shortcut: OpenSandbox.client (singleton, reset after configure)
+    def client
+      @client ||= Client.new
+    end
+
+    def reset_client!
+      @client = nil
+    end
+
+    # Convenience delegators
+    def logger = configuration.logger
+  end
+
+  # Main entry point for the OpenSandbox SDK.
+  class Client
+    # @param base_url [String, nil] override global config
+    # @param api_key  [String, nil] override global config
+    # @param timeout  [Integer, nil] override global config
+    # @param logger   [Logger, nil] override global config
+    def initialize(base_url: nil, api_key: nil, timeout: nil, logger: nil)
+      cfg       = OpenSandbox.configuration
+      @base_url = base_url || cfg.base_url
+      @api_key  = api_key  || cfg.api_key
+      @timeout  = timeout  || cfg.timeout
+      @logger   = logger   || cfg.logger
+    end
+
+    # @return [Sandboxes]
+    def sandboxes
+      @sandboxes ||= Sandboxes.new(http, logger: @logger)
+    end
+
+    # @return [Pools]
+    def pools
+      @pools ||= Pools.new(http)
+    end
+
+    # Health check — returns true if the server responds successfully.
+    # @return [Boolean]
+    def healthy?
+      http.get("/health")
+      true
+    rescue Error
+      false
+    end
+
+    private
+
+    def http
+      @http ||= HttpClient.new(base_url: @base_url, api_key: @api_key, timeout: @timeout)
+    end
+  end
+end

data/lib/open_sandbox/errors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OpenSandbox
+  # Base error for all OpenSandbox errors
+  class Error < StandardError; end
+
+  # 400 - Invalid request
+  class InvalidRequestError < Error; end
+
+  # 401 - Missing or invalid credentials
+  class AuthenticationError < Error; end
+
+  # 403 - Insufficient permissions
+  class ForbiddenError < Error; end
+
+  # 404 - Resource not found
+  class NotFoundError < Error; end
+
+  # 409 - Conflict (e.g., already exists, wrong state)
+  class ConflictError < Error; end
+
+  # 422 - Validation error
+  class ValidationError < Error; end
+
+  # 500 - Server error
+  class ServerError < Error; end
+
+  # Connection / timeout errors
+  class ConnectionError < Error; end
+end

data/lib/open_sandbox/http_client.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "json"
+require "httparty"
+
+module OpenSandbox
+  # Low-level HTTP client for the OpenSandbox API.
+  # Not intended to be used directly – use Client instead.
+  class HttpClient
+    include HTTParty
+
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_OPEN_TIMEOUT = 10
+
+    attr_reader :base_url, :api_key, :timeout
+
+    def initialize(base_url:, api_key: nil, timeout: DEFAULT_TIMEOUT)
+      @base_url     = base_url.chomp("/")
+      @api_key      = api_key
+      @timeout      = timeout
+    end
+
+    def get(path, query: {}, headers: {})
+      request(:get, path, query: query.compact, headers: headers)
+    end
+
+    def post(path, body: {}, headers: {})
+      request(:post, path, body: body, headers: headers)
+    end
+
+    def put(path, body: {}, headers: {})
+      request(:put, path, body: body, headers: headers)
+    end
+
+    def delete(path, headers: {})
+      request(:delete, path, headers: headers)
+    end
+
+    # 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)
+    end
+
+    private
+
+    def request(method, path, query: {}, body: nil, headers: {}, raw: false)
+      url = "#{base_url}#{path}"
+      options = {
+        timeout:      timeout,
+        open_timeout: DEFAULT_OPEN_TIMEOUT,
+        headers:      build_headers(headers)
+      }
+      options[:query] = query if query && !query.empty?
+
+      if body
+        options[:body]    = body.to_json
+        options[:headers] = (options[:headers] || {}).merge("Content-Type" => "application/json")
+      end
+
+      response = self.class.send(method, url, options)
+
+      return response if raw
+      handle_response(response)
+    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 build_headers(extra = {})
+      headers = { "Accept" => "application/json" }
+      headers["Authorization"] = "Bearer #{api_key}" if api_key && !api_key.empty?
+      headers.merge(extra)
+    end
+
+    def handle_response(response)
+      case response.code
+      when 200, 201, 202
+        parse_json(response)
+      when 204
+        nil
+      when 400
+        raise InvalidRequestError, error_message(response)
+      when 401
+        raise AuthenticationError, error_message(response)
+      when 403
+        raise ForbiddenError, error_message(response)
+      when 404
+        raise NotFoundError, error_message(response)
+      when 409
+        raise ConflictError, error_message(response)
+      when 422
+        raise ValidationError, error_message(response)
+      when 500..599
+        raise ServerError, "Server error (#{response.code}): #{error_message(response)}"
+      else
+        raise Error, "Unexpected status #{response.code}: #{response.body}"
+      end
+    end
+
+    def parse_json(response)
+      body = response.body
+      return nil if body.nil? || body.empty?
+      JSON.parse(body)
+    rescue JSON::ParserError
+      response.body
+    end
+
+    def error_message(response)
+      data = parse_json(response)
+      if data.is_a?(Hash)
+        data["message"] || data["detail"] || response.body
+      else
+        response.body
+      end
+    rescue
+      response.body
+    end
+  end
+end

data/lib/open_sandbox/models.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "time"
+
+module OpenSandbox
+  # Sandbox lifecycle states
+  module SandboxState
+    PENDING    = "Pending"
+    RUNNING    = "Running"
+    PAUSING    = "Pausing"
+    PAUSED     = "Paused"
+    STOPPING   = "Stopping"
+    TERMINATED = "Terminated"
+    FAILED     = "Failed"
+  end
+
+  # Value object for sandbox status
+  SandboxStatus = Data.define(:state, :reason, :message, :last_transition_at) do
+    def running?   = state == SandboxState::RUNNING
+    def pending?   = state == SandboxState::PENDING
+    def paused?    = state == SandboxState::PAUSED
+    def failed?    = state == SandboxState::FAILED
+    def terminated? = state == SandboxState::TERMINATED
+
+    def self.from_hash(h)
+      return nil unless h
+      new(
+        state:              h["state"],
+        reason:             h["reason"],
+        message:            h["message"],
+        last_transition_at: h["lastTransitionAt"] ? Time.parse(h["lastTransitionAt"]) : nil
+      )
+    end
+  end
+
+  # Value object for a Sandbox resource
+  Sandbox = Data.define(:id, :status, :image_uri, :entrypoint, :metadata, :expires_at, :created_at) do
+    def self.from_hash(h)
+      new(
+        id:         h["id"],
+        status:     SandboxStatus.from_hash(h["status"]),
+        image_uri:  h.dig("image", "uri"),
+        entrypoint: h["entrypoint"] || [],
+        metadata:   h["metadata"] || {},
+        expires_at: h["expiresAt"] ? Time.parse(h["expiresAt"]) : nil,
+        created_at: h["createdAt"] ? Time.parse(h["createdAt"]) : nil
+      )
+    end
+  end
+
+  # Value object for an Endpoint
+  Endpoint = Data.define(:endpoint, :headers) do
+    def self.from_hash(h)
+      new(endpoint: h["endpoint"], headers: h["headers"] || {})
+    end
+
+    def url = endpoint.start_with?("http") ? endpoint : "http://#{endpoint}"
+  end
+
+  # Value object for pagination
+  PaginationInfo = Data.define(:page, :page_size, :total_items, :total_pages, :has_next_page) do
+    def self.from_hash(h)
+      new(
+        page:          h["page"],
+        page_size:     h["pageSize"],
+        total_items:   h["totalItems"],
+        total_pages:   h["totalPages"],
+        has_next_page: h["hasNextPage"]
+      )
+    end
+  end
+
+  # Value object for list response
+  SandboxList = Data.define(:items, :pagination) do
+    def self.from_hash(h)
+      new(
+        items:      (h["items"] || []).map { Sandbox.from_hash(_1) },
+        pagination: PaginationInfo.from_hash(h["pagination"])
+      )
+    end
+  end
+
+  # Value object for pool capacity
+  PoolCapacitySpec = Data.define(:buffer_max, :buffer_min, :pool_max, :pool_min) do
+    def self.from_hash(h)
+      new(
+        buffer_max: h["bufferMax"],
+        buffer_min: h["bufferMin"],
+        pool_max:   h["poolMax"],
+        pool_min:   h["poolMin"]
+      )
+    end
+
+    def to_api_hash
+      { "bufferMax" => buffer_max, "bufferMin" => buffer_min, "poolMax" => pool_max, "poolMin" => pool_min }
+    end
+  end
+
+  # Value object for a Pool resource
+  Pool = Data.define(:name, :capacity_spec, :status, :created_at) do
+    def self.from_hash(h)
+      new(
+        name:          h["name"],
+        capacity_spec: PoolCapacitySpec.from_hash(h["capacitySpec"]),
+        status:        h["status"],
+        created_at:    h["createdAt"] ? Time.parse(h["createdAt"]) : nil
+      )
+    end
+  end
+
+  # Utility helpers for processing sandbox output.
+  module LogUtils
+    # Strip Docker-style RFC3339 nanosecond timestamp prefixes from each log line.
+    #
+    #   "2026-04-29T13:37:33.993340334Z 1024\n"  =>  "1024\n"
+    #   "no-timestamp\n"                         =>  "no-timestamp\n"
+    #
+    TIMESTAMP_RE = /\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z /.freeze
+
+    def self.strip_timestamps(raw)
+      raw.to_s.lines.map { |line| line.sub(TIMESTAMP_RE, "") }.join
+    end
+  end
+end

data/lib/open_sandbox/pools.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module OpenSandbox
+  # Manages pre-warmed resource pools for reduced sandbox cold-start latency.
+  class Pools
+    def initialize(http)
+      @http = http
+    end
+
+    # List all pools.
+    #
+    # @return [Array<Pool>]
+    def list
+      data = @http.get("/v1/pools")
+      (data["items"] || []).map { Pool.from_hash(_1) }
+    end
+
+    # Get a pool by name.
+    #
+    # @param pool_name [String]
+    # @return [Pool]
+    # @raise [NotFoundError]
+    def get(pool_name)
+      Pool.from_hash(@http.get("/v1/pools/#{pool_name}"))
+    end
+
+    # Create a new pre-warmed pool.
+    #
+    # @param name [String] unique pool name (lowercase alphanumeric + hyphens)
+    # @param template [Hash] Kubernetes PodTemplateSpec
+    # @param capacity_spec [PoolCapacitySpec, Hash] capacity configuration
+    # @return [Pool]
+    def create(name:, template:, capacity_spec:)
+      spec = capacity_spec.is_a?(PoolCapacitySpec) ? capacity_spec.to_api_hash : capacity_spec.transform_keys(&:to_s).then do |h|
+        {
+          "bufferMax" => h["buffer_max"] || h["bufferMax"],
+          "bufferMin" => h["buffer_min"] || h["bufferMin"],
+          "poolMax"   => h["pool_max"]   || h["poolMax"],
+          "poolMin"   => h["pool_min"]   || h["poolMin"]
+        }
+      end
+
+      body = { "name" => name.to_s, "template" => template, "capacitySpec" => spec }
+      Pool.from_hash(@http.post("/v1/pools", body: body))
+    end
+
+    # Update pool capacity configuration.
+    #
+    # @param pool_name [String]
+    # @param capacity_spec [PoolCapacitySpec, Hash]
+    # @return [Pool]
+    def update(pool_name, capacity_spec:)
+      spec = capacity_spec.is_a?(PoolCapacitySpec) ? capacity_spec.to_api_hash : capacity_spec
+      body = { "capacitySpec" => spec }
+      Pool.from_hash(@http.put("/v1/pools/#{pool_name}", body: body))
+    end
+
+    # Delete a pool.
+    #
+    # @param pool_name [String]
+    # @return [nil]
+    def delete(pool_name)
+      @http.delete("/v1/pools/#{pool_name}")
+    end
+  end
+end

data/lib/open_sandbox/runner.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module OpenSandbox
+  # Runner: execute code or commands in an ephemeral sandbox and collect output.
+  #
+  # Opinionated wrapper around OpenSandbox::Client for short-lived,
+  # fire-and-collect code execution. The sandbox is always cleaned up after use.
+  #
+  # == Examples
+  #   result = SandboxRunnerService.run_python(<<~CODE)
+  #     import math
+  #     print(math.sqrt(144))
+  #   CODE
+  #   result.output    # => "12.0\n"
+  #
+  #   result = OpenSandbox::Runner.python("print(2 ** 10)")
+  #   result.output    # => "1024\n"
+  #   result.success?  # => true
+  #   result.elapsed   # => 3.14
+  #
+  #   result = OpenSandbox::Runner.node("console.log('hi')")
+  #   result = OpenSandbox::Runner.shell("echo $((6 * 7))")
+  #
+  #   result = OpenSandbox::Runner.call(
+  #     image:   "ubuntu:24.04",
+  #     command: ["bash", "-c", "ls /"],
+  #     timeout: 60
+  #   )
+  #
+  class Runner
+    Result = Data.define(:success, :output, :sandbox_id, :elapsed) do
+      alias_method :success?, :success
+      def failure? = !success
+    end
+
+    DEFAULT_LIMITS  = { "cpu" => "500m", "memory" => "256Mi" }.freeze
+    STARTUP_TIMEOUT = 60  # seconds to wait for sandbox to reach Running
+
+    # ── Convenience shortcuts ─────────────────────────────────────────────
+
+    def self.python(code, version: "3.11", timeout: nil)
+      call(image: "python:#{version}-slim", command: ["python", "-c", code], timeout: timeout)
+    end
+
+    def self.node(code, version: "20", timeout: nil)
+      call(image: "node:#{version}-slim", command: ["node", "-e", code], timeout: timeout)
+    end
+
+    def self.shell(command, timeout: nil)
+      call(image: "ubuntu:24.04", command: ["bash", "-c", command], timeout: timeout)
+    end
+
+    def self.call(**kwargs)
+      new(**kwargs).call
+    end
+
+    # ── Instance ──────────────────────────────────────────────────────────
+
+    def initialize(
+      image:,
+      command:,
+      env:             {},
+      timeout:         nil,
+      resource_limits: DEFAULT_LIMITS,
+      metadata:        {}
+    )
+      @image           = image
+      @command         = command
+      @env             = env
+      @timeout         = timeout || OpenSandbox.configuration.timeout
+      @resource_limits = resource_limits
+      @metadata        = metadata
+      @client          = OpenSandbox.client
+    end
+
+    def call
+      started_at = Time.now
+      sandbox_id = nil
+
+      sandbox    = @client.sandboxes.create(
+        image:           @image,
+        entrypoint:      @command,
+        env:             @env,
+        timeout:         @timeout,
+        resource_limits: @resource_limits,
+        metadata:        @metadata
+      )
+      sandbox_id = sandbox.id
+
+      @client.sandboxes.wait_until(
+        sandbox_id,
+        target_state: SandboxState::TERMINATED,
+        timeout:      STARTUP_TIMEOUT + @timeout
+      ) { |s| OpenSandbox.logger.debug("[Runner] #{sandbox_id} state=#{s.status.state}") }
+
+      raw    = @client.sandboxes.logs(sandbox_id, tail: 1000)
+      output = LogUtils.strip_timestamps(raw.to_s)
+
+      Result.new(success: true, output: output, sandbox_id: sandbox_id, elapsed: Time.now - started_at)
+    rescue OpenSandbox::Error => e
+      OpenSandbox.logger.error("[Runner] #{sandbox_id}: #{e.message}")
+      Result.new(success: false, output: "Error: #{e.message}", sandbox_id: sandbox_id, elapsed: Time.now - started_at)
+    ensure
+      begin
+        @client.sandboxes.delete(sandbox_id) if sandbox_id
+      rescue OpenSandbox::Error => e
+        OpenSandbox.logger.warn("[Runner] cleanup failed for #{sandbox_id}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/open_sandbox/sandboxes.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module OpenSandbox
+  # Manages sandbox lifecycle operations.
+  #
+  # All methods return typed value objects (Sandbox, Endpoint, etc.)
+  # or raise OpenSandbox::Error subclasses on failure.
+  class Sandboxes
+    def initialize(http, logger: Logger.new(nil))
+      @http   = http
+      @logger = logger
+    end
+
+    # List all sandboxes with optional filters.
+    #
+    # @param page [Integer] page number (default 1)
+    # @param page_size [Integer] items per page (default 20)
+    # @param metadata [Hash] filter by metadata key-value pairs
+    # @return [SandboxList]
+    def list(page: 1, page_size: 20, metadata: {})
+      query = { page: page, pageSize: page_size }
+      metadata.each { |k, v| query["metadata.#{k}"] = v }
+      data = @http.get("/v1/sandboxes", query: query)
+      SandboxList.from_hash(data)
+    end
+
+    # Get a sandbox by ID.
+    #
+    # @param sandbox_id [String]
+    # @return [Sandbox]
+    # @raise [NotFoundError]
+    def get(sandbox_id)
+      data = @http.get("/v1/sandboxes/#{sandbox_id}")
+      Sandbox.from_hash(data)
+    end
+
+    # Create a new sandbox.
+    #
+    # @param image [String] container image URI, e.g. "python:3.11"
+    # @param entrypoint [Array<String>] command to run, e.g. ["python", "/app/main.py"]
+    # @param resource_limits [Hash] CPU/memory limits, e.g. { cpu: "500m", memory: "512Mi" }
+    # @param timeout [Integer, nil] seconds before auto-terminate (min 60); nil = no auto-terminate
+    # @param env [Hash] environment variables
+    # @param metadata [Hash] custom key-value labels
+    # @param network_policy [Hash, nil] egress policy
+    # @param volumes [Array<Hash>, nil] volume mounts
+    # @param image_auth [Hash, nil] registry credentials { username:, password: }
+    # @param extensions [Hash, nil] provider-specific parameters (e.g. poolRef)
+    # @param platform [Hash, nil] { os: "linux", arch: "amd64" }
+    # @return [Sandbox]
+    def create(
+      image:,
+      entrypoint:,
+      resource_limits: { "cpu" => "500m", "memory" => "512Mi" },
+      timeout: 300,
+      env: {},
+      metadata: {},
+      network_policy: nil,
+      volumes: nil,
+      image_auth: nil,
+      extensions: nil,
+      platform: nil
+    )
+      body = {
+        image:          build_image_spec(image, image_auth),
+        entrypoint:     entrypoint,
+        resourceLimits: resource_limits.transform_keys(&:to_s),
+        env:            env.transform_keys(&:to_s)
+      }
+
+      body[:timeout]       = timeout       if timeout
+      body[:metadata]      = metadata.transform_keys(&:to_s) if metadata && !metadata.empty?
+      body[:networkPolicy] = network_policy if network_policy
+      body[:volumes]       = volumes        if volumes
+      body[:extensions]    = extensions.transform_keys(&:to_s) if extensions
+      body[:platform]      = { "os" => platform[:os], "arch" => platform[:arch] } if platform
+
+      data = @http.post("/v1/sandboxes", body: body)
+      Sandbox.from_hash(data)
+    end
+
+    # Delete (terminate) a sandbox.
+    #
+    # @param sandbox_id [String]
+    # @return [nil]
+    def delete(sandbox_id)
+      @http.delete("/v1/sandboxes/#{sandbox_id}")
+    end
+
+    # Pause a running sandbox (preserves state).
+    #
+    # @param sandbox_id [String]
+    # @return [nil]
+    def pause(sandbox_id)
+      @http.post("/v1/sandboxes/#{sandbox_id}/pause")
+    end
+
+    # Resume a paused sandbox.
+    #
+    # @param sandbox_id [String]
+    # @return [nil]
+    def resume(sandbox_id)
+      @http.post("/v1/sandboxes/#{sandbox_id}/resume")
+    end
+
+    # Renew sandbox expiration time.
+    #
+    # @param sandbox_id [String]
+    # @param expires_at [Time] new expiration time (must be in the future)
+    # @return [Time] new expiration time
+    def renew_expiration(sandbox_id, expires_at:)
+      body = { "expiresAt" => expires_at.utc.iso8601 }
+      data = @http.post("/v1/sandboxes/#{sandbox_id}/renew-expiration", body: body)
+      Time.parse(data["expiresAt"])
+    end
+
+    # Get public endpoint URL for a service port inside the sandbox.
+    #
+    # @param sandbox_id [String]
+    # @param port [Integer] port number where the service listens
+    # @param use_server_proxy [Boolean] return server-proxied URL
+    # @return [Endpoint]
+    def endpoint(sandbox_id, port:, use_server_proxy: false)
+      data = @http.get(
+        "/v1/sandboxes/#{sandbox_id}/endpoints/#{port}",
+        query: { useServerProxy: use_server_proxy }
+      )
+      Endpoint.from_hash(data)
+    end
+
+    # Proxy an HTTP request to a service running inside the sandbox.
+    #
+    # @param sandbox_id [String]
+    # @param port [Integer]
+    # @param method [Symbol] :get, :post, :put, :patch, :delete
+    # @param path [String] path within the proxied service (default "/")
+    # @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('/')}"
+
+      @http.proxy(method, proxy_path, body: body, headers: headers)
+    end
+
+    # ── Diagnostics ─────────────────────────────────────────────────────────
+
+    # Get container logs for a sandbox.
+    #
+    # @param sandbox_id [String]
+    # @param tail [Integer] number of trailing lines
+    # @param since [String, nil] duration string, e.g. "10m", "1h"
+    # @return [String]
+    def logs(sandbox_id, tail: 100, since: nil)
+      query = { tail: tail }
+      query[:since] = since if since
+      @http.get("/v1/sandboxes/#{sandbox_id}/diagnostics/logs", query: query)
+    end
+
+    # Get detailed container inspection info.
+    #
+    # @param sandbox_id [String]
+    # @return [String]
+    def inspect_container(sandbox_id)
+      @http.get("/v1/sandboxes/#{sandbox_id}/diagnostics/inspect")
+    end
+
+    # Get events for a sandbox.
+    #
+    # @param sandbox_id [String]
+    # @param limit [Integer]
+    # @return [String]
+    def events(sandbox_id, limit: 50)
+      @http.get("/v1/sandboxes/#{sandbox_id}/diagnostics/events", query: { limit: limit })
+    end
+
+    # Get combined diagnostics summary (inspect + events + logs).
+    #
+    # @param sandbox_id [String]
+    # @param tail [Integer]
+    # @param event_limit [Integer]
+    # @return [String]
+    def diagnostics(sandbox_id, tail: 50, event_limit: 20)
+      @http.get(
+        "/v1/sandboxes/#{sandbox_id}/diagnostics/summary",
+        query: { tail: tail, eventLimit: event_limit }
+      )
+    end
+
+    # ── Polling helpers ──────────────────────────────────────────────────────
+
+    # Wait until sandbox reaches a target state (or fails/terminates).
+    #
+    # @param sandbox_id [String]
+    # @param target_state [String] e.g. SandboxState::RUNNING
+    # @param timeout [Integer] max seconds to wait
+    # @param interval [Numeric] polling interval in seconds
+    # @yield [Sandbox] called after each poll (optional)
+    # @return [Sandbox] when target state reached
+    # @raise [Error] if sandbox fails or timeout exceeded
+    def wait_until(sandbox_id, target_state:, timeout: 120, interval: 2)
+      deadline = Time.now + timeout
+      loop do
+        sandbox = get(sandbox_id)
+        yield sandbox if block_given?
+
+        return sandbox if sandbox.status.state == target_state
+
+        if sandbox.status.failed? || sandbox.status.terminated?
+          raise Error, "Sandbox #{sandbox_id} entered #{sandbox.status.state} state: #{sandbox.status.message}"
+        end
+
+        raise Error, "Timed out waiting for sandbox #{sandbox_id} to reach #{target_state}" if Time.now >= deadline
+
+        sleep interval
+      end
+    end
+
+    private
+
+    def build_image_spec(image, auth)
+      spec = { "uri" => image }
+      if auth
+        spec["auth"] = { "username" => auth[:username].to_s, "password" => auth[:password].to_s }
+      end
+      spec
+    end
+  end
+end

data/lib/open_sandbox/version.rb

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

data/lib/open_sandbox.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "open_sandbox/version"
+require_relative "open_sandbox/client"
+require_relative "open_sandbox/runner"

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: open_sandbox
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Grayson Chen
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.21'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.21'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+description: A lightweight, idiomatic Ruby client for managing isolated container
+  sandboxes via the open-sandbox.ai REST API. Supports sandbox lifecycle (create,
+  pause, resume, delete), resource pools, diagnostics, HTTP proxying, and polling
+  helpers.
+email:
+- cgg5207@sina.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/generators/open_sandbox/install_generator.rb
+- lib/generators/open_sandbox/templates/initializer.rb
+- lib/open_sandbox.rb
+- lib/open_sandbox/client.rb
+- lib/open_sandbox/errors.rb
+- lib/open_sandbox/http_client.rb
+- lib/open_sandbox/models.rb
+- lib/open_sandbox/pools.rb
+- lib/open_sandbox/runner.rb
+- lib/open_sandbox/sandboxes.rb
+- lib/open_sandbox/version.rb
+homepage: https://github.com/graysonchen/open_sandbox-sdk-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/graysonchen/open_sandbox-sdk-ruby
+  source_code_uri: https://github.com/graysonchen/open_sandbox-sdk-ruby
+  changelog_uri: https://github.com/graysonchen/open_sandbox-sdk-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/graysonchen/open_sandbox-sdk-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby SDK for the open-sandbox.ai API
+test_files: []