withruntime 0.1.0

checksums.yaml

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

data/GUIDE.md

@@ -0,0 +1,406 @@
+# Ruby SDK
+
+One Ruby client for every Runtime Cloud product.
+
+The `withruntime` gem needs Ruby 3.2 or later and uses only the standard
+library. It is safe to share between threads and keeps its connections open.
+
+```bash no-run
+gem install withruntime
+```
+
+**The client finds its key by itself.** It uses `RUNTIME_API_KEY` when that is
+set, and otherwise the connection this machine saved (any `npx withruntime`
+command connects it, with one browser approval).
+
+On a server, put a key from https://withruntime.com/account/keys in
+`RUNTIME_API_KEY` from your secret manager. Never put it in source code, a URL
+or a command-line argument. With no key anywhere, `WithRuntime::Client.new`
+raises `WithRuntime::AuthenticationError` whose `code` is `missing_api_key`
+and whose `hint` says how to get one.
+
+## Hello, sandbox
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+sbx = runtime.sandboxes.create(funding: "trial")
+begin
+  puts sbx.exec("python3 -c 'print(6 * 7)'", check: true).stdout
+ensure
+  sbx.stop
+end
+```
+
+`create` returns once the sandbox is running. With no arguments you get the
+free trial while it lasts, the default region, and 2 vCPU, 4 GiB of memory and
+a 4 GiB disk for up to 30 minutes. `funding: "trial"` never falls back to paid
+credit. Every field is optional, in snake_case:
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+sbx = runtime.sandboxes.create(
+  name: "tests-42",
+  labels: { team: "search", job: "42" },
+  vcpu: 2,
+  memory_mib: 4096,
+  disk_mib: 8192,
+  timeout_seconds: 900,
+  on_lease_end: "stop",
+  network: { internet: true, allow: ["rubygems.org", "*.githubusercontent.com"] }
+)
+puts sbx.id, sbx.info.funding, sbx.info.expires_at
+sbx.stop
+```
+
+An answer reads by snake_case name (`sbx.info.memory_mib`) or by the API's own
+key (`sbx.info["memoryMiB"]`), so a field newer than the SDK is always there. A
+string key in a request (`"newField" => 1`) is sent as it is.
+
+## Run commands
+
+A string runs under `bash -c`; an array runs the program directly, with no
+shell, which is what you want for untrusted arguments.
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+sbx = runtime.sandboxes.create
+sbx.exec("mkdir -p app && echo 'print(1 + 1)' > app/main.py")
+run = sbx.exec(["python3", "main.py"], cwd: "/workspace/app", env: { API_TOKEN: ENV.fetch("API_TOKEN", "") }, timeout: 120)
+warn run.stderr unless run.exit_code.zero?
+print run.stdout
+
+sbx.exec("for i in 1 2 3; do echo line $i; sleep 1; done", on_stdout: ->(text) { print text })
+sbx.exec_stream("node --version") do |event|
+  print event["data"] if event["type"] == "stdout"
+end
+sbx.stop
+```
+
+- `env:` is how secrets reach a command. It is never echoed back. Never put a
+  secret in the command line itself.
+- `stdin:` gives the command input, then closes it.
+- The default timeout is 60 seconds; the maximum is a day. A timeout is a
+  result (`timed_out` is true, with the output so far), not an exception.
+- `check: true` raises `WithRuntime::CommandError`, with the exit code and
+  output, on a non-zero exit or a timeout.
+- With `on_stdout:`, `on_stderr:` or a timeout over a minute, the command
+  streams and the result keeps everything it printed. A long stream resumes by
+  itself when the server ends it, so no output is dropped.
+
+## Background processes
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+sbx = runtime.sandboxes.create
+server = sbx.spawn("python3 -m http.server 8000", cwd: "/workspace")
+repl = sbx.spawn(["python3", "-i", "-q"], pipe_stdin: true)
+repl.write("print(21 * 2)\n", eof: true)
+print repl.wait.stdout
+sbx.processes.each { |process| puts "#{process.id} #{process.state} #{process.command}" }
+server.kill("SIGTERM")
+sbx.stop
+```
+
+A process outlives your connection; get it back with `sbx.process(id)`.
+`write` tracks input offsets, so a retried write is never typed twice.
+
+## Files
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+sbx = runtime.sandboxes.create
+sbx.files.write("/workspace/data/input.csv", "a,b\n1,2\n")
+print sbx.files.read_text("/workspace/data/input.csv")
+sbx.files.list("/workspace", depth: 2).each { |entry| puts "#{entry.type} #{entry.size} #{entry.path}" }
+sbx.files.mkdir("/workspace/out")
+sbx.files.rename("/workspace/data/input.csv", "/workspace/out/input.csv")
+sbx.files.upload("./lib", "/workspace/project/lib")
+sbx.files.download("/workspace/out", "./out")
+sbx.stop
+```
+
+`write` makes parent directories and replaces the file atomically; a file over
+1 MiB goes in parallel chunks checked by SHA-256. `stat` returns `nil` for a
+path that does not exist. `upload` and `download` move a whole directory as
+one gzipped archive. Pass `mode: 0o755` to write an executable, or
+`mode: 0` for no permission bits. `chmod(path, mode)` changes an existing
+file. A caller-supplied `idempotency_key:` also makes a complete large-file
+write safe to repeat; each upload phase keeps its own stable key. On an
+older guest, setting a mode also needs the exec grant for its chmod fallback.
+
+## Pause, wake, fork and snapshot
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+sbx = runtime.sandboxes.create(funding: "trial")
+sbx.pause # memory and files are kept; compute billing stops
+again = runtime.sandboxes.get(sbx.id)
+again.wake(timeout_seconds: 1200)
+again.extend_lease(600)
+
+copies = again.fork(count: 2, funding: "trial")
+copies.each(&:stop)
+snapshot = again.snapshot(name: "ready", retention_days: 7)
+runtime.sandboxes.create(snapshot: snapshot.id, funding: "trial").stop
+runtime.snapshots.delete(snapshot.id)
+again.stop
+```
+
+A fork copies a sandbox as it is now, with its files, memory and running
+processes, on the same server; see [JavaScript](./javascript) for what forks
+and snapshots keep and how they are billed. If a copy fails, the error's
+`details["startedSandboxIds"]` names the copies that did start. Because
+`extend` is Ruby's own, the lease is extended with `extend_lease(seconds)`.
+`sbx.keep_alive` extends it from your process until `stop`, and
+`runtime.sandboxes.get_or_create(name, **fields)` answers the sandbox with
+that name, woken or restarted, or creates it.
+
+## Share a port
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+sbx = runtime.sandboxes.create
+sbx.spawn("python3 -m http.server 3000")
+preview = sbx.previews.create(3000)
+puts preview.url, preview.token # send the token as x-runtime-preview-token
+sbx.stop
+```
+
+A preview is private by default; `visibility: "public"` shares it with anyone
+who has the address. Addresses are under `runtimehost.com`.
+
+## Images, volumes, network rules and secrets
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+image = runtime.images.build(name: "data", recipe: { pip: ["pandas"], apt: ["jq"] }) { |line| puts line.text }
+volume = runtime.volumes.create(size_mib: 10_240, name: "cache")
+sbx = runtime.sandboxes.create(image: image.id, volumes: [{ volume_id: volume.id, path: "/data" }])
+print sbx.exec("python3 -c 'import pandas; print(pandas.__version__)'").stdout
+cell = sbx.interpreter.run("import math\nround(math.pi * 2, 3)")
+puts cell.results.first.data["text/plain"]
+sbx.network.set(internet: true, allow: ["pypi.org", "*.pythonhosted.org"])
+sbx.stop
+
+secret = runtime.secrets.set("OPENAI_API_KEY", value: "sk-...", hosts: ["api.openai.com"])
+puts secret.placeholder # what sandboxes see in $OPENAI_API_KEY
+```
+
+`images.build` waits until the image is ready and raises with code
+`image_failed` when the build fails; `images.create` queues it and returns. A
+Dockerfile build takes `dockerfile:` and `context_dir:`, the folder
+`docker build` would read, with its `.dockerignore`; only the parts the server
+does not have yet are uploaded. See [custom images](./images). A volume lives
+on one server; volume backups can restore its data onto another host.
+`sbx.desktop` drives a Linux desktop in the sandbox.
+
+## Domains, TCP ports and private networking
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+sbx = runtime.sandboxes.create
+runtime.domains.add(hostname: "app.example.org", sandbox_id: sbx.id, port: 8080)
+p runtime.domains.get("app.example.org") # DNS records to install, then verify
+runtime.domains.verify("app.example.org")
+port = runtime.ports.open(sandbox_id: sbx.id, port: 5432)
+p port
+runtime.ports.close(port.id)
+runtime.domains.remove("app.example.org")
+sbx.stop
+```
+
+`runtime.addresses.reserve(family: 4)` reserves a dedicated address;
+`list` and `release(id)` manage it. Returned funding fields and integer money
+are preserved. `runtime.tunnel` manages the account's WireGuard network with
+`create`, `get`, `delete`, `add_peer`, `rotate_peer` and `remove_peer`.
+Save a generated peer's `config` securely even when `config_ready` is false:
+its private key is returned once. Calls generating a private key are not
+retried automatically. `runtime.sso.get` reads the organization's SSO state.
+
+## Backups, mounts, MCP and recordings
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+volume = runtime.volumes.create(size_mib: 1024)
+backup = runtime.volumes.backup(volume.id, name: "before-import", retention_days: 7)
+runtime.volumes.set_backup_policy(volume.id, daily: true, retention_days: 7)
+restored = runtime.volumes.restore(backup.id, name: "restored")
+p runtime.volumes.backups(volume_id: volume.id).data
+runtime.volumes.delete_backup(backup.id)
+runtime.volumes.delete(restored.id)
+runtime.volumes.delete(volume.id)
+```
+
+`sbx.mounts.add(provider: "s3", bucket: "data", path: "/data", secret: "S3_KEY")`
+mounts an object store; `list` and `remove(path)` manage mounts. The named
+secret stays on Runtime. `runtime.mcp.catalog` lists supported servers;
+`sbx.mcp.start(servers: [{ id: "fetch" }])`, `ready`, `get` and `stop` manage
+servers in a sandbox. Server `secrets`, `env` and `options` keep their
+original dictionary keys.
+
+`sbx.desktop.recordings.start(fps: 10)` returns a recording. Use `get(id)`,
+`list`, `stop(id)`, `download(id)` for MP4 bytes, and `delete(id)` to manage it.
+
+## Watch files
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+sbx = runtime.sandboxes.create
+watch = sbx.files.watch("/workspace", recursive: true)
+begin
+  watch.events.each { |event| puts "#{event.k}: #{event.path}" }
+ensure
+  watch.stop
+  sbx.stop
+end
+```
+
+The reader follows continuation messages and keeps `watch.cursor`. Overflow
+and lost-event notices reach your block. `watch.close` cancels only the active
+reader; another thread can call it while HTTP headers, a body or a retry delay
+is pending. `watch.stop` also removes the watch in the guest and prevents new
+readers. A paused sandbox ends the current stream.
+
+## Terminal and local port forwarding
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+sbx = runtime.sandboxes.get("your-sandbox-id")
+terminal = sbx.terminal(cols: 100, rows: 30)
+begin
+  terminal.write("printf 'hello\n'\n")
+  print terminal.read
+  terminal.resize(cols: 120, rows: 40)
+ensure
+  terminal.close
+end
+forward = sbx.port_forward(8080)
+begin
+  puts "Local server: http://#{forward.host}:#{forward.port}"
+ensure
+  forward.close
+end
+```
+
+A terminal exposes `read`, `write`, `resize`, `process_id`, `exit_code` and
+`close`. `sbx.open_tunnel` shares one authenticated connection across
+`connect(port)` and `ssh(public_key)` streams. Each stream supports `read`,
+`write`, `close_write` and `close`; half-closing input still permits a response.
+`port_forward` binds to `127.0.0.1` and a free port by default; pass `host:`
+and `local_port:` to choose them. Closing it releases its listener and active
+connections.
+
+Read responses while writing large requests. An individual unread stream has
+at most 1 MiB buffered; overflow closes that stream with
+`tunnel_receive_overflow` and leaves other streams usable. Closing a terminal
+or tunnel wakes blocked readers and writers. WebSockets use the same API key
+and origin, support an HTTP CONNECT proxy, and verify TLS certificates.
+
+## Metrics, events and webhooks
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+hook = runtime.webhooks.create(url: "https://example.com/hooks/runtime")
+secret = hook.secret # shown once; keep it
+
+# In your endpoint, with the raw body and the Runtime-Signature header:
+begin
+  event = WithRuntime::Webhooks.verify("{}", "t=0,v1=0", secret)
+  puts event.type
+rescue WithRuntime::WebhookVerificationError => e
+  puts "refused: #{e.message}"
+end
+runtime.events.list(type: "sandbox.stopped").each { |event| puts "#{event.created_at} #{event.type}" }
+```
+
+`sbx.metrics(range: "15m")` returns the sandbox's measured CPU and memory, and
+`runtime.otel.create(endpoint: ...)` pushes events and metrics to an
+OpenTelemetry endpoint. See [metrics and webhooks](./observability).
+
+## Errors and retries
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new
+begin
+  runtime.sandboxes.get("00000000-0000-4000-8000-000000000000")
+rescue WithRuntime::NotFoundError
+  puts "no such sandbox"
+rescue WithRuntime::Error => e
+  puts e.code, e.hint, e.request_id
+end
+```
+
+Every error is a `WithRuntime::Error` with `code`, `message`, `hint`,
+`request_id`, `status` and `details`. Its subclasses are
+`AuthenticationError`, `PermissionDeniedError`, `NotFoundError`,
+`ConflictError`, `InvalidRequestError`, `RateLimitError`,
+`ServiceUnavailableError`, `ConnectionError` and `CommandError`, the same
+classes as the JavaScript, Python, Go and Java SDKs.
+
+Every write carries an idempotency key, made for you and kept across the
+client's own retries. Transport failures, 429, 502, 503 and 504 are retried
+with the same key, so a retry never makes two sandboxes or runs a command
+twice. `retryable?` says whether trying the same call again may work.
+
+**A create waits for room.** When every trial slot is taken (`trial_busy`), the
+account is at its limit (`quota_exceeded`) or the region is full
+(`no_capacity`), `sandboxes.create` waits and sends the same request again, for
+up to two minutes. Pass `wait_for_capacity:` (seconds) to the client or to one
+create; zero fails at once.
+
+An owner, admin or developer can make a read-only key and set a daily spending
+limit on a key at [API keys](https://withruntime.com/account/keys).
+`runtime.limits.get` reads both; past the limit, a create, wake or extension
+raises with code `spending_limit_reached`, and it is not retried.
+
+## Configuration
+
+```ruby
+require "withruntime"
+
+runtime = WithRuntime::Client.new(
+  api_key: ENV.fetch("MY_RUNTIME_KEY"),
+  timeout: 120,
+  max_retries: 4,
+  wait_for_capacity: 600
+)
+puts runtime.me.org_id
+p runtime.request("GET", "/v1/volumes") # any endpoint, same rules
+```
+
+- `RUNTIME_API_URL` points the client at another API origin, as `base_url:`
+  does.
+- The client is safe to share between threads. It keeps its connections open
+  and holds at most 32 calls in flight (`max_connections:`).
+- It honours `HTTPS_PROXY` and `NO_PROXY`.
+- Money is integer microdollars: 1,000,000 is one US dollar.
+  `runtime.usage.available` is the account's balance as an exact decimal
+  string.

data/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/ 
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

data/lib/withruntime/client.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module WithRuntime
+  DEFAULT_BASE_URL = "https://api.withruntime.com"
+
+  # One client for every Runtime Cloud product. Make it once and share it: it
+  # 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.stop
+  #
+  # Every product is +runtime.<product>.<verb>+. Money is integer microdollars
+  # (1,000,000 is one US dollar).
+  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
+
+    # +api_key+: default RUNTIME_API_KEY, then this machine's saved connection.
+    # +base_url+: default RUNTIME_API_URL, then https://api.withruntime.com.
+    # +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).
+    def initialize(api_key: nil, base_url: nil, timeout: 300, max_retries: 4, max_connections: 32,
+                   wait_for_capacity: 120, env: ENV)
+      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?
+      key ||= Credentials.saved_key(env, origin)
+      raise Error.missing_key if key.nil? || key.empty?
+      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,
+                                 max_connections: max_connections, wait_for_capacity: [0, wait_for_capacity].max)
+      @sandboxes = Sandboxes.new(@transport)
+      @snapshots = Snapshots.new(@transport)
+      @images = Images.new(@transport)
+      @volumes = Volumes.new(@transport)
+      @secrets = Secrets.new(@transport)
+      @limits = Limits.new(@transport)
+      @referrals = Referrals.new(@transport)
+      @switching = Switching.new(@transport)
+      @events = Events.new(@transport)
+      @webhooks = Webhooks.new(@transport)
+      @otel = Otel.new(@transport)
+      @audit = Audit.new(@transport)
+      @feedback = Feedback.new(@transport)
+      @support = Support.new(@transport)
+      @domains = Domains.new(@transport)
+      @ports = Ports.new(@transport)
+      @addresses = Addresses.new(@transport)
+      @tunnel = PrivateTunnel.new(@transport)
+      @sso = SSO.new(@transport)
+      @mcp = MCP.new(@transport)
+    end
+
+    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.
+    def usage = Record.new(@transport.json("GET", "/v1/usage"))
+
+    # Calls any API path with this client's key, retries, idempotency keys and
+    # errors, and returns the parsed JSON answer. For an endpoint newer than this SDK.
+    def request(method, path, query: nil, body: nil)
+      raise ArgumentError, "The path must start with /." unless path.start_with?("/")
+
+      method = method.to_s.upcase
+      body = {} if body.nil? && !%w[GET DELETE].include?(method)
+      @transport.json(method, path, query: query, body: body)
+    end
+  end
+end

