e2b 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfc3dc31658813cd8fb30e3ad23464287d65a0c44fe604092b88af9943e6cc95
-  data.tar.gz: 944847469b79e7da14d8f347c21cbc564bc44d76ae426c4f338c020f1497ff45
+  metadata.gz: 71bb823dbcc8f1b7622aeb0ddfbb2535cab96fb26ac97409baa6d1f9a04c22be
+  data.tar.gz: b978c0e71dce188c41a679780eef5fd9c20c8cb6e71d64a2c79290d1c7920632
 SHA512:
-  metadata.gz: 479f9080d1a96b9ae2e7508f79d2ee3fdd17d82519a7a395bbcd2bc7c4864d3b99b43c29a66812ba4156c43f87751d49ccec267eb36a808118bf5bffd9cf98ce
-  data.tar.gz: ab09177f228a09b7c4c350324ab352de99d2c86ad8a8d8c25849923c3ad6b35ccb524ddbcd58f98dae7ce3a4c2920bccca57bf33cf4b91e27ec2ebfa53b0ca32
+  metadata.gz: b28d09048b6d48cd5ea1db1ed9dd505efb007c8ca4629c074dd28ca47efbe76d34a3928ae61b2346c4c5efacfc9df20b64a0dd68cff26db035e37a088bb712e2
+  data.tar.gz: f65d80825693194d3ec3b2004a5f40c050fe571ca9e0baf91700bb9bdc53cf4a346d569828996234702ee61c39917fbf100ba5c203c2baa15ce5afe6ebf17f2a

data/README.md

@@ -1,5 +1,7 @@
 # E2B Ruby SDK
 
