daytona 0.223.0 → 0.224.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce7bf391267dee8c74a05e8ed953fc1b11d350e551f7cfe2481823b757369ca3
-  data.tar.gz: 476cc862b0e6395dc99b9a9df53c427cfb5fcdc30b984cf40a7b78d53c6dc57b
+  metadata.gz: 9073174dfdaf41ddfeeff8c273346f9802806c7e39025f7efdf07eb5aaf32395
+  data.tar.gz: 27dcffd7cbeba0eabb88148108c5467995f16abb709820511c43a17a5568d8d5
 SHA512:
-  metadata.gz: 1484338fb95baf777228e193ff8092b732d92986d06dfdf9cabeb0a01e0602afbd554e6a97dd972cfcd99094f7a3259c3282336fec2c1dc8528c2b7d468bc501
-  data.tar.gz: e9d594ace654c716d6e7635c23a3a080d9dbb5fed967ee2a7a191159b23956f302a76672cbccca3178aa1a297a8ff9750bd8edbad40c4e8777284e0a5f67cde6
+  metadata.gz: 958b391e87200ff87e0f643f3ddd66901b82d47528aaa2ec6986ea3726ac64e26474b3456a07146adb496c857daf3ca978c5a0793d954891cf350314ed0761fa
+  data.tar.gz: 381ecfdc0266799593abc3dc3aebbce9c077e41102852456c089f32e81f7992e4bad86231300378d6da5953edf78432f83d214cb288ebff0343fab755e274c25

data/README.md

