withruntime 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8912abd064916dd450a7fb5b9f0c1610c79b65918cf63a3a599b5906d46e3577
-  data.tar.gz: c7e663ef88244b43c2c761bb6f55e43ea147631e7c22b9c19b7d68789510c0e0
+  metadata.gz: e403c64b0fd311fd7ba3fb2a9fab6304afda36100ebc1fe0bd30f6b8f82bcece
+  data.tar.gz: a6eb390df90ab8f676704e8181c535d2dd23a41eebec44efdbf0219f46f675c6
 SHA512:
-  metadata.gz: 041d53fd9761a1f1e0c9f94cfb70a77c6f0805329dbfbc3523f08cb7024ad4c3bcd06373e08fa6a391823ca48688d786be6643a2b2f460ad1c14c43ee8750c2b
-  data.tar.gz: 4ad9e1df60b31416e7d35abb1499a2fd5e1c329e314a91d9f440f6b56ec2bde9975ae7765a030187f8c6dff540ad8268468188d301de716ae83fd3758117493c
+  metadata.gz: a9994df04fad6ef2af83e9c1bb92e037b42e048bdf2806465d5969e43f7bc4ba9862fcbc77036d61b7d826579f9e0c316e302b05822cf6c326e6739a657ef677
+  data.tar.gz: de3343c87c44ea8dbed899137c0034de4683f64cb2ff44029ffcfbd6da98652f68d4fae8b53fbc90d3dc00a4ba5305d0239190eb756d8dff95ee54f0c0584043

data/lib/withruntime/api_defaults.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  # Every value this SDK sends the API for a bounded time field when the caller
+  # names none, in one place. packages/cloud/tests/sdk-defaults.test.ts holds
+  # each inside the range the API's registry gives that field, and the same
+  # names in the JavaScript, Python, Go and Java SDKs to theirs. The suffix is
+  # the unit; a new default goes here, under a name that test maps to its field.
+  module ApiDefaults
+    # A server-side wait for a state (GET /v1/sandboxes/{id}?waitFor=).
+    WAIT_FOR_TIMEOUT_SECONDS = 60
+    # A streamed exec's command limit when none is given: the API's longest.
+    STREAMED_EXEC_TIMEOUT_SECONDS = 86_400
+    # The time keep_alive keeps ahead of a time limit, and so the most it extends by.
+    KEEP_ALIVE_MARGIN_SECONDS = 600
+  end
+end

data/lib/withruntime/client.rb

@@ -7,25 +7,36 @@ module WithRuntime
   # is safe for use from many threads and keeps its connections open.
   #
   #   runtime = WithRuntime::Client.new # RUNTIME_API_KEY, or this machine's saved connection
-  #   sbx = runtime.sandboxes.create(funding: "trial")
-  #   puts sbx.exec("python3 -c 'print(6 * 7)'", check: true).stdout
+  #   sbx = runtime.sandboxes.create
+  #   sbx.files.write("/workspace/invoice.py", "print(sum([125, 250, 375]))\n")
+  #   puts sbx.exec("python3 /workspace/invoice.py", check: true).stdout
   #   sbx.stop
   #
   # Every product is +runtime.<product>.<verb>+. Money is integer microdollars
   # (1,000,000 is one US dollar).
+  # The account's networks: +wireguard+, a tunnel from your own network into
+  # your sandboxes.
+  Networks = Struct.new(:wireguard)
+
+  # The day the 6 October 2026 rename stops serving its old names, set when it
+  # ships (packages/cloud/src/product-names.ts); nil until then.
+  RENAME_RETIRES = nil
+
   class Client
     attr_reader :transport, :sandboxes, :snapshots, :images, :volumes, :secrets, :limits, :referrals,
-                :switching, :events, :webhooks, :otel, :audit, :feedback, :support, :domains, :ports, :addresses, :tunnel, :sso, :mcp
+                :switching, :events, :webhooks, :otel, :audit, :feedback, :support, :domains, :ports, :ips, :networks, :sso, :mcp
 
     # +api_key+: default RUNTIME_API_KEY, then this machine's saved connection.
     # +base_url+: default RUNTIME_API_URL, then https://api.withruntime.com.