+[![Gem Version](https://badge.fury.io/rb/e2b.svg)](https://badge.fury.io/rb/e2b)
+
 Ruby SDK for [E2B](https://e2b.dev) - secure cloud sandboxes for AI-generated code execution.
 
 Aligned with the [official E2B SDKs](https://github.com/e2b-dev/E2B) (Python/JS).
@@ -12,7 +14,10 @@ Aligned with the [official E2B SDKs](https://github.com/e2b-dev/E2B) (Python/JS)
 - PTY (pseudo-terminal) support for interactive sessions
 - Git operations (clone, push, pull, branches, status, commit, etc.)
 - Directory watching with event polling
-- Snapshot support
+- Snapshot support (create, list, delete)
+- Template builds (Dockerfile-style DSL, registry auth, build logs)
+- Sandbox metrics & logs
+- MCP gateway integration
 - Backward-compatible Client class
 
 ## Installation
@@ -79,8 +84,13 @@ sandbox.kill
 ## Configuration
 
 ```bash
-# Option 1: Environment variable (recommended)
+# Option 1: Environment variables (recommended)
 export E2B_API_KEY=your-api-key
+# Optional:
+export E2B_ACCESS_TOKEN=your-access-token  # alternative auth
+export E2B_DOMAIN=e2b.app                  # custom domain
+export E2B_API_URL=https://api.e2b.app     # custom API URL
+export E2B_DEBUG=true                      # enable debug logging
 ```
 
 ```ruby
@@ -90,8 +100,9 @@ E2B.configure do |config|
   config.domain = 'e2b.app'
 end
 
-# Option 3: Per-call
+# Option 3: Per-call (api_key or access_token)
 sandbox = E2B::Sandbox.create(template: "base", api_key: "your-key")
+sandbox = E2B::Sandbox.create(template: "base", access_token: "your-token")
 
 # Option 4: Client class (backward compatible)
 client = E2B::Client.new(api_key: "your-key")
@@ -102,12 +113,17 @@ sandbox = client.create(template: "base")
 
 ### Sandbox (class methods)
 
+> Every class method below also accepts `access_token:` (alternative to `api_key:`)
+> and `domain:` (override the default).
+
 | Method | Description |
 |--------|-------------|
-| `Sandbox.create(template:, timeout:, metadata:, envs:, api_key:)` | Create a new sandbox |
-| `Sandbox.connect(sandbox_id, timeout:, api_key:)` | Connect to existing sandbox |
-| `Sandbox.list(query:, limit:, api_key:)` | List running sandboxes |
-| `Sandbox.kill(sandbox_id, api_key:)` | Kill a sandbox by ID |
+| `Sandbox.create(template:, timeout:, metadata:, envs:, secure:, allow_internet_access:, network:, lifecycle:, auto_pause:, mcp:, api_key:, request_timeout:)` | Create a new sandbox. `lifecycle:` / `auto_pause:` control what happens at timeout (kill vs pause); `network:` configures egress rules; `request_timeout:` is the create-call HTTP timeout (default 120s). |
+| `Sandbox.connect(sandbox_id, timeout:, api_key:)` | Connect to an existing sandbox |
+| `Sandbox.list(query:, limit:, next_token:, api_key:)` | List running sandboxes (returns `SandboxPaginator`) |
+| `Sandbox.kill(sandbox_id, api_key:)` | Kill a sandbox by ID (idempotent) |
+| `Sandbox.list_snapshots(sandbox_id:, limit:, next_token:, api_key:)` | List snapshots (returns `SnapshotPaginator`) |
+| `Sandbox.delete_snapshot(snapshot_id, api_key:)` | Delete a snapshot template |
 
 ### Sandbox (instance)
 
@@ -117,30 +133,40 @@ sandbox = client.create(template: "base")
 | `sandbox.files` | Filesystem service |
 | `sandbox.pty` | PTY (terminal) service |
 | `sandbox.git` | Git operations service |
+| `sandbox.get_info` | Refresh and return sandbox info from API |
+| `sandbox.running?` | Check whether sandbox is currently running |
 | `sandbox.set_timeout(seconds)` | Extend sandbox lifetime |
-| `sandbox.get_host(port)` | Get host string for a port |
-| `sandbox.get_url(port)` | Get full URL for a port |
-| `sandbox.pause` / `sandbox.resume` | Pause/resume sandbox |
-| `sandbox.create_snapshot` | Create sandbox snapshot |
-| `sandbox.kill` | Terminate sandbox |
+| `sandbox.time_remaining` | Seconds until timeout (0 if expired/unknown) |
+| `sandbox.get_host(port)` / `sandbox.get_url(port)` | Get host string / full URL for a port |
+| `sandbox.download_url(path, user:, use_signature_expiration:)` / `sandbox.upload_url(path = nil, user:, use_signature_expiration:)` | Pre-signed file URLs (`use_signature_expiration:` overrides the default URL TTL) |
+| `sandbox.pause` / `sandbox.resume(timeout:)` | Pause/resume sandbox |
+| `sandbox.create_snapshot` | Create sandbox snapshot (returns `SnapshotInfo`) |
+| `sandbox.list_snapshots(limit:, next_token:)` | List snapshots from this sandbox |
+| `sandbox.get_metrics(start_time:, end_time:)` | CPU / memory / disk metrics |
+| `sandbox.logs(start_time:, limit:)` | Sandbox logs |
+| `sandbox.get_mcp_url` / `sandbox.get_mcp_token` | MCP gateway URL and token (when `mcp:` enabled) |
+| `sandbox.kill` | Terminate sandbox (idempotent) |
 
 ### Commands (`sandbox.commands`)
 
 | Method | Description |
 |--------|-------------|
-| `run(cmd, background:, envs:, cwd:, timeout:, on_stdout:, on_stderr:)` | Run command (returns `CommandResult` or `CommandHandle`) |
+| `run(cmd, background:, envs:, user:, cwd:, timeout:, request_timeout:, stdin:, on_stdout:, on_stderr:)` | Run command (returns `CommandResult` or `CommandHandle`). `timeout` is the command timeout (seconds, default 60); `request_timeout` is the HTTP request timeout. Pass `stdin: true` if you plan to call `send_stdin` on a background handle. |
 | `list` | List running processes |
 | `kill(pid)` | Kill a process |
 | `send_stdin(pid, data)` | Send stdin to a process |
 | `close_stdin(pid)` | Close stdin (send EOF) |
-| `connect(pid)` | Connect to running process |
+| `connect(pid, timeout:)` | Connect to a running process |
 
 ### Filesystem (`sandbox.files`)
 
+> Every filesystem method also accepts `user:` (default `"user"`, pass `"root"` for
+> root-owned paths) and `request_timeout:` (per-call HTTP timeout in seconds).
+
 | Method | Description |
 |--------|-------------|
-| `read(path)` | Read file content |
-| `write(path, data)` | Write file (via REST upload) |
+| `read(path, format:)` | Read file content (`format:` `"text"` (default), `"bytes"`, or `"stream"`) |
+| `write(path, data)` | Write file (via REST upload, returns `WriteInfo`) |
 | `write_files(files)` | Write multiple files |
 | `list(path, depth:)` | List directory (returns `EntryInfo[]`) |
 | `get_info(path)` | Get file/dir info (returns `EntryInfo`) |
@@ -154,8 +180,8 @@ sandbox = client.create(template: "base")
 
 | Method | Description |
 |--------|-------------|
-| `create(size:, cwd:, envs:)` | Create PTY session (returns `CommandHandle`) |
-| `connect(pid)` | Connect to existing PTY |
+| `create(size:, user:, cwd:, envs:)` | Create PTY session (returns `CommandHandle`) |
+| `connect(pid, timeout:)` | Connect to existing PTY (`timeout:` defaults to 60s) |
 | `send_stdin(pid, data)` | Send input to PTY |
 | `kill(pid)` | Kill PTY process |
 | `resize(pid, size)` | Resize terminal |
@@ -171,7 +197,7 @@ sandbox = client.create(template: "base")
 | `status(path)` | Get repo status (returns `GitStatus`) |
 | `branches(path)` | List branches (returns `GitBranches`) |
 | `add(path, files:, all:)` | Stage files |
-| `commit(path, message, author_name:, author_email:)` | Create commit |
+| `commit(path, message, author_name:, author_email:, allow_empty:)` | Create commit (`allow_empty: true` allows empty commits) |
 | `push(path, remote:, branch:, username:, password:)` | Push to remote |
 | `pull(path, remote:, branch:, username:, password:)` | Pull from remote |
 | `create_branch` / `checkout_branch` / `delete_branch` | Branch management |
@@ -179,7 +205,65 @@ sandbox = client.create(template: "base")
 | `reset(path, mode:, target:)` / `restore(path, paths)` | Reset/restore changes |
 | `set_config` / `get_config` | Git configuration |
 | `configure_user(name, email)` | Set user name/email |
-| `dangerously_authenticate(username, password)` | Store credentials globally |
+| `dangerously_authenticate(username, password, host:, protocol:)` | Store credentials globally (`host:` defaults to `github.com`, `protocol:` to `https`) |
+
+### Templates (`E2B::Template`)
+
+Build custom sandbox templates using a Dockerfile-style DSL, then build them
+on E2B's infrastructure.
+
+```ruby
+template = E2B::Template.new
+  .from_python_image("3.12")
+  .pip_install(["requests", "pandas"])
+  .run_cmd("apt-get update && apt-get install -y curl")
+  .copy("./app", "/app")
+  .set_workdir("/app")
+  .set_envs("MY_ENV" => "value")
+
+# Build (blocks until finished)
+build_info = E2B::Template.build(
+  template,
+  alias_name: "my-template",
+  cpu_count: 2,
+  memory_mb: 1024,
+  disk_size_mb: 2048,
+  on_build_logs: ->(entry) { puts entry.message }
+)
+
+# Or build asynchronously
+build_info = E2B::Template.build_in_background(template, alias_name: "my-template")
+status = E2B::Template.get_build_status(build_info)
+E2B::Template.wait_for_build_finish(build_info)
+
+# Use the built template
+sandbox = E2B::Sandbox.create(template: "my-template")
+```
+
+| Method | Description |
+|--------|-------------|
+| `Template.new(file_context_path:, file_ignore_patterns:)` | Start a new template definition |
+| `from_image(image, username:, password:)` | Use a custom base image (with optional registry auth) |
+| `from_debian_image` / `from_ubuntu_image` / `from_python_image` / `from_node_image` / `from_bun_image` / `from_base_image` | Convenience base-image helpers |
+| `from_aws_registry(image, ...)` / `from_gcp_registry(image, ...)` | Pull base from AWS ECR / GCP Artifact Registry |
+| `from_dockerfile(content_or_path)` | Initialize from a Dockerfile |
+| `from_template(template)` | Inherit from an existing template |
+| `copy(src, dest, ...)` / `copy_items(items)` | Copy files into the image |
+| `run_cmd(cmd, user:)` | Run a build-time command |
+| `set_workdir(path)` / `set_user(user)` / `set_envs(envs)` | Image config |
+| `pip_install` / `npm_install` / `bun_install` / `apt_install` | Package manager helpers |
+| `add_mcp_server(servers)` | Register MCP servers in the template |
+| `git_clone(url, path, branch:, depth:, user:)` | Clone repo at build time |
+| `remove(path, ...)` / `rename(src, dest, ...)` / `make_dir(path, ...)` / `make_symlink(src, dest, ...)` | Filesystem ops |
+| `set_start_cmd(cmd, ready_cmd)` / `set_ready_cmd(ready_cmd)` | Process start / readiness checks |
+| `skip_cache` | Force-rebuild the next layer |
+| `Template.build(template, name:, alias_name:, tags:, cpu_count:, memory_mb:, disk_size_mb:, skip_cache:, on_build_logs:)` | Build template (blocks) |
+| `Template.build_in_background(template, ...)` | Start a build, return `BuildInfo` |
+| `Template.get_build_status(build_info, logs_offset:)` | Poll build status |
+| `Template.wait_for_build_finish(build_info, on_build_logs:)` | Block until build completes |
+| `Template.exists(name)` / `Template.alias_exists(alias)` | Check template existence |
+| `Template.assign_tags(name, tags)` / `Template.remove_tags(name, tags)` / `Template.get_tags(template_id)` | Tag management |
+| `Template.to_dockerfile(template)` / `Template.to_json(template)` | Serialize a template definition |
 
 ## License
 

data/lib/e2b/api/http_client.rb

@@ -130,7 +130,11 @@ module E2B
 
       def parse_body(body, headers)
         if body.is_a?(String) && !body.empty?
-          content_type = headers["content-type"] rescue "unknown"
+          content_type = begin
+            headers["content-type"]
+          rescue StandardError
+            "unknown"
+          end
           if content_type&.include?("json") || body.start_with?("{", "[")
             begin
               return JSON.parse(body)

data/lib/e2b/client.rb

@@ -74,9 +74,7 @@ module E2B
       body[:envVars] = envs if envs
       body[:mcp] = mcp if mcp
       body[:network] = network if network
-      if body[:autoPause]
-        body[:autoResume] = { enabled: lifecycle[:auto_resume] }
-      end
+      body[:autoResume] = { enabled: lifecycle[:auto_resume] } if body[:autoPause]
 
       response = @http_client.post("/sandboxes", body: body, timeout: request_timeout || @config.request_timeout || 120)
       ensure_supported_envd_version!(response, @http_client)
@@ -101,7 +99,7 @@ module E2B
     def connect(sandbox_id, timeout: nil)
       timeout_seconds = timeout || ((@config.sandbox_timeout_ms || (Sandbox::DEFAULT_TIMEOUT * 1000)) / 1000).to_i
       response = @http_client.post("/sandboxes/#{sandbox_id}/connect",
-        body: { timeout: timeout_seconds })
+                                   body: { timeout: timeout_seconds })
 
       Sandbox.new(
         sandbox_data: response,
@@ -162,7 +160,7 @@ module E2B
     # @param timeout [Integer] Timeout in seconds
     def set_timeout(sandbox_id, timeout)
       @http_client.post("/sandboxes/#{sandbox_id}/timeout",
-        body: { timeout: timeout })
+                        body: { timeout: timeout })
     end
 
     # Pause a sandbox

data/lib/e2b/configuration.rb

@@ -87,8 +87,8 @@ module E2B
       sandbox_timeout_ms: DEFAULT_SANDBOX_TIMEOUT_MS,
       debug: false
     )
-      @api_key = api_key || ENV["E2B_API_KEY"]
-      @access_token = access_token || ENV["E2B_ACCESS_TOKEN"]
+      @api_key = api_key || ENV.fetch("E2B_API_KEY", nil)
+      @access_token = access_token || ENV.fetch("E2B_ACCESS_TOKEN", nil)
       @domain = domain || ENV["E2B_DOMAIN"] || DEFAULT_DOMAIN
       @debug = debug || ENV["E2B_DEBUG"]&.downcase == "true"
       @api_url = api_url || ENV["E2B_API_URL"] || self.class.default_api_url(@domain, debug: @debug)
@@ -103,10 +103,10 @@ module E2B
     #
     # @raise [ConfigurationError] If API key is missing
     def validate!
-      if (@api_key.nil? || @api_key.empty?) && (@access_token.nil? || @access_token.empty?)
-        raise ConfigurationError,
-          "E2B API key is required. Set E2B_API_KEY environment variable or pass api_key option."
-      end
+      return unless (@api_key.nil? || @api_key.empty?) && (@access_token.nil? || @access_token.empty?)
+
+      raise ConfigurationError,
+            "E2B API key is required. Set E2B_API_KEY environment variable or pass api_key option."
     end
 
     # Check if configuration is valid

data/lib/e2b/models/process_result.rb

@@ -55,21 +55,21 @@ module E2B
             next unless event.is_a?(Hash)
 
             # Handle nested event structure
-            if event["event"]
-              ev = event["event"]
-              if ev["Stdout"]
-                stdout += decode_base64_safe(ev["Stdout"]["data"])
-              elsif ev["stdout"]
-                stdout += decode_base64_safe(ev["stdout"]["data"])
-              elsif ev["Stderr"]
-                stderr += decode_base64_safe(ev["Stderr"]["data"])
-              elsif ev["stderr"]
-                stderr += decode_base64_safe(ev["stderr"]["data"])
-              elsif ev["Exit"]
-                exit_code = ev["Exit"]["exitCode"] || ev["Exit"]["exit_code"] || exit_code
-              elsif ev["exit"]
-                exit_code = ev["exit"]["exitCode"] || ev["exit"]["exit_code"] || exit_code
-              end
+            next unless event["event"]
+
+            ev = event["event"]
+            if ev["Stdout"]
+              stdout += decode_base64_safe(ev["Stdout"]["data"])
+            elsif ev["stdout"]
+              stdout += decode_base64_safe(ev["stdout"]["data"])
+            elsif ev["Stderr"]
+              stderr += decode_base64_safe(ev["Stderr"]["data"])
+            elsif ev["stderr"]
+              stderr += decode_base64_safe(ev["stderr"]["data"])
+            elsif ev["Exit"]
+              exit_code = ev["Exit"]["exitCode"] || ev["Exit"]["exit_code"] || exit_code
+            elsif ev["exit"]
+              exit_code = ev["exit"]["exitCode"] || ev["exit"]["exit_code"] || exit_code
             end
           end
         end
@@ -89,9 +89,9 @@ module E2B
 
         str = value.to_s
         if str =~ /exit status (\d+)/i
-          $1.to_i
+          ::Regexp.last_match(1).to_i
         elsif str =~ /(\d+)/
-          $1.to_i
+          ::Regexp.last_match(1).to_i
         else
           str.include?("0") ? 0 : 1
         end

data/lib/e2b/models/template_log_entry.rb

@@ -35,7 +35,7 @@ module E2B
       end
 
       def self.strip_ansi_escape_codes(message)
-        message.gsub(/\e\[[0-9;?]*[ -\/]*[@-~]/, "")
+        message.gsub(%r{\e\[[0-9;?]*[ -/]*[@-~]}, "")
       end
     end
 

data/lib/e2b/paginator.rb

@@ -34,9 +34,7 @@ module E2B
       super(limit: limit, next_token: next_token) do |limit:, next_token:|
         params = { limit: limit }
         params[:nextToken] = next_token if next_token
-        if normalized_query[:metadata]
-          params[:metadata] = self.class.encode_metadata(normalized_query[:metadata])
-        end
+        params[:metadata] = self.class.encode_metadata(normalized_query[:metadata]) if normalized_query[:metadata]
         params[:state] = normalized_query[:state] if normalized_query[:state]
 
         response = http_client.get("/v2/sandboxes", params: params, detailed: true)

data/lib/e2b/sandbox.rb

@@ -37,7 +37,7 @@ module E2B
     DEFAULT_MCP_TEMPLATE = "mcp-gateway"
 
     # MCP gateway port.
-    MCP_PORT = 50005
+    MCP_PORT = 50_005
 
     # @return [String] Unique sandbox ID
     attr_reader :sandbox_id
@@ -133,9 +133,7 @@ module E2B
         body[:envVars] = envs if envs
         body[:mcp] = mcp if mcp
         body[:network] = network if network
-        if body[:autoPause]
-          body[:autoResume] = { enabled: lifecycle[:auto_resume] }
-        end
+        body[:autoResume] = { enabled: lifecycle[:auto_resume] } if body[:autoPause]
 
         response = http_client.post("/sandboxes", body: body, timeout: request_timeout)
         ensure_supported_envd_version!(response, http_client)
@@ -165,7 +163,7 @@ module E2B
         http_client = build_http_client(**credentials, domain: domain)
 
         response = http_client.post("/sandboxes/#{sandbox_id}/connect",
-          body: { timeout: timeout || DEFAULT_TIMEOUT })
+                                    body: { timeout: timeout || DEFAULT_TIMEOUT })
 
         new(
           sandbox_data: response,
@@ -246,7 +244,6 @@ module E2B
       rescue E2B::NotFoundError
         true
       end
-
     end
 
     # -------------------------------------------------------------------
@@ -298,7 +295,7 @@ module E2B
       raise ArgumentError, "Timeout cannot exceed 24 hours (86400s)" if timeout > 86_400
 
       @http_client.post("/sandboxes/#{@sandbox_id}/timeout",
-        body: { timeout: timeout })
+                        body: { timeout: timeout })
 
       @end_at = Time.now + timeout
     end
@@ -542,9 +539,7 @@ module E2B
     end
 
     def build_file_url_query(path:, user:, operation:, use_signature_expiration:)
-      if use_signature_expiration && !@envd_access_token
-        raise ArgumentError, "Signature expiration can be used only when the sandbox is secured"
-      end
+      raise ArgumentError, "Signature expiration can be used only when the sandbox is secured" if use_signature_expiration && !@envd_access_token
 
       query = []
       query << ["path", path] if path

data/lib/e2b/sandbox_helpers.rb

@@ -26,9 +26,7 @@ module E2B
       }
 
       on_timeout = raw_lifecycle[:on_timeout] || raw_lifecycle["on_timeout"] || "kill"
-      unless %w[kill pause].include?(on_timeout)
-        raise ArgumentError, "Lifecycle on_timeout must be 'kill' or 'pause'"
-      end
+      raise ArgumentError, "Lifecycle on_timeout must be 'kill' or 'pause'" unless %w[kill pause].include?(on_timeout)
 
       auto_resume = if raw_lifecycle.key?(:auto_resume)
                       raw_lifecycle[:auto_resume]
@@ -65,18 +63,18 @@ module E2B
       end
 
       raise TemplateError,
-        "You need to update the template to use the new SDK. You can do this by running `e2b template build` in the directory with the template."
+            "You need to update the template to use the new SDK. You can do this by running `e2b template build` in the directory with the template."
     rescue ArgumentError
       nil
     end
 
     def resolve_credentials(api_key:, access_token:)
-      resolved_api_key = api_key || E2B.configuration&.api_key || ENV["E2B_API_KEY"]
-      resolved_access_token = access_token || E2B.configuration&.access_token || ENV["E2B_ACCESS_TOKEN"]
+      resolved_api_key = api_key || E2B.configuration&.api_key || ENV.fetch("E2B_API_KEY", nil)
+      resolved_access_token = access_token || E2B.configuration&.access_token || ENV.fetch("E2B_ACCESS_TOKEN", nil)
 
       unless (resolved_api_key && !resolved_api_key.empty?) || (resolved_access_token && !resolved_access_token.empty?)
         raise ConfigurationError,
-          "E2B credentials are required. Set E2B_API_KEY or E2B_ACCESS_TOKEN, or pass api_key:/access_token:."
+              "E2B credentials are required. Set E2B_API_KEY or E2B_ACCESS_TOKEN, or pass api_key:/access_token:."
       end
 
       { api_key: resolved_api_key, access_token: resolved_access_token }