data/lib/withruntime/credentials.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "uri"
+
+module WithRuntime
+  # The key `runtime login` saved for this machine. Its file is the CLI's
+  # (packages/cloud-sdk/src/credentials.ts) and is read exactly as the CLI
+  # reads it: only from a private file in a private directory, bound to both
+  # origins.
+  module Credentials
+    KEY = /\Artcloud_[a-f0-9-]{36}_[A-Za-z0-9_-]{43}\z/
+
+    module_function
+
+    # An HTTPS origin, or plain HTTP to localhost for tests, with nothing after the host.
+    def origin(value)
+      uri = URI(value)
+      local = %w[localhost 127.0.0.1 [::1] ::1].include?(uri.host)
+      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)."
+      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)."
+    end
+
+    # Where the CLI keeps this machine's connection for the two origins.
+    def file(env, api_origin, auth_origin)
+      root = env["XDG_CONFIG_HOME"]
+      root = File.join(Dir.home, ".config") if root.nil? || root.empty?
+      raise ArgumentError, "XDG_CONFIG_HOME must be an absolute path." unless root.start_with?("/")
+
+      File.join(root, "runtime-cloud", "#{Digest::SHA256.hexdigest("#{auth_origin}\n#{api_origin}")}.json")
+    end
+
+    # The saved key, or nil when there is none.
+    def saved_key(env, api_origin)
+      auth = env["RUNTIME_AUTH_URL"]
+      auth_origin = origin(auth.nil? || auth.empty? ? "https://withruntime.com" : auth)
+      path = file(env, api_origin, auth_origin)
+      directory = File.dirname(path)
+      begin
+        info = File.lstat(directory)
+      rescue Errno::ENOENT
+        return nil
+      end
+      raise SecurityError, "Runtime's credential directory must be private to your user." unless info.directory? && private?(info)
+
+      text = begin
+        File.open(path, File::RDONLY | File::NOFOLLOW) do |handle|
+          stat = handle.stat
+          raise SecurityError, "Runtime's saved connection must be private to your user." unless stat.file? && stat.size <= 4096 && private?(stat)
+
+          handle.read(4097)
+        end
+      rescue Errno::ENOENT
+        return nil
+      rescue Errno::ELOOP
+        raise SecurityError, "Could not safely open Runtime's saved connection."
+      end
+      saved = JSON.parse(text)
+      unless saved.is_a?(Hash) && saved["version"] == 1 && saved["apiOrigin"] == api_origin &&
+             saved["authOrigin"] == auth_origin && saved["key"].is_a?(String) && KEY.match?(saved["key"]) &&
+             %w[connectionId orgId agentName].all? { |name| saved[name].is_a?(String) }
+        raise ArgumentError, "Runtime's saved connection is invalid. Connect again with `npx withruntime login`."
+      end
+
+      saved["key"]
+    rescue JSON::ParserError
+      raise ArgumentError, "Runtime's saved connection is invalid. Connect again with `npx withruntime login`."
+    end
+
+    def private?(stat)
+      return true if Gem.win_platform?
+
+      (stat.mode & 0o077).zero? && stat.uid == Process.uid
+    end
+  end
+end