+    # Inside a Runtime sandbox, calls for https://api.withruntime.com go to
+    # http://runtime.internal.
     # +timeout+: seconds for each call, retries included (300).
     # +max_retries+: of transport failures, 429, 502, 503 and 504 (4).
     # +max_connections+: calls in flight at once; streams do not count (32).
     # +wait_for_capacity+: seconds a sandbox create keeps retrying, with the
-    # same key and input, when the trial, quota or region is full (120; 0 fails at once).
+    # same key and input, when the slots without credit, quota or region are full (120; 0 fails at once).
     def initialize(api_key: nil, base_url: nil, timeout: 300, max_retries: 4, max_connections: 32,
-                   wait_for_capacity: 120, env: ENV)
+                   wait_for_capacity: 120, env: ENV, in_sandbox: -> { Credentials.in_runtime_sandbox? })
       origin = Credentials.origin(base_url || env["RUNTIME_API_URL"].then { |url| url.nil? || url.empty? ? DEFAULT_BASE_URL : url })
       key = api_key
       key ||= env["RUNTIME_API_KEY"] unless env["RUNTIME_API_KEY"].to_s.empty?
@@ -34,7 +45,10 @@ module WithRuntime
       raise ArgumentError, "The Runtime API key contains whitespace." if key.match?(/\s/)
       raise ArgumentError, "max_retries cannot be negative." if max_retries.negative?
 
-      @transport = Transport.new(api_key: key, base_url: origin, timeout: timeout, max_retries: max_retries,
+      # The saved key is found by the origin as given; the calls go where that
+      # origin is reachable from here.
+      @transport = Transport.new(api_key: key, base_url: Credentials.reachable(origin, in_sandbox: in_sandbox),
+                                 timeout: timeout, max_retries: max_retries,
                                  max_connections: max_connections, wait_for_capacity: [0, wait_for_capacity].max)
       @sandboxes = Sandboxes.new(@transport)
       @snapshots = Snapshots.new(@transport)
@@ -52,18 +66,23 @@ module WithRuntime
       @support = Support.new(@transport)
       @domains = Domains.new(@transport)
       @ports = Ports.new(@transport)
-      @addresses = Addresses.new(@transport)
-      @tunnel = PrivateTunnel.new(@transport)
+      @ips = Addresses.new(@transport)
+      @networks = Networks.new(PrivateTunnel.new(@transport))
       @sso = SSO.new(@transport)
       @mcp = MCP.new(@transport)
     end
 
+    # Renamed on 6 October 2026, one plural word per product: each old name is the product it became, with a warning,
+    # until RENAME_RETIRES, then raises name_retired.
+    def addresses = renamed("addresses", "ips") { @ips }
+    def tunnel = renamed("tunnel", "networks.wireguard") { @networks.wireguard }
+
     def base_url = @transport.base_url
 
     # Who this key is: organization, agent and credential.
     def me = Record.new(@transport.json("GET", "/v1/me"))
 
-    # The account's credit, holds, trial time and per-resource charges.
+    # The account's credit, holds, free time and per-resource charges.
     def usage = Record.new(@transport.json("GET", "/v1/usage"))
 
     # Calls any API path with this client's key, retries, idempotency keys and
@@ -75,5 +94,20 @@ module WithRuntime
       body = {} if body.nil? && !%w[GET DELETE].include?(method)
       @transport.json(method, path, query: query, body: body)
     end
+
+    private
+
+    def renamed(old, new, retires: RENAME_RETIRES, now: Time.now.utc)
+      if retires && now >= Time.utc(*retires.split("-").map(&:to_i))
+        raise Error.new("runtime.#{old} was renamed runtime.#{new} and stopped working on #{retires}.",
+                        code: "name_retired", status: 410, hint: "Use runtime.#{new}.")
+      end
+      @renamed_said ||= {}
+      unless @renamed_said[old]
+        @renamed_said[old] = true
+        warn("Runtime: runtime.#{old} is now runtime.#{new}.#{retires ? " It stops working on #{retires}." : ""}")
+      end
+      yield
+    end
   end
 end

data/lib/withruntime/credentials.rb

@@ -12,22 +12,48 @@ module WithRuntime
   module Credentials
     KEY = /\Artcloud_[a-f0-9-]{36}_[A-Za-z0-9_-]{43}\z/
 
+    BAD_ORIGIN = "Use an HTTPS API origin (or http://runtime.internal inside a sandbox, http://localhost for tests)."
+    # Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
+    # own host sends each request on to the public API over HTTPS. The API runs
+    # on that host, whose addresses a sandbox cannot reach directly. Plain HTTP
+    # because the hop never leaves the machine: from the program to the guest's
+    # own proxy, then over the sandbox's private channel to its host.
+    SANDBOX_BASE_URL = "http://runtime.internal"
+    # A file every Runtime sandbox has; the guest keeps it current.
+    SANDBOX_MARKER = "/run/runtime/environment.json"
+
     module_function
 
-    # An HTTPS origin, or plain HTTP to localhost for tests, with nothing after the host.
+    def in_runtime_sandbox?(marker = SANDBOX_MARKER)
+      File.exist?(marker)
+    end
+
+    # The origin calls for +api_origin+ are sent to from here. In a sandbox the
+    # public API is its own host, which it cannot reach directly, so calls for
+    # it go to runtime.internal; every other origin is left as it is.
+    def reachable(api_origin, in_sandbox: -> { in_runtime_sandbox? })
+      api_origin == DEFAULT_BASE_URL && in_sandbox.call ? SANDBOX_BASE_URL : api_origin
+    end
+
+    # An HTTPS origin, plain HTTP to runtime.internal inside a sandbox, or plain
+    # HTTP to localhost for tests, with nothing after the host. runtime.internal
+    # is reserved and never resolves outside a sandbox, so a key sent there in
+    # plain HTTP never leaves the sandbox's host.
     def origin(value)
       uri = URI(value)
-      local = %w[localhost 127.0.0.1 [::1] ::1].include?(uri.host)
+      internal = uri.host == "runtime.internal"
+      local = %w[localhost 127.0.0.1 [::1] ::1].include?(uri.host) || internal
       unless uri.host && (uri.scheme == "https" || (local && uri.scheme == "http")) && uri.userinfo.nil? &&
-             uri.query.nil? && uri.fragment.nil? && ["", "/"].include?(uri.path.to_s)
-        raise ArgumentError, "Use an HTTPS API origin (or http://localhost for tests)."
+             uri.query.nil? && uri.fragment.nil? && ["", "/"].include?(uri.path.to_s) &&
+             !(internal && (uri.scheme != "http" || uri.port != 80))
+        raise ArgumentError, BAD_ORIGIN
       end
 
       default_port = uri.scheme == "https" ? 443 : 80
       host = uri.host.include?(":") && !uri.host.start_with?("[") ? "[#{uri.host}]" : uri.host
       "#{uri.scheme}://#{host}#{uri.port == default_port ? "" : ":#{uri.port}"}"
     rescue URI::InvalidURIError
-      raise ArgumentError, "Use an HTTPS API origin (or http://localhost for tests)."
+      raise ArgumentError, BAD_ORIGIN
     end
 
     # Where the CLI keeps this machine's connection for the two origins.

data/lib/withruntime/errors.rb

@@ -7,11 +7,16 @@ module WithRuntime
   # Java SDKs.
   class Error < StandardError
     # 503s that are a deliberate state, not a passing one: retrying cannot change them.
-    DELIBERATE = %w[fork_unavailable previews_unavailable unavailable].freeze
-    # Refusals that pass on their own: a host frees room, a trial slot frees.
-    PASSING = %w[no_capacity trial_busy].freeze
+    DELIBERATE = %w[
+      unavailable unsupported fork_unavailable previews_unavailable
+      network_unavailable network_rules_unavailable secrets_unavailable identity_unavailable env_unavailable
+      resize_unavailable
+    ].freeze
+    # Refusals that pass on their own: a host frees room, a sandbox of an
+    # account without credit stops.
+    PASSING = %w[no_capacity no_credit_running_limit no_credit_total_limit].freeze
     # Refusals of a create that clear when a sandbox stops or a host frees room.
-    WAITS_FOR_ROOM = %w[trial_busy trial_domain_limit trial_capacity quota_exceeded no_capacity].freeze
+    WAITS_FOR_ROOM = %w[no_credit_running_limit no_credit_total_limit no_credit_domain_limit no_credit_capacity_full quota_exceeded no_capacity volume_releasing].freeze
 
     attr_reader :code, :status, :hint, :request_id, :details, :idempotency_key, :retry_after
 

data/lib/withruntime/network_products.rb

@@ -20,24 +20,24 @@ module WithRuntime
   end
 
   class Addresses < Product
-    def reserve(family: 4) = Record.new(@t.json("POST", "/v1/addresses", body: { "family" => family }))
-    def list = @t.json("GET", "/v1/addresses")["data"].map { |row| Record.new(row) }
-    def release(id) = @t.json("DELETE", "/v1/addresses/#{seg(id)}") && nil
+    def reserve(family: 4) = Record.new(@t.json("POST", "/v1/ips", body: { "family" => family }))
+    def list = @t.json("GET", "/v1/ips")["data"].map { |row| Record.new(row) }
+    def release(id) = @t.json("DELETE", "/v1/ips/#{seg(id)}") && nil
   end
 
   # Account WireGuard networking, distinct from Sandbox#open_tunnel.
   class PrivateTunnel < Product
-    def get = Record.new(@t.json("GET", "/v1/tunnel"))
-    def create(subnet: nil) = Record.new(@t.json("POST", "/v1/tunnel", body: { "subnet" => subnet }.compact))
-    def delete = @t.json("DELETE", "/v1/tunnel") && nil
+    def get = Record.new(@t.json("GET", "/v1/networks/wireguard"))
+    def create(subnet: nil) = Record.new(@t.json("POST", "/v1/networks/wireguard", body: { "subnet" => subnet }.compact))
+    def delete = @t.json("DELETE", "/v1/networks/wireguard") && nil
     # Save config even when config_ready is false: its private key is shown once.
     def add_peer(name:, public_key: nil, routes: nil, idempotency_key: nil)
-      Record.new(@t.json("POST", "/v1/tunnel/peers", body: Fields.body(name: name, public_key: public_key, routes: routes), key: idempotency_key, no_retry: public_key.to_s.empty?))
+      Record.new(@t.json("POST", "/v1/networks/wireguard/peers", body: Fields.body(name: name, public_key: public_key, routes: routes), key: idempotency_key, no_retry: public_key.to_s.empty?))
     end
     def rotate_peer(id, public_key: nil)
-      Record.new(@t.json("POST", "/v1/tunnel/peers/#{seg(id)}:rotate", body: { "publicKey" => public_key }.compact, no_retry: public_key.to_s.empty?))
+      Record.new(@t.json("POST", "/v1/networks/wireguard/peers/#{seg(id)}:rotate", body: { "publicKey" => public_key }.compact, no_retry: public_key.to_s.empty?))
     end
-    def remove_peer(id) = Record.new(@t.json("DELETE", "/v1/tunnel/peers/#{seg(id)}"))
+    def remove_peer(id) = Record.new(@t.json("DELETE", "/v1/networks/wireguard/peers/#{seg(id)}"))
   end
 
   class SSO < Product

data/lib/withruntime/parity_products.rb

@@ -45,7 +45,7 @@ module WithRuntime
     def get(id) = Record.new(@t.json("GET", path(id)))
     def list = @t.json("GET", path)["data"].map { |row| Record.new(row) }
     def stop(id) = Record.new(@t.json("POST", "#{path(id)}:stop", body: {}))
-    def download(id) = @t.bytes("GET", "#{path(id)}/video", accept: "video/mp4")
+    def download(id) = @t.file_bytes("#{path(id)}/video", accept: "video/mp4")
     def delete(id) = @t.json("DELETE", path(id)) && nil
   end
 end

data/lib/withruntime/products.rb

@@ -71,6 +71,12 @@ module WithRuntime
 
     def list(state: nil, name: nil, limit: nil) = page("/v1/volumes", { "state" => state, "name" => name, "limit" => limit })
 
+    # Grows a volume no sandbox holds to +size_mib+, on its host, and waits
+    # (up to +wait+ seconds) for it. The answer's +resize+ shows how far it got.
+    def resize(id, size_mib:, wait: 10, idempotency_key: nil)
+      Record.new(@t.json("POST", "/v1/volumes/#{seg(id)}:resize", body: Fields.body(size_mib: size_mib), wait: wait, key: idempotency_key))
+    end
+
     # Deletes a volume and everything on it.
     def delete(id) = Record.new(@t.json("POST", "/v1/volumes/#{seg(id)}:delete", body: {}))
   end
@@ -103,7 +109,8 @@ module WithRuntime
     def get = Record.new(@t.json("GET", "/v1/limits"))
   end
 
-  # +runtime.referrals+: the account's referral link and what it earned.
+  # +runtime.referrals+: the account's referral link and what it earned. Money is
+  # integer microdollars in strings.
   class Referrals < Product
     def get = Record.new(@t.json("GET", "/v1/referrals"))
   end

data/lib/withruntime/sandbox.rb

@@ -13,22 +13,28 @@ module WithRuntime
     end
 
     # Creates a sandbox and, unless +wait: false+, waits until it is running.
-    # Every field is optional: with none you get the free trial while it lasts,
+    # Every field is optional: with none you get the free usage while it lasts,
     # the default region and a 2 vCPU / 4 GiB machine for up to 30 minutes.
-    # When every trial slot or the account's quota is taken, it waits for one to
+    # When every slot without credit or the account's quota is taken, it waits for one to
     # free, up to +wait_for_capacity+ seconds (the client's, two minutes by default).
     #
-    #   runtime.sandboxes.create(funding: "trial", labels: { team: "search" }, timeout_seconds: 900)
+    #   runtime.sandboxes.create(labels: { team: "search" }, timeout_seconds: 900)
     def create(wait: true, idempotency_key: nil, wait_for_capacity: nil, **fields)
       room = wait_for_capacity.nil? ? @t.wait_for_capacity : [0, wait_for_capacity].max
       info = @t.json("POST", "/v1/sandboxes", body: Fields.body(fields), wait: wait ? 60 : 0,
                                               key: idempotency_key, room: room)
       sandbox = Sandbox.new(@t, info)
       if wait && sandbox.state != "running"
-        sandbox.wait_for("running", timeout: 60)
+        sandbox.wait_for("running", timeout: ApiDefaults::WAIT_FOR_TIMEOUT_SECONDS)
         unless sandbox.state == "running"
-          raise Error.new("Sandbox #{sandbox.id} is #{sandbox.state}, not running.", code: "start_failed",
-                                                                                       hint: "Read it with runtime.sandboxes.get(id); stop_reason says why.")
+          message = if info["replayed"]
+                      "Sandbox #{sandbox.id} was made by an earlier call with this idempotency key and is #{sandbox.state} now. " \
+                        "It did not fail to start; create again with a new key."
+                    else
+                      "Sandbox #{sandbox.id} is #{sandbox.state}, not running."
+                    end
+          raise Error.new(message, code: "start_failed",
+                                   hint: "Read it with runtime.sandboxes.get(id); stop_reason says why.")
         end
       end
       sandbox
@@ -94,7 +100,7 @@ module WithRuntime
 
     # Waits, on the server with no polling, until the sandbox reaches +state+
     # (running, paused or stopped) or +timeout+ seconds pass.
-    def wait_for(state, timeout: 60)
+    def wait_for(state, timeout: ApiDefaults::WAIT_FOR_TIMEOUT_SECONDS)
       seconds = [1, timeout.to_i].max
       @info = Record.new(@t.json("GET", path, query: { "waitFor" => state, "timeoutSeconds" => seconds },
                                               timeout: seconds + 60))
@@ -110,12 +116,14 @@ module WithRuntime
     # Saves the sandbox's memory and files; compute billing stops.
     def pause(wait: true, idempotency_key: nil) = lifecycle("pause", {}, wait, idempotency_key)
 
-    # Carries on a paused sandbox, with its memory and processes; +timeout_seconds+ is its new lease.
+    # Carries on a paused sandbox, with its memory and processes;
+    # +timeout_seconds+ is its new time limit, for a sandbox that has one.
     def wake(wait: true, timeout_seconds: nil, idempotency_key: nil)
       lifecycle("wake", timeout_seconds ? { "timeoutSeconds" => timeout_seconds } : {}, wait, idempotency_key)
     end
 
-    # More time before the lease ends, at most an hour ahead of now.
+    # Moves a sandbox's time limit on, at most an hour ahead of now. A sandbox
+    # with no time limit answers at once and nothing changes.
     def extend_lease(seconds, idempotency_key: nil) = lifecycle("extend", { "seconds" => seconds }, false, idempotency_key)
 
     # Days (1 to 365) a paused sandbox is kept before it is deleted.
@@ -133,12 +141,13 @@ module WithRuntime
       lifecycle("update", body, false, idempotency_key)
     end
 
-    # Keeps a running sandbox's lease ahead of now on a background thread, until
-    # +stop+ or +stop_keep_alive+: every +every+ seconds it extends the lease so
-    # that +margin+ seconds remain, never more than the hour ahead the API
-    # allows. Running time is billed as it is used. A paused sandbox is left
-    # paused; a stopped one ends the loop.
-    def keep_alive(every: 60, margin: 600, &on_error)
+    # Keeps a sandbox with a time limit running past it on a background thread,
+    # until +stop+ or +stop_keep_alive+: every +every+ seconds it extends the
+    # limit so that +margin+ seconds remain, never more than the hour ahead the
+    # API allows. A sandbox with no time limit needs none and is only watched.
+    # Running time is billed as it is used. A paused sandbox is left paused; a
+    # stopped one ends the loop.
+    def keep_alive(every: 60, margin: ApiDefaults::KEEP_ALIVE_MARGIN_SECONDS, &on_error)
       stop_keep_alive
       every = [10, every].max
       margin = margin.clamp(60, 3600)
@@ -148,7 +157,7 @@ module WithRuntime
             refresh
             break if %w[stopped stopping].include?(state)
 
-            expires = @info["expiresAt"]
+            expires = Sandbox.limit_end(@info)
             if state == "running" && expires
               need = (margin - (Time.parse(expires) - Time.now)).ceil
               extend_lease([3600, need].min) if need >= 1
@@ -163,6 +172,17 @@ module WithRuntime
       self
     end
 
+    # Where a sandbox's time limit ends, or nil when it has none: it renews
+    # itself (timeoutSeconds 0, or persistent) unless endsAt says its renewal
+    # stopped. An older server sends no endsAt and a timeout of at least a
+    # minute.
+    def self.limit_end(info)
+      return info["endsAt"] if info["endsAt"]
+      return nil if info["timeoutSeconds"].to_i.zero? || info["persistent"]
+
+      info["expiresAt"]
+    end
+
     # Ends a keep-alive, if one runs.
     def stop_keep_alive
       thread = @keep_alive
@@ -174,8 +194,9 @@ module WithRuntime
     # processes), each its own sandbox, on the same server, answered once they
     # run. One copy without +count+; an array with it. If a copy fails, the
     # error's +details["startedSandboxIds"]+ names the copies that did start.
+    # +funding+ is accepted and ignored: copies run on free usage first, then credit.
     def fork(count: nil, name: nil, labels: nil, keep_snapshot: nil, funding: nil, idempotency_key: nil)
-      body = Fields.body(count: count, name: name, labels: labels, keep_snapshot: keep_snapshot, funding: funding)
+      body = Fields.body(count: count, name: name, labels: labels, keep_snapshot: keep_snapshot)
       reply = @t.json("POST", path(":fork"), body: body, wait: 60, key: idempotency_key)
       copies = reply["sandboxes"].map { |info| Sandbox.new(@t, info) }
       count.nil? ? copies.first : copies
@@ -239,43 +260,89 @@ module WithRuntime
                                                idempotency_key: idempotency_key)
       end
 
-      body = command_body(command, cwd, env, stdin, timeout || 86_400).merge("stream" => true)
+      longest = ApiDefaults::STREAMED_EXEC_TIMEOUT_SECONDS
+      body = command_body(command, cwd, env, stdin, timeout || longest).merge("stream" => true)
       handed_over = nil
-      @t.events("POST", path(":exec"), body: body, key: idempotency_key,
-                                       timeout: timeout ? timeout + 60 : 86_400) do |event|
-        case event["type"]
-        when "continue" then handed_over = event
-        when "error" then raise stream_error(event)
-        else yield event
+      process_id = nil
+      cursor = 0
+      exited = false
+      begin
+        @t.events("POST", path(":exec"), body: body, key: idempotency_key,
+                                         timeout: timeout ? timeout + 60 : longest) do |event|
+          case event["type"]
+          when "continue" then handed_over = event
+          when "error" then raise stream_error(event)
+          else
+            process_id = event["processId"] if event["type"] == "start"
+            cursor = event["offset"] + event["data"].bytesize if %w[stdout stderr].include?(event["type"])
+            exited = true if event["type"] == "exit"
+            yield event
+          end
+          break if handed_over || exited
         end
-        break if handed_over
+      rescue ConnectionError => e
+        raise if e.code != "connection_error" || process_id.nil?
       end
-      follow(handed_over["processId"], handed_over["cursor"], &block) if handed_over
+      return follow(handed_over["processId"], handed_over["cursor"], &block) if handed_over
+      return if exited
+
+      # The stream closed before the command's exit. Its output is kept on the
+      # sandbox, so follow it from where this stream stopped; an end with no
+      # exit is never a result.
+      if process_id.nil?
+        raise ConnectionError.new("The exec stream closed before the command started.",
+                                  code: "connection_error", idempotency_key: idempotency_key,
+                                  hint: "Run it again; to be sure it runs once, pass the same idempotency_key.")
+      end
+      follow(process_id, cursor, &block)
     end
 
-    # A process's output events from +cursor+ until it exits, across the server's stream slices.
+    # A process's output events from +cursor+ until it exits, across the
+    # server's stream slices. A stream that closes or is cut before the exit
+    # is followed again from where it stopped; four in a row with nothing new
+    # are an error, never an end.
     def follow(process_id, cursor = 0)
       return enum_for(:follow, process_id, cursor) unless block_given?
 
+      idle = 0
       loop do
         resume = nil
         exited = false
-        @t.events("GET", path("/processes/#{Transport.segment(process_id)}/output"),
-                  query: { "cursor" => cursor, "follow" => "true" }, timeout: 180) do |event|
-          case event["type"]
-          when "continue"
-            resume = event["cursor"]
-            break
-          when "stdout", "stderr" then cursor = event["offset"] + event["data"].bytesize
-          when "error" then raise stream_error(event)
-          when "exit" then exited = true
+        before = cursor
+        cut = false
+        begin
+          @t.events("GET", path("/processes/#{Transport.segment(process_id)}/output"),
+                    query: { "cursor" => cursor, "follow" => "true" }, timeout: 180) do |event|
+            case event["type"]
+            when "continue"
+              resume = event["cursor"]
+              break
+            when "stdout", "stderr" then cursor = event["offset"] + event["data"].bytesize
+            when "error" then raise stream_error(event)
+            when "exit" then exited = true
+            end
+            yield event
+            break if exited
           end
-          yield event
-          break if exited
+        rescue ConnectionError => e
+          raise if e.code != "connection_error"
+
+          cut = true
         end
-        break if exited || resume.nil?
+        break if exited
 
-        cursor = resume
+        cursor = [cursor, resume].max if resume
+        if resume || cursor > before
+          idle = 0
+          next
+        end
+        idle += 1
+        if idle > 3
+          raise ConnectionError.new("The output stream of process #{process_id} keeps closing before it ends.",
+                                    code: "connection_error",
+                                    hint: "Read what it printed so far: runtime sandboxes logs #{id} #{process_id}")
+        end
+        sleep([0.05 * (2**idle), 2].min) if cut
       end
     end
 
@@ -421,7 +488,7 @@ module WithRuntime
     end
 
     # A file's bytes (a binary String), any size.
-    def read(path) = t.bytes("GET", @sandbox.path("/files/content"), query: { "path" => path }, accept: "application/octet-stream")
+    def read(path) = t.file_bytes(@sandbox.path("/files/content"), query: { "path" => path })
 
     def read_text(path) = read(path).force_encoding(Encoding::UTF_8)
 
@@ -536,20 +603,38 @@ module WithRuntime
       nil
     end
 
-    # Copies a local file or directory in. A directory travels as one gzipped tar.
+    # Copies a local file or directory in. A directory travels as one gzipped
+    # tar to the API's folder routes, unpacked by the sandbox's own tar as it
+    # arrives.
     def upload(local, remote)
       return write(remote, File.binread(local)) unless File.directory?(local)
 
-      staging = "/tmp/.runtime-upload-#{SecureRandom.uuid}.tar.gz"
-      write(staging, Tar.pack_directory(local))
-      result = @sandbox.exec(["sh", "-c", 'mkdir -p "$1" && tar -xzf "$2" -C "$1"; code=$?; rm -f "$2"; exit $code',
-                              "sh", remote, staging])
-      raise CommandError, result unless result.ok?
-
+      archive = Tar.pack_directory(local)
+      if archive.bytesize <= CHUNK
+        t.bytes("PUT", @sandbox.path("/files/archive"), query: { "path" => remote }, raw: archive)
+        return nil
+      end
+      # Larger: parts in order; a part resent after a lost answer is not written twice.
+      upload = t.json("POST", @sandbox.path("/files/archive/uploads"), body: { "path" => remote, "gzip" => true })
+      base = @sandbox.path("/files/archive/uploads/#{Transport.segment(upload["uploadId"])}")
+      begin
+        (0...archive.bytesize).step(upload["chunkBytes"].to_i) do |offset|
+          t.bytes("PUT", base, query: { "offset" => offset }, raw: archive.byteslice(offset, upload["chunkBytes"].to_i))
+        end
+        t.json("POST", "#{base}:commit", body: {})
+      rescue StandardError
+        begin
+          t.json("POST", "#{base}:abort", body: {}, timeout: 10)
+        rescue Error
+          nil
+        end
+        raise
+      end
       nil
     end
 
-    # Copies a file or directory out.
+    # Copies a file or directory out. A directory comes as one tar from the
+    # API's folder route.
     def download(remote, local)
       entry = stat(remote)
       raise NotFoundError.new("#{remote} does not exist.", code: "file_not_found", status: 404) unless entry
@@ -559,18 +644,14 @@ module WithRuntime
         File.binwrite(local, read(remote))
         return nil
       end
-      staging = "/tmp/.runtime-download-#{SecureRandom.uuid}.tar.gz"
-      packed = @sandbox.exec(["tar", "-czf", staging, "-C", remote, "."])
-      raise CommandError, packed unless packed.ok?
-
+      # The sandbox's own tar packs it as it streams, and it is unpacked as it
+      # arrives; one cut short is refused and nothing is put in place.
+      unpacker = Tar::Unpacker.new(local)
       begin
-        Tar.unpack(read(staging), local)
+        t.chunks(@sandbox.path("/files/archive"), query: { "path" => remote, "gzip" => true }) { |chunk| unpacker.feed(chunk) }
+        unpacker.finish
       ensure
-        begin
-          remove(staging)
-        rescue Error
-          nil # /tmp is cleared with the sandbox.
-        end
+        unpacker.discard
       end
       nil
     end
@@ -587,11 +668,16 @@ module WithRuntime
       @sandbox = sandbox
     end
 
-    # Shares +port+, or changes its visibility if it is shared already.
-    # +visibility+ is "private" (the default: a token is needed) or "public";
-    # +ttl_seconds+ is how long the returned token lasts (60 s to 7 days).
-    def create(port, visibility: nil, ttl_seconds: nil)
-      body = { "port" => port, "visibility" => visibility, "ttlSeconds" => ttl_seconds }.compact
+    # Shares +port+, or changes its visibility and embed origins if it is
+    # shared already. +visibility+ is "private" (the default: a token is
+    # needed) or "public"; +ttl_seconds+ is how long the returned token lasts
+    # (60 s to 7 days). +embed_origins+ names the sites that may show it in an
+    # iframe (["https://app.example.com", "https://*.example.com"]); any other
+    # site's iframe is refused. Omitted, a shared port keeps its list; [] is
+    # any site, the default.
+    def create(port, visibility: nil, ttl_seconds: nil, embed_origins: nil)
+      body = { "port" => port, "visibility" => visibility, "ttlSeconds" => ttl_seconds,
+               "embedOrigins" => embed_origins }.compact
       Record.new(t.json("POST", path, body: body))
     end