@@ -30,7 +30,7 @@ Configure the SDK using [environment variables](https://www.daytona.io/docs/en/c
 
 - `DAYTONA_API_KEY`: Your Daytona [API key](https://www.daytona.io/docs/en/api-keys/)
 - `DAYTONA_API_URL`: The Daytona [API URL](https://www.daytona.io/docs/en/tools/api/)
-- `DAYTONA_TARGET`: Your target [region](https://www.daytona.io/docs/en/regions/) environment (e.g. `us`, `eu`)
+- `DAYTONA_TARGET`: Default [region](https://www.daytona.io/docs/en/regions/) for sandboxes and snapshots (e.g. `us`, `eu`); a per-call `target:` / `region_id:` overrides it
 
 ```ruby
 require 'daytona'
@@ -62,6 +62,20 @@ sandbox = daytona.create
 
 Daytona provides [examples](https://www.daytona.io/docs/en/getting-started/#examples) and [guides](https://www.daytona.io/docs/en/guides/) for common sandbox operations, best practices, and a wide range of topics, from basic usage to advanced topics, showcasing various types of integrations between Daytona and other tools.
 
+### Create a sandbox or snapshot in a specific region
+
+Pass `target:` in the sandbox create params, or `region_id:` in the snapshot create params, to choose the [region](https://www.daytona.io/docs/en/regions/) for that call. The region is resolved per call: the per-call value, then the client-level `target` (or `DAYTONA_TARGET`), then the organization's default region.
+
+```ruby
+require 'daytona'
+
+daytona = Daytona::Daytona.new
+sandbox = daytona.create(Daytona::CreateSandboxFromSnapshotParams.new(target: 'eu'))
+snapshot = daytona.snapshot.create(
+  Daytona::CreateSnapshotParams.new(name: 'my-snapshot', image: 'python:3.12', region_id: 'eu')
+)
+```
+
 ### Create a sandbox with custom resources
 
 Create a sandbox with [custom resources](https://www.daytona.io/docs/en/sandboxes/#resources) (CPU, memory, disk).

data/lib/daytona/common/daytona.rb

@@ -86,6 +86,11 @@ module Daytona
     #   ephemeral (auto_delete_interval=0) and cannot themselves be linked to another Sandbox.
     attr_accessor :linked_sandbox
 
+    # @return [String, nil] Target (region) where the Sandbox is created. Overrides the client-level
+    #   target for this call. If omitted, uses the client-level target when set; otherwise the
+    #   organization's default region.
+    attr_accessor :target
+
     # Initialize CreateSandboxBaseParams
     #
     # @param language [Symbol, nil] Programming language for the Sandbox
@@ -118,6 +123,8 @@ module Daytona
     # @param spot [Boolean, nil] GPU-only. Whether the Sandbox may be instantly terminated to free GPU
     #   capacity for an on-demand GPU Sandbox
     # @param linked_sandbox [String, nil] ID or name of an existing Sandbox to link the new Sandbox to
+    # @param target [String, nil] Target (region) where the Sandbox is created. Overrides the client-level
+    #   target for this call.
     def initialize( # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
       language: nil,
       os_user: nil,
@@ -141,7 +148,8 @@ module Daytona
       otel_endpoint_override: nil,
       ephemeral: nil,
       spot: nil,
-      linked_sandbox: nil
+      linked_sandbox: nil,
+      target: nil
     )
       @language = language
       @os_user = os_user
@@ -166,6 +174,7 @@ module Daytona
       @ephemeral = ephemeral
       @spot = spot
       @linked_sandbox = linked_sandbox
+      @target = target
 
       # Handle ephemeral and auto_delete_interval conflict
       handle_ephemeral_auto_delete_conflict
@@ -198,7 +207,8 @@ module Daytona
         otel_endpoint_override:,
         ephemeral:,
         spot:,
-        linked_sandbox:
+        linked_sandbox:,
+        target:
       }.compact
     end
 

data/lib/daytona/common/snapshot.rb

@@ -30,7 +30,8 @@ module Daytona
     # @param image [String, Daytona::Image] Image of the snapshot
     # @param resources [Daytona::Resources, nil] Resources of the snapshot
     # @param entrypoint [Array<String>, nil] Entrypoint of the snapshot
-    # @param region_id [String, nil] ID of the region where the snapshot will be available
+    # @param region_id [String, nil] ID of the region where the snapshot will be available. If omitted, uses
+    #   the client-level target when set; otherwise the organization's default region.
     # @param sandbox_class [DaytonaApiClient::SandboxClass, nil] Target sandbox class
     def initialize(name:, image:, resources: nil, entrypoint: nil, region_id: nil, sandbox_class: nil)
       @name = name

data/lib/daytona/config.rb

@@ -77,7 +77,8 @@ module Daytona
     # @return [String, nil] Daytona API URL
     attr_accessor :organization_id
 
-    # Target environment for sandboxes
+    # Default region for Sandboxes and Snapshots. A per-call `target:` (Sandbox create params) or
+    # `region_id:` (Snapshot create params) overrides it.
     #
     # @return [String, nil] Daytona target
     attr_accessor :target
@@ -108,7 +109,8 @@ module Daytona
     # @param jwt_token [String, nil] Daytona JWT token. Defaults to ENV['DAYTONA_JWT_TOKEN'].
     # @param api_url [String, nil] Daytona API URL. Defaults to ENV['DAYTONA_API_URL'] or Daytona::Config::API_URL.
     # @param organization_id [String, nil] Daytona organization ID. Defaults to ENV['DAYTONA_ORGANIZATION_ID'].
-    # @param target [String, nil] Daytona target. Defaults to ENV['DAYTONA_TARGET'].
+    # @param target [String, nil] Default region for Sandboxes and Snapshots; a per-call `target:` / `region_id:`
+    #   overrides it. Defaults to ENV['DAYTONA_TARGET'].
     # @param otel_enabled [Boolean, nil] Enable OpenTelemetry tracing for SDK operations.
     # @param use_deprecated_polling [Boolean, nil] Observe sandbox state by legacy polling instead of
     #   WebSocket event streaming. Defaults to false (event streaming). Can also be enabled via the

data/lib/daytona/daytona.rb

@@ -286,7 +286,7 @@ module Daytona
         env: params.env_vars || {},
         labels: labels,
         public: params.public,
-        target: config.target,
+        target: params.target.to_s.empty? ? config.target : params.target,
         auto_stop_interval: params.auto_stop_interval,
         auto_pause_interval: params.auto_pause_interval,
         auto_archive_interval: params.auto_archive_interval,

data/lib/daytona/process.rb

@@ -40,6 +40,20 @@ module Daytona
 
     # Execute a shell command in the Sandbox
     #
+    # The command is run by the first available of zsh, bash or sh in the sandbox, which is zsh
+    # in the default snapshots. Quote arguments that contain glob characters, for example
+    # `pip install -e '.[test]'`, or wrap bash-specific scripts in `bash -c '...'`.
+    #
+    # The call returns when the command finishes. To start a long-running process such as a
+    # server, run it in the background with its output redirected, e.g.
+    # `python3 -m http.server 8000 > server.log 2>&1 &`, or use a session with `run_async: true`
+    # (see {#execute_session_command}). A background process that keeps the command's output open
+    # (`cmd &` without a redirect) can block the call until that process exits.
+    #
+    # Tools in the sandbox may report the host's CPU count and memory (for example `nproc` or
+    # `Etc.nprocessors`) rather than the sandbox's own limits. Size worker pools from the
+    # sandbox's cpu and memory instead, e.g. `pytest -n 2` rather than `pytest -n auto`.
+    #
     # @param command [String] Shell command to execute
     # @param cwd [String, nil] Working directory for command execution. If not specified, uses the sandbox working directory
     # @param env [Hash<String, String>, nil] Environment variables to set for the command
@@ -48,15 +62,18 @@ module Daytona
     #
     # @example
     #   # Simple command
-    #   response = sandbox.process.exec("echo 'Hello'")
+    #   response = sandbox.process.exec(command: "echo 'Hello'")
     #   puts response.artifacts.stdout
     #   => "Hello\n"
     #
     #   # Command with working directory
-    #   result = sandbox.process.exec("ls", cwd: "workspace/src")
+    #   result = sandbox.process.exec(command: "ls", cwd: "workspace/src")
     #
     #   # Command with timeout
-    #   result = sandbox.process.exec("sleep 10", timeout: 5)
+    #   result = sandbox.process.exec(command: "sleep 10", timeout: 5)
+    #
+    #   # Start a server in the background
+    #   sandbox.process.exec(command: "python3 -m http.server 8000 > server.log 2>&1 &")
     def exec(command:, cwd: nil, env: nil, timeout: nil)
       envs = env&.empty? ? nil : env
 

data/lib/daytona/sandbox.rb

@@ -364,6 +364,21 @@ module Daytona
       process_response(data)
     end
 
+    # Sets whether the Sandbox's preview URLs are publicly accessible.
+    # When public, preview URLs (see #preview_url) can be opened without a preview token or API key.
+    # When private, every preview request must authenticate.
+    #
+    # @param is_public [Boolean]
+    # @return [Boolean]
+    # @raise [Daytona::Sdk::Error]
+    #
+    # @example
+    #   sandbox.public = true
+    def public=(is_public)
+      sandbox_api.update_public_status(id, is_public)
+      @public = is_public
+    end
+
     # Sets the auto-stop interval for the Sandbox.
     # The Sandbox will automatically stop after being idle (no new events) for the specified interval.
     # Events include any state changes or interactions with the Sandbox through the SDK.
@@ -555,8 +570,21 @@ module Daytona
     # it will be opened automatically. For private sandboxes, a token is included to grant access
     # to the URL.
     #
+    # For a private sandbox, requests to the URL must authenticate, otherwise they are answered
+    # with 401 Unauthorized. Send the returned token in the X-Daytona-Preview-Token header, or
+    # send your Daytona API key as "Authorization: Bearer <api key>". To get a URL that works
+    # without extra headers (for example to open it in a browser or share it), use
+    # {#create_signed_preview_url} instead. Public sandboxes need no credentials.
+    #
     # @param port [Integer]
     # @return [DaytonaApiClient::PortPreviewUrl]
+    #
+    # @example
+    #   preview = sandbox.preview_url(3000)
+    #   uri = URI(preview.url)
+    #   request = Net::HTTP::Get.new(uri)
+    #   request['X-Daytona-Preview-Token'] = preview.token
+    #   response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
     def preview_url(port)
       sandbox_api.get_port_preview_url(id, port)
     end
@@ -633,9 +661,14 @@ module Daytona
 
     # Creates a signed preview URL for the sandbox at the specified port.
     #
+    # The access token is embedded in the returned URL, so it can be used without any headers,
+    # for example in a browser or by another service. The URL stops working when it expires or
+    # when it is expired with {#expire_signed_preview_url}.
+    #
     # @param port [Integer] The port to open the preview link on
     # @param expires_in_seconds [Integer, nil] The number of seconds the signed preview URL
-    #   will be valid for. Defaults to 60 seconds.
+    #   will be valid for. Defaults to 60 seconds; set a longer value for links that need to
+    #   stay usable, e.g. 3600 for one hour.
     # @return [DaytonaApiClient::SignedPortPreviewUrl] The signed preview URL response object
     #
     # @example
@@ -951,7 +984,7 @@ module Daytona
       end
     end
 
-    with_events :archive, :auto_archive_interval=, :auto_delete_interval=, :auto_stop_interval=,
+    with_events :archive, :auto_archive_interval=, :auto_delete_interval=, :auto_stop_interval=, :public=,
                 :create_ssh_access, :delete, :get_user_home_dir, :get_work_dir, :labels=,
                 :preview_url, :create_signed_preview_url, :expire_signed_preview_url,
                 :refresh, :refresh_activity, :revoke_ssh_access, :start, :recover, :stop,
@@ -960,7 +993,7 @@ module Daytona
                 :fork, :create_snapshot, :pause
 
     instrument :archive, :auto_archive_interval=, :auto_delete_interval=, :auto_pause_interval=, :auto_stop_interval=,
-               :ttl_minutes=,
+               :ttl_minutes=, :public=,
                :update_network_settings, :update_secrets, :update_env,
                :create_ssh_access, :delete, :get_user_home_dir, :get_work_dir, :get_metrics, :get_metrics_latest,
                :labels=,

data/lib/daytona/sdk/version.rb

@@ -5,6 +5,6 @@
 
 module Daytona
   module Sdk
-    VERSION = '0.223.0'
+    VERSION = '0.224.0'
   end
 end

data/lib/daytona/snapshot_service.rb

@@ -117,7 +117,7 @@ module Daytona
         create_snapshot_req.disk = params.resources.disk
       end
 
-      create_snapshot_req.region_id = params.region_id || @default_region_id
+      create_snapshot_req.region_id = params.region_id.to_s.empty? ? @default_region_id : params.region_id
       create_snapshot_req.sandbox_class = params.sandbox_class
 
       snapshot = snapshots_api.create_snapshot(create_snapshot_req)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: daytona
 version: !ruby/object:Gem::Version
-  version: 0.223.0
+  version: 0.224.0
 platform: ruby
 authors:
 - Daytona Platforms Inc.
@@ -91,42 +91,42 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.223.0
+        version: 0.224.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.223.0
+        version: 0.224.0
 - !ruby/object:Gem::Dependency
   name: daytona_api_client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.223.0
+        version: 0.224.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.223.0
+        version: 0.224.0
 - !ruby/object:Gem::Dependency
   name: daytona_toolbox_api_client
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.223.0
+        version: 0.224.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.223.0
+        version: 0.224.0
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement