feat(sandboxes): add Ruby session and execution facade

Steepfile

@@ -169,3 +169,16 @@ target :consumers do
   library 'tempfile'
   configure_code_diagnostics Steep::Diagnostic::Ruby.all_error
 end
+
+target :sandboxes do
+  signature 'sig', 'sig_dev'
+  check 'lib/volcano/sandbox_models.rb'
+  check 'lib/volcano/sandbox_request.rb'
+  check 'lib/volcano/sandbox_response.rb'
+  check 'lib/volcano/sandboxes.rb'
+  check 'lib/volcano/sandbox_session.rb'
+  check 'lib/volcano/sandbox_files.rb'
+  library 'base64'
+  library 'securerandom'
+  configure_code_diagnostics Steep::Diagnostic::Ruby.all_error
+end

Steepfile.transport

@@ -5,6 +5,7 @@ target :client_transport do
   ignore_signature 'sig/client.rbs'
   check 'lib/volcano/client.rb'
   check 'lib/volcano/generated_transport.rb'
+  check 'lib/volcano/generated_transport_sandbox.rb'
   check 'lib/volcano/generated_transport_anonymous.rb'
   check 'lib/volcano/generated_transport_auth.rb'
   check 'lib/volcano/generated_transport_confirmation.rb'

docs/README.md

@@ -129,3 +129,5 @@ See [Authentication](./authentication.md) for account, session, email, and OAuth
 See [Functions](./functions.md) for standard invocation, durable execution clients, and error handling.
 
 See [Versions and compatibility](./versions.md) for runtime support, upgrades, and restoring a tested dependency set.
+
+- [Sandboxes](sandboxes.md): isolated commands, sessions, files, and HTTP access.

docs/sandboxes.md

@@ -0,0 +1,86 @@
+---
+title: Sandboxes
+description: Run isolated commands and manage sessions, files, and HTTP services from Ruby.
+---
+
+Run a command from trusted backend code in an environment with Sandbox access enabled:
+
+```ruby
+require 'volcano'
+require 'securerandom'
+
+client = Volcano::Client.new(
+  anon_key: ENV.fetch('VOLCANO_ANON_KEY'),
+  service_key: ENV.fetch('VOLCANO_SERVICE_KEY'),
+  api_url: ENV.fetch('VOLCANO_API_URL', 'https://api.volcano.dev')
+)
+project_id = ENV.fetch('VOLCANO_PROJECT_ID')
+request_id = SecureRandom.uuid
+result = client.sandboxes.exec(
+  project_id, 'python -c "print(42)"',
+  region: 'aws-us-east-1', preset: 'python3.12', request_id: request_id
+)
+puts result.stdout
+```
+
+Keep the same `request_id` when retrying an uncertain create or execution. A new
+ID represents a new operation. The SDK does not replay commands after transport failures. A rejected user token
+is refreshed once; the retry preserves the request ID.
+Nonzero exits and timeouts are result fields, not API exceptions. API failures
+raise typed `Volcano::Error` exceptions with `status`, `code`, and `retry_after`
+when supplied by the server.
+
+## Keep a session
+
+```ruby
+client.sandboxes.create(
+  project_id, region: 'aws-us-east-1', preset: 'python3.12', max_duration_seconds: 300
+).use do |session|
+  60.times do
+    break if session.refresh.state == 'running'
+    sleep 1
+  end
+  raise 'Sandbox did not become ready' unless session.state == 'running'
+
+  bytes = (0..255).to_a.pack('C*')
+  session.files.write('/tmp/input.bin', bytes)
+  raise 'File changed' unless session.files.read('/tmp/input.bin') == bytes
+  puts session.exec('wc -c /tmp/input.bin').stdout
+end
+```
+
+Creation, suspension, resumption, and termination are asynchronous. Use `refresh`
+to observe state. `use` requests termination when its block exits, including on
+exceptions. If cleanup also fails, the original block exception is preserved.
+It does not wait for termination to complete. Use `get(session_id)`
+to reconnect, then `suspend`, `resume`, or `terminate` as needed. Files preserve
+binary `String` content. Writes accept at most 8 MiB.
+
+## Access a background HTTP service
+
+Inside a running session, detach the service and redirect its streams:
+
+```ruby
+session.exec('nohup python -m http.server 8080 --bind 0.0.0.0 >/tmp/http.log 2>&1 </dev/null &')
+access = session.access(8080)
+# Send access.token in X-Volcano-Sandbox-Token when requesting access.url.
+```
+
+The process lasts until it exits or its session ends. Credentials are scoped to
+this session and port and expire at `access.expires_at`. Do not log the token or
+put it in URLs. See [Sandbox HTTP access](/platform/guides/sandboxes).
+
+## Select presets and authorize users
+
+`client.sandboxes.presets` lists available presets and regions. Supply exactly one
+of `preset` or a saved template's `sandbox_id`. Omit `memory_mb` to preserve that
+template's configured memory.
+
+Only trusted backend code should call
+`client.sandboxes.grant(session_id, auth_user_id, expires_at: expiry)` or
+`client.sandboxes.revoke(session_id, auth_user_id)`. Project users can access only
+sessions explicitly granted to them; they cannot create or manage sessions.
+Service keys stay on the backend. Anonymous keys alone cannot use this facade.
+
+When both credentials are configured, management operations use the service key.
+Granted session reads, commands, files, and HTTP access use the signed-in user.

lib/volcano.rb

@@ -64,10 +64,17 @@
 require_relative 'volcano/locks'
 require_relative 'volcano/realtime/protocol'
 require_relative 'volcano/realtime'
+require_relative 'volcano/sandbox_models'
+require_relative 'volcano/sandbox_request'
+require_relative 'volcano/sandbox_response'
+require_relative 'volcano/sandbox_files'
+require_relative 'volcano/sandbox_session'
+require_relative 'volcano/sandboxes'
 require_relative 'volcano/client'
 
 # Public namespace for the Volcano Ruby SDK.
 module Volcano
+  private_constant :SandboxRequest, :SandboxRequests, :SandboxResponse
   private_constant :AuthRefresh, :AuthSignOut, :AuthProfile, :AuthProfileFields, :AuthUpdateUser, :AuthEmailChange,
                    :AuthSessions, :AuthSessionConstruction,
                    :GeneratedTransport, :LockAutoRenewal, :LockLeaseClock, :LockRenewer,

lib/volcano/client.rb

@@ -16,9 +16,9 @@ def session_request
     end
     private_constant :SessionToken
 
-    attr_reader :auth, :functions, :durable, :logs, :storage, :locks, :realtime
+    attr_reader :sandboxes, :auth, :functions, :durable, :logs, :storage, :locks, :realtime
 
-    # @dynamic auth, functions, durable, logs, storage, locks, realtime
+    # @dynamic sandboxes, auth, functions, durable, logs, storage, locks, realtime
 
     def initialize( # rubocop:disable Metrics/ParameterLists -- Preserve typed constructor keywords.
       anon_key:,
@@ -122,6 +122,7 @@ def initialize_facades(socket_factory, reconnect_delay)
       @logs = Logs.new(self, @transport)
       @storage = Storage.new(self, @transport, api_url: @api_url, anon_key: @anon_key)
       @locks = Locks.new(self, @transport)
+      @sandboxes = Sandboxes.new(self, @transport)
       @realtime = Realtime.new(
         self,
         api_url: @api_url,

lib/volcano/generated/.openapi-generator/FILES

@@ -25,9 +25,11 @@ lib/volcano-generated/api/locks_api.rb
 lib/volcano-generated/api/logs_api.rb
 lib/volcano-generated/api/o_auth_authentication_api.rb
 lib/volcano-generated/api/o_auth_configuration_api.rb
+lib/volcano-generated/api/project_access_tokens_api.rb
 lib/volcano-generated/api/project_imports_api.rb
 lib/volcano-generated/api/projects_api.rb
 lib/volcano-generated/api/realtime_api.rb
+lib/volcano-generated/api/sandboxes_api.rb
 lib/volcano-generated/api/service_keys_api.rb
 lib/volcano-generated/api/storage_admin_api.rb
 lib/volcano-generated/api/storage_buckets_api.rb
@@ -99,6 +101,11 @@ lib/volcano-generated/models/ban_auth_user_request.rb
 lib/volcano-generated/models/ban_user_response.rb
 lib/volcano-generated/models/batch_function_deploy_failure.rb
 lib/volcano-generated/models/batch_function_deploy_response.rb
+lib/volcano-generated/models/call_mcp200_response.rb
+lib/volcano-generated/models/call_mcp200_response_error.rb
+lib/volcano-generated/models/call_mcp200_response_id.rb
+lib/volcano-generated/models/call_mcp_request.rb
+lib/volcano-generated/models/call_mcp_request_id.rb
 lib/volcano-generated/models/call_o_auth_provider_api200_response.rb
 lib/volcano-generated/models/call_o_auth_provider_api_request.rb
 lib/volcano-generated/models/complete_upload_session_response.rb
@@ -112,15 +119,20 @@ lib/volcano-generated/models/create_database_request.rb
 lib/volcano-generated/models/create_database_restore_request.rb
 lib/volcano-generated/models/create_email_template_request.rb
 lib/volcano-generated/models/create_frontend_custom_domain_request.rb
+lib/volcano-generated/models/create_frontend_function_route_request.rb
 lib/volcano-generated/models/create_function_scheduler_request.rb
 lib/volcano-generated/models/create_o_auth_config_request.rb
+lib/volcano-generated/models/create_project_access_token_request.rb
 lib/volcano-generated/models/create_project_request.rb
+lib/volcano-generated/models/create_sandbox_session_request.rb
+lib/volcano-generated/models/create_sandbox_template_request.rb
 lib/volcano-generated/models/create_service_key_request.rb
 lib/volcano-generated/models/create_storage_bucket_request.rb
 lib/volcano-generated/models/create_storage_policy_request.rb
 lib/volcano-generated/models/create_upload_session_request.rb
 lib/volcano-generated/models/create_upload_session_response.rb
 lib/volcano-generated/models/create_variable_request.rb
+lib/volcano-generated/models/created_project_access_token.rb
 lib/volcano-generated/models/database.rb
 lib/volcano-generated/models/database_backup.rb
 lib/volcano-generated/models/database_backup_list.rb
@@ -166,6 +178,8 @@ lib/volcano-generated/models/frontend_custom_domain_tls_config.rb
 lib/volcano-generated/models/frontend_deployment.rb
 lib/volcano-generated/models/frontend_domain_routing_record.rb
 lib/volcano-generated/models/frontend_domain_verification_record.rb
+lib/volcano-generated/models/frontend_function_route.rb
+lib/volcano-generated/models/frontend_function_route_list.rb
 lib/volcano-generated/models/frontend_usage_daily_entry.rb
 lib/volcano-generated/models/frontend_usage_data.rb
 lib/volcano-generated/models/frontend_usage_history_response.rb
@@ -240,6 +254,7 @@ lib/volcano-generated/models/paginated_frontend_deployments.rb
 lib/volcano-generated/models/paginated_frontends.rb
 lib/volcano-generated/models/paginated_function_deployments.rb
 lib/volcano-generated/models/paginated_functions.rb
+lib/volcano-generated/models/paginated_project_access_tokens.rb
 lib/volcano-generated/models/paginated_project_custom_domains.rb
 lib/volcano-generated/models/paginated_project_deployments.rb
 lib/volcano-generated/models/paginated_projects.rb
@@ -250,6 +265,10 @@ lib/volcano-generated/models/platform_exchange_response.rb
 lib/volcano-generated/models/preview_auth_page_request.rb
 lib/volcano-generated/models/preview_auth_page_response.rb
 lib/volcano-generated/models/project.rb
+lib/volcano-generated/models/project_access_token.rb
+lib/volcano-generated/models/project_access_token_scope.rb
+lib/volcano-generated/models/project_access_token_usage.rb
+lib/volcano-generated/models/project_access_token_usage_daily_entry.rb
 lib/volcano-generated/models/project_config.rb
 lib/volcano-generated/models/project_config_apply_result.rb
 lib/volcano-generated/models/project_config_apply_result_entry.rb
@@ -279,6 +298,7 @@ lib/volcano-generated/models/project_config_database.rb
 lib/volcano-generated/models/project_config_email_template.rb
 lib/volcano-generated/models/project_config_email_templates.rb
 lib/volcano-generated/models/project_config_frontend.rb
+lib/volcano-generated/models/project_config_frontend_function_route.rb
 lib/volcano-generated/models/project_config_function.rb
 lib/volcano-generated/models/project_config_hosted_page.rb
 lib/volcano-generated/models/project_config_hosted_pages.rb
@@ -345,14 +365,37 @@ lib/volcano-generated/models/project_source_export_omission.rb
 lib/volcano-generated/models/project_source_export_skip.rb
 lib/volcano-generated/models/project_source_export_state.rb
 lib/volcano-generated/models/project_usage_response.rb
+lib/volcano-generated/models/publish_sandbox_preset_request.rb
 lib/volcano-generated/models/realtime_config.rb
 lib/volcano-generated/models/realtime_plan_limits.rb
 lib/volcano-generated/models/realtime_stats.rb
 lib/volcano-generated/models/refresh_o_auth_provider_token200_response.rb
+lib/volcano-generated/models/replace_frontend_shared_variables_request.rb
 lib/volcano-generated/models/replace_shared_variables_request.rb
 lib/volcano-generated/models/reset_database_password200_response.rb
 lib/volcano-generated/models/resolve_function_response.rb
 lib/volcano-generated/models/resource_reference.rb
+lib/volcano-generated/models/sandbox_access.rb
+lib/volcano-generated/models/sandbox_access_request.rb
+lib/volcano-generated/models/sandbox_capacity.rb
+lib/volcano-generated/models/sandbox_capacity_list.rb
+lib/volcano-generated/models/sandbox_command_request.rb
+lib/volcano-generated/models/sandbox_command_result.rb
+lib/volcano-generated/models/sandbox_deployment.rb
+lib/volcano-generated/models/sandbox_deployment_page.rb
+lib/volcano-generated/models/sandbox_execution_request.rb
+lib/volcano-generated/models/sandbox_execution_result.rb
+lib/volcano-generated/models/sandbox_file_read_request.rb
+lib/volcano-generated/models/sandbox_file_result.rb
+lib/volcano-generated/models/sandbox_file_write_request.rb
+lib/volcano-generated/models/sandbox_pagination.rb
+lib/volcano-generated/models/sandbox_preset.rb
+lib/volcano-generated/models/sandbox_preset_list.rb
+lib/volcano-generated/models/sandbox_session.rb
+lib/volcano-generated/models/sandbox_session_page.rb
+lib/volcano-generated/models/sandbox_subject_grant_request.rb
+lib/volcano-generated/models/sandbox_template.rb
+lib/volcano-generated/models/sandbox_template_page.rb
 lib/volcano-generated/models/schedule_request.rb
 lib/volcano-generated/models/service_key.rb
 lib/volcano-generated/models/set_project_git_production_branch_request.rb
@@ -381,6 +424,7 @@ lib/volcano-generated/models/update_o_auth_config_request.rb
 lib/volcano-generated/models/update_project_git_deploy_settings_request.rb
 lib/volcano-generated/models/update_project_request.rb
 lib/volcano-generated/models/update_realtime_config_request.rb
+lib/volcano-generated/models/update_sandbox_template_request.rb
 lib/volcano-generated/models/update_storage_bucket_request.rb
 lib/volcano-generated/models/update_variable_request.rb
 lib/volcano-generated/models/upload_session_part.rb