xshellz 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fae387e6b5028c2064007a18564008e3e9ee33ecf740f38d038d6e9b37c4b707
+  data.tar.gz: f26c57baadbe0d628c8e9cd24442b3b846303e9747e2f079995f43f7048eaada
+SHA512:
+  metadata.gz: 1356a6f340d78bc8267dea29fc6712680da93660bc5dd9b42f9119593fcb1d39e9b0b48aaa27130cba6a909e96d9dfbc7fe51867c6f00ff8bce84316a398fb93
+  data.tar.gz: 6fd6696f8eb7d23fe0035ae7f0381b0702b6d0dd4d0ce1ce6a31c29871f174450e229ce7b1c37582fdf46f9ce9b2431680cf1782660c15364ce05291194e8f25

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xShellz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,166 @@
+# xshellz
+
+Official Ruby SDK for [xShellz](https://xshellz.com) sandboxes: throwaway,
+gVisor-isolated Linux boxes you can spawn and run commands in from your own
+program - in three lines.
+
+```bash
+gem install xshellz
+```
+
+```ruby
+require "xshellz"
+
+Xshellz::Sandbox.create do |sbx|
+  result = sbx.run("ruby -e 'puts 6*7'")
+  puts result.stdout # 42
+end
+# the box is destroyed when the block exits
+```
+
+Each sandbox is a real Linux box (root shell, package manager, network) running
+under [gVisor](https://gvisor.dev) kernel isolation. Spawning is synchronous -
+`Sandbox.create` returns once the box is running, typically in a few seconds.
+
+## Authentication
+
+The SDK authenticates with an xShellz personal access token (PAT) carrying the
+`read` and `write` scopes:
+
+1. Create a token from your [xShellz dashboard](https://app.xshellz.com)
+   (Settings -> API tokens), or via the API: `POST /v1/auth/tokens`.
+2. Export it:
+
+```bash
+export XSHELLZ_API_KEY="your-token"
+```
+
+or pass it explicitly: `Xshellz::Sandbox.create(api_key: "your-token")`.
+
+Config precedence: explicit argument > `XSHELLZ_API_KEY` / `XSHELLZ_API_URL`
+environment variables > default (`https://api.xshellz.com/v1`).
+
+To target a staging or self-hosted control plane:
+
+```bash
+export XSHELLZ_API_URL="https://api.staging.example.com/v1"
+```
+
+## Usage
+
+### Run commands
+
+```ruby
+Xshellz::Sandbox.create(name: "build-box") do |sbx|
+  r = sbx.run("apt-get update && apt-get install -y jq", timeout: 300)
+  puts r.exit_code, r.stdout, r.stderr
+
+  # A non-zero exit code does NOT raise - it's data:
+  r = sbx.run("false")
+  r.exit_code # => 1
+  r.ok?       # => false
+
+  # cwd and env:
+  sbx.run("make test", cwd: "/srv/app", env: { "CI" => "1" })
+
+  # Stream long-running output as it arrives:
+  sbx.run("npm run build") do |stream, chunk|
+    warn(chunk) if stream == :stderr
+    print(chunk) if stream == :stdout
+  end
+end
+```
+
+### Files (SFTP)
+
+```ruby
+sbx.write_file("/tmp/config.json", '{"debug": true}')
+data = sbx.read_file("/tmp/config.json") # => String
+
+sbx.upload("local.txt", "/tmp/remote.txt")
+sbx.download("/tmp/remote.txt", "out.txt")
+```
+
+### Lifecycle
+
+```ruby
+sbx.uuid         # sandbox id
+sbx.ssh_host     # e.g. "shellus1.xshellz.com"
+sbx.ssh_port     # e.g. 42001
+sbx.ssh_command  # ready-to-copy "ssh -p 42001 root@..."
+sbx.status       # "running", "stopped", ...
+
+sbx.detach       # keep the box alive after the create block
+sbx.kill         # destroy the box explicitly
+sbx.start        # resume an idle-stopped box
+
+# Non-block form: you own the lifecycle.
+sbx = Xshellz::Sandbox.create
+sbx.run("uname -a")
+sbx.kill
+
+# Re-attach later (persist sbx.private_key_openssh + sbx.uuid for this):
+sbx = Xshellz::Sandbox.connect(uuid, private_key: saved_private_key)
+
+# Enumerate your sandboxes:
+Xshellz::Sandbox.list.each do |info|
+  puts "#{info.uuid} #{info.status}"
+end
+```
+
+### Typed errors
+
+```ruby
+begin
+  sbx = Xshellz::Sandbox.create
+rescue Xshellz::QuotaError
+  # plan limit reached - attach to the existing box instead
+  existing = Xshellz::Sandbox.list.first
+  sbx = Xshellz::Sandbox.connect(existing.uuid, private_key: saved_key)
+rescue Xshellz::AuthError => e
+  puts e.message # missing/invalid token, scope, or account verification
+end
+```
+
+- `Xshellz::Error` - base class for everything the SDK raises
+- `Xshellz::AuthError` - 401/403: bad or missing token, scopes, account gates
+- `Xshellz::QuotaError` - plan sandbox limit reached / plan has no sandbox entitlement
+- `Xshellz::SandboxNotRunningError` - operation needs a `running` box
+- `Xshellz::CommandTimeoutError` - `run(timeout: ...)` exceeded
+- `Xshellz::ApiError` - any other 4xx/5xx (carries `.status` and `.body`)
+
+## How it works
+
+- **Control plane**: HTTPS to `api.xshellz.com/v1` (create / list / start /
+  destroy), authenticated by your PAT.
+- **Data plane**: SSH directly to the box as `root` (net-ssh), files over
+  SFTP (net-sftp). `Sandbox.create` generates an in-memory ed25519 keypair
+  per sandbox; the private key never leaves your process and the server never
+  sees it - only the public half is installed in the box's `authorized_keys`.
+- **Host keys are auto-accepted** (`verify_host_key: :never`). Sandbox host
+  keys are generated at spawn time, so there is no out-of-band fingerprint to
+  pin. If your threat model requires host-key verification, connect manually
+  with your own SSH tooling using `sbx.ssh_command`.
+
+## v0 limits
+
+- **Free tier: 1 concurrent sandbox.** A second `Sandbox.create` raises
+  `Xshellz::QuotaError` while one exists - use `Sandbox.list` +
+  `Sandbox.connect` to attach to the existing box, or `kill` it first. Paid
+  plans raise the limit.
+- **Free boxes idle-stop after ~30 minutes.** The box (its `/home` and your
+  key) is preserved; call `sbx.start` to resume it.
+- Sandbox creation is throttled to 10 requests/minute per account.
+
+## Local development (Docker)
+
+No local Ruby toolchain is required - the whole test suite runs inside a
+`ruby:3.3` container (gems cached in a named volume):
+
+```bash
+docker compose run --rm test
+```
+
+## License
+
+MIT

data/lib/xshellz/client.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Xshellz
+  # Default HTTP adapter: one Net::HTTP request per call.
+  #
+  # Any object responding to +call(method, url, headers, body)+ and returning
+  # something with +status+ (Integer) and +body+ (String) can replace it -
+  # specs inject a fake so no test ever touches the network.
+  class NetHttpAdapter
+    def initialize(open_timeout: 10, read_timeout: 120)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    def call(method, url, headers, body)
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @open_timeout
+      http.read_timeout = @read_timeout
+
+      request = Net::HTTP.const_get(method.capitalize).new(uri.request_uri, headers)
+      request.body = body unless body.nil?
+
+      response = http.request(request)
+      Client::Response.new(status: response.code.to_i, body: response.body.to_s)
+    end
+  end
+
+  # Bearer-authenticated JSON client for the xShellz control plane
+  # (+https://api.xshellz.com/v1+) with typed error mapping.
+  class Client
+    Response = Struct.new(:status, :body, keyword_init: true)
+
+    DEFAULT_API_URL = "https://api.xshellz.com/v1"
+    API_KEY_ENV = "XSHELLZ_API_KEY"
+    API_URL_ENV = "XSHELLZ_API_URL"
+
+    # 403 message fragments emitted by the control plane's guard chain. All
+    # guards abort(403, message); quota/entitlement are distinguished by
+    # message text.
+    QUOTA_FRAGMENTS = [
+      "agent shell limit", # "You've reached your plan's agent shell limit (N)."
+      "plan does not include agent shells" # entitlement gate
+    ].freeze
+
+    attr_reader :api_url
+
+    def initialize(api_key: nil, api_url: nil, http: nil)
+      @api_key = self.class.resolve_api_key(api_key)
+      @api_url = self.class.resolve_api_url(api_url)
+      @http = http || NetHttpAdapter.new
+    end
+
+    # Resolve the API key (explicit argument > environment) or raise a
+    # helpful AuthError.
+    def self.resolve_api_key(api_key = nil)
+      key = (api_key || ENV[API_KEY_ENV] || "").strip
+      return key unless key.empty?
+
+      raise AuthError,
+            "No xShellz API key found. Pass api_key: ... or set the " \
+            "#{API_KEY_ENV} environment variable. Create a personal access " \
+            "token with `read` and `write` scopes from your xShellz dashboard " \
+            "(Settings -> API tokens) or via POST /v1/auth/tokens."
+    end
+
+    # Resolve the API base URL (explicit argument > environment > default),
+    # with no trailing slash.
+    def self.resolve_api_url(api_url = nil)
+      url = api_url || ENV[API_URL_ENV] || DEFAULT_API_URL
+      url = url.strip
+      url = DEFAULT_API_URL if url.empty?
+      url.sub(%r{/+\z}, "")
+    end
+
+    def get(path)
+      request("GET", path)
+    end
+
+    def post(path, body = nil)
+      request("POST", path, body)
+    end
+
+    def delete(path)
+      request("DELETE", path)
+    end
+
+    # Issue a request; return the parsed JSON body or raise a typed error.
+    def request(method, path, body = nil)
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => "xshellz-ruby/#{VERSION}"
+      }
+      headers["Content-Type"] = "application/json" unless body.nil?
+
+      response = @http.call(method, "#{@api_url}#{path}", headers, body.nil? ? nil : JSON.generate(body))
+      raise map_error(response) if response.status >= 400
+      return nil if response.body.nil? || response.body.empty?
+
+      JSON.parse(response.body)
+    end
+
+    private
+
+    def map_error(response)
+      status = response.status
+      body = parse_body(response.body)
+
+      message = ""
+      error_code = ""
+      if body.is_a?(Hash)
+        message = (body["message"] || "").to_s
+        error_code = (body["error"] || "").to_s
+      end
+      message = response.body.to_s if message.empty?
+      message = "HTTP #{status}" if message.empty?
+
+      case status
+      when 401
+        AuthError.new(
+          "Authentication failed (401): the API key is missing, invalid, " \
+          "expired, or revoked. Create a personal access token with `read` " \
+          "and `write` scopes from your xShellz dashboard (Settings -> API " \
+          "tokens) or via POST /v1/auth/tokens. Server said: #{message}"
+        )
+      when 403
+        map_forbidden(message, error_code)
+      when 429
+        ApiError.new(
+          "Rate limited (429): #{message} - sandbox creation is throttled " \
+          "to 10 requests/minute.",
+          status: status,
+          body: body
+        )
+      else
+        ApiError.new("HTTP #{status}: #{message}", status: status, body: body)
+      end
+    end
+
+    def map_forbidden(message, error_code)
+      lowered = message.downcase
+      if QUOTA_FRAGMENTS.any? { |fragment| lowered.include?(fragment) }
+        return QuotaError.new(
+          "#{message} Tip: on the free tier only one sandbox may exist at a " \
+          "time - use Sandbox.list and Sandbox.connect to attach to the " \
+          "existing box, or kill it first."
+        )
+      end
+      return AuthError.new("Account verification required (403): #{message}") if error_code == "verification_required"
+
+      AuthError.new("Forbidden (403): #{message}")
+    end
+
+    def parse_body(raw)
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      raw
+    end
+  end
+end

data/lib/xshellz/errors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Xshellz
+  # Base class for every error raised by the xShellz SDK.
+  class Error < StandardError; end
+
+  # Authentication or authorization failed (HTTP 401/403).
+  #
+  # Raised for a missing/invalid API key, insufficient token scopes, account
+  # verification requirements, and other access gates.
+  class AuthError < Error; end
+
+  # The account's sandbox quota or plan entitlement blocks the operation.
+  #
+  # The control plane returns HTTP 403 both when the plan's concurrent sandbox
+  # limit is reached ("agent shell limit") and when the plan does not include
+  # sandboxes at all. On the free tier the limit is 1 concurrent box - use
+  # +Sandbox.list+ + +Sandbox.connect+ to attach to the existing one instead
+  # of creating a new box.
+  class QuotaError < Error; end
+
+  # The sandbox is not in the +running+ state (or no longer exists).
+  class SandboxNotRunningError < Error; end
+
+  # A command executed with +run(timeout: ...)+ exceeded its deadline.
+  class CommandTimeoutError < Error; end
+
+  # Any other non-success API response (4xx/5xx).
+  #
+  # Carries the HTTP +status+ and the parsed JSON +body+ (or the raw text when
+  # the response was not JSON).
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status:, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+end

data/lib/xshellz/keys.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "ed25519"
+require "securerandom"
+
+module Xshellz
+  # In-memory ed25519 SSH keypair generation.
+  #
+  # The keypair is generated per +Sandbox.create+ and never touches disk; the
+  # control plane only ever sees the public half. Both halves are encoded by
+  # hand (RFC 4253 public line, openssh-key-v1 private container) so the
+  # private key can be handed to net-ssh via +key_data+ without any file IO.
+  module Keys
+    # An in-memory ed25519 keypair.
+    #
+    # +private_key_openssh+ is the private key in OpenSSH format
+    # (-----BEGIN OPENSSH PRIVATE KEY-----). Persist it if you plan to
+    # +detach+ and +Sandbox.connect+ again later from another process.
+    # +public_key_line+ is the single-line OpenSSH public key
+    # (+ssh-ed25519 <base64> <comment>+) sent to the control plane.
+    KeyPair = Struct.new(:private_key_openssh, :public_key_line, keyword_init: true)
+
+    DEFAULT_KEY_COMMENT = "xshellz-sdk"
+    AUTH_MAGIC = "openssh-key-v1\0"
+    KEY_TYPE = "ssh-ed25519"
+    BLOCK_SIZE = 8
+
+    module_function
+
+    # Generate a fresh in-memory ed25519 keypair.
+    #
+    # @return [KeyPair]
+    def generate(comment: DEFAULT_KEY_COMMENT)
+      signing_key = Ed25519::SigningKey.generate
+      seed = signing_key.to_bytes
+      public_bytes = signing_key.verify_key.to_bytes
+
+      line = "#{KEY_TYPE} #{base64(public_key_blob(public_bytes))}"
+      line = "#{line} #{comment}" unless comment.to_s.empty?
+
+      KeyPair.new(
+        private_key_openssh: encode_openssh_private_key(seed, public_bytes, comment.to_s),
+        public_key_line: line
+      )
+    end
+
+    # The RFC 4253 public key blob: string "ssh-ed25519" + string key-bytes.
+    def public_key_blob(public_bytes)
+      ssh_string(KEY_TYPE) + ssh_string(public_bytes)
+    end
+
+    # A length-prefixed SSH wire string.
+    def ssh_string(value)
+      [value.bytesize].pack("N") + value.dup.force_encoding(Encoding::BINARY)
+    end
+
+    # Serialize the private key into the openssh-key-v1 container (unencrypted:
+    # cipher "none", kdf "none") - the format ssh-keygen writes and the one
+    # net-ssh's ED25519 support parses from +key_data+.
+    def encode_openssh_private_key(seed, public_bytes, comment)
+      check = SecureRandom.bytes(4)
+
+      section = "".b
+      section << check << check
+      section << ssh_string(KEY_TYPE)
+      section << ssh_string(public_bytes)
+      section << ssh_string(seed + public_bytes)
+      section << ssh_string(comment)
+      pad = 1
+      until (section.bytesize % BLOCK_SIZE).zero?
+        section << [pad].pack("C")
+        pad += 1
+      end
+
+      blob = "".b
+      blob << AUTH_MAGIC.b
+      blob << ssh_string("none") # ciphername
+      blob << ssh_string("none") # kdfname
+      blob << ssh_string("")     # kdfoptions
+      blob << [1].pack("N")      # number of keys
+      blob << ssh_string(public_key_blob(public_bytes))
+      blob << ssh_string(section)
+
+      body = base64(blob).scan(/.{1,70}/).join("\n")
+      "-----BEGIN OPENSSH PRIVATE KEY-----\n#{body}\n-----END OPENSSH PRIVATE KEY-----\n"
+    end
+
+    # Strict (unwrapped) base64 without pulling in the base64 gem.
+    def base64(data)
+      [data].pack("m0")
+    end
+  end
+end

data/lib/xshellz/models.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Xshellz
+  # The outcome of a single +Sandbox#run+ invocation.
+  #
+  # A non-zero +exit_code+ does NOT raise - it is data, exactly like a local
+  # subprocess call.
+  CommandResult = Struct.new(:stdout, :stderr, :exit_code, keyword_init: true) do
+    # True when the command exited with status 0.
+    def ok?
+      exit_code == 0
+    end
+  end
+
+  # A sandbox as reported by the control plane (snake_case wire shape).
+  SandboxInfo = Struct.new(
+    :uuid,
+    :name,
+    :status,
+    :ssh_command,
+    :ssh_host,
+    :ssh_port,
+    :web_terminal_ready,
+    :always_on,
+    :trial_hours_remaining,
+    :spawned_at,
+    :created_at,
+    :isolation,
+    :gvisor,
+    keyword_init: true
+  ) do
+    # Build a +SandboxInfo+ from the API's JSON payload.
+    #
+    # Tolerant of missing keys so a newer/older API version never breaks
+    # deserialization.
+    def self.from_api(payload)
+      payload ||= {}
+      port = payload["ssh_port"]
+      new(
+        uuid: payload["uuid"].to_s,
+        name: payload["name"].to_s,
+        status: payload["status"].to_s,
+        ssh_command: payload["ssh_command"],
+        ssh_host: payload["ssh_host"],
+        ssh_port: port.nil? ? nil : Integer(port),
+        web_terminal_ready: !!payload["web_terminal_ready"],
+        always_on: !!payload["always_on"],
+        trial_hours_remaining: (payload["trial_hours_remaining"] || 0.0).to_f,
+        spawned_at: payload["spawned_at"],
+        created_at: payload["created_at"],
+        isolation: payload["isolation"],
+        gvisor: !!payload["gvisor"]
+      )
+    end
+  end
+end

data/lib/xshellz/sandbox.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module Xshellz
+  # A remote sandbox: control plane over HTTPS, data plane over SSH.
+  #
+  # Create one with +Sandbox.create+, attach to an existing one with
+  # +Sandbox.connect+, or enumerate them with +Sandbox.list+.
+  #
+  # The block form destroys the sandbox when the block exits, unless
+  # +detach+ was called:
+  #
+  #   Xshellz::Sandbox.create do |sbx|
+  #     result = sbx.run("echo hello")
+  #   end
+  class Sandbox
+    STATUS_RUNNING = "running"
+
+    # The last-known control-plane state (a SandboxInfo).
+    attr_reader :info
+
+    # OpenSSH serialization of the private key authenticating this sandbox's
+    # SSH (persist it to reconnect later via +Sandbox.connect+).
+    attr_reader :private_key_openssh
+
+    def initialize(info:, client:, private_key_openssh: nil, transport: nil)
+      @info = info
+      @client = client
+      @private_key_openssh = private_key_openssh
+      @transport = transport
+      @detached = false
+      @killed = false
+    end
+
+    # ------------------------------------------------------------------ #
+    # Constructors (control plane)
+    # ------------------------------------------------------------------ #
+
+    # Spawn a new sandbox and return it once it is RUNNING.
+    #
+    # An in-memory ed25519 keypair is generated for the box; the private key
+    # never leaves this process and the server never sees it. Spawning is
+    # synchronous - the box is reachable when this returns.
+    #
+    # With a block, the sandbox is yielded and destroyed when the block
+    # exits (unless +detach+ was called); the block's value is returned.
+    #
+    # Raises AuthError (missing/invalid API key, insufficient scope, or an
+    # account gate), QuotaError (the plan's concurrent sandbox limit is
+    # reached or the plan has no sandbox entitlement), or ApiError (other
+    # API failures: throttle 429, host capacity 503, ...).
+    def self.create(name: nil, api_key: nil, api_url: nil, http: nil)
+      keypair = Keys.generate
+      client = Client.new(api_key: api_key, api_url: api_url, http: http)
+
+      body = { "ssh_public_key" => keypair.public_key_line }
+      body["name"] = name unless name.nil?
+      payload = client.post("/shells/agent", body)
+
+      sandbox = new(
+        info: SandboxInfo.from_api(payload),
+        client: client,
+        private_key_openssh: keypair.private_key_openssh
+      )
+      return sandbox unless block_given?
+
+      begin
+        yield sandbox
+      ensure
+        sandbox.kill unless sandbox.detached?
+        sandbox.close
+      end
+    end
+
+    # Attach to an existing sandbox by UUID.
+    #
+    # +private_key+ is the OpenSSH-format private key whose public half the
+    # box was created with (the +private_key_openssh+ of the original
+    # sandbox).
+    def self.connect(uuid, private_key:, api_key: nil, api_url: nil, http: nil)
+      Ssh.load_private_key!(private_key)
+      client = Client.new(api_key: api_key, api_url: api_url, http: http)
+      info = find(client, uuid)
+      new(info: info, client: client, private_key_openssh: private_key)
+    end
+
+    # List the account's active sandboxes (a bare array on the wire).
+    #
+    # @return [Array<SandboxInfo>]
+    def self.list(api_key: nil, api_url: nil, http: nil)
+      client = Client.new(api_key: api_key, api_url: api_url, http: http)
+      client.get("/shells/agent").map { |item| SandboxInfo.from_api(item) }
+    end
+
+    # Resolve one sandbox via the list endpoint (there is no GET show route).
+    def self.find(client, uuid)
+      client.get("/shells/agent").each do |item|
+        info = SandboxInfo.from_api(item)
+        return info if info.uuid == uuid
+      end
+      raise SandboxNotRunningError,
+            "Sandbox #{uuid} was not found among this account's active sandboxes."
+    end
+
+    # ------------------------------------------------------------------ #
+    # Properties
+    # ------------------------------------------------------------------ #
+
+    def uuid
+      @info.uuid
+    end
+
+    def name
+      @info.name
+    end
+
+    def status
+      @info.status
+    end
+
+    def ssh_host
+      @info.ssh_host
+    end
+
+    def ssh_port
+      @info.ssh_port
+    end
+
+    def ssh_command
+      @info.ssh_command
+    end
+
+    def detached?
+      @detached
+    end
+
+    # ------------------------------------------------------------------ #
+    # Data plane (SSH/SFTP)
+    # ------------------------------------------------------------------ #
+
+    # Run a shell command in the sandbox and wait for it to finish.
+    #
+    # A non-zero exit code does NOT raise - inspect +result.exit_code+. An
+    # optional block receives (:stdout | :stderr, chunk) as output arrives
+    # (the full output is still returned in the result).
+    #
+    # Raises SandboxNotRunningError when the box is not +running+, and
+    # CommandTimeoutError when +timeout+ seconds elapse before exit.
+    #
+    # @return [CommandResult]
+    def run(command, cwd: nil, env: nil, timeout: nil, &block)
+      transport.exec(Ssh.build_shell_command(command, cwd: cwd, env: env), timeout: timeout, &block)
+    end
+
+    # Write +data+ to +path+ inside the sandbox (SFTP).
+    def write_file(path, data)
+      transport.write_file(path, data)
+    end
+
+    # Read and return the contents of +path+ inside the sandbox (SFTP).
+    def read_file(path)
+      transport.read_file(path)
+    end
+
+    # Upload a local file into the sandbox (SFTP).
+    def upload(local_path, remote_path)
+      transport.upload(local_path, remote_path)
+    end
+
+    # Download a file from the sandbox to a local path (SFTP).
+    def download(remote_path, local_path)
+      transport.download(remote_path, local_path)
+    end
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle (control plane)
+    # ------------------------------------------------------------------ #
+
+    # Resume an idle-stopped box (+POST /shells/agent/{uuid}/start+).
+    #
+    # Free-tier boxes idle-stop after ~30 minutes; this brings the same box
+    # (same /home, same authorized key) back to +running+.
+    def start
+      begin
+        payload = @client.post("/shells/agent/#{uuid}/start")
+      rescue ApiError => e
+        if e.status == 404
+          raise SandboxNotRunningError,
+                "Sandbox #{uuid} has no stopped box to start - it may " \
+                "already be running, suspended, or deleted."
+        end
+        raise
+      end
+      @info = SandboxInfo.from_api(payload)
+      close_transport
+      self
+    end
+
+    # Destroy the sandbox (+DELETE /shells/agent/{uuid}+). Idempotent: a 404
+    # (already gone) is swallowed.
+    def kill
+      close_transport
+      return if @killed
+
+      begin
+        @client.delete("/shells/agent/#{uuid}")
+      rescue ApiError => e
+        raise unless e.status == 404
+      end
+      @killed = true
+      nil
+    end
+
+    # Keep the sandbox alive when the +create+ block exits.
+    #
+    # Persist +private_key_openssh+ and +uuid+ to re-attach later with
+    # +Sandbox.connect+.
+    def detach
+      @detached = true
+      self
+    end
+
+    # Re-fetch this sandbox's state from the control plane.
+    def refresh
+      @info = self.class.find(@client, uuid)
+    end
+
+    # Close the SSH connection (keeps the box alive).
+    def close
+      close_transport
+      nil
+    end
+
+    def inspect
+      "#<Xshellz::Sandbox uuid=#{uuid.inspect} status=#{status.inspect} ssh=#{ssh_host}:#{ssh_port}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def transport
+      return @transport unless @transport.nil?
+
+      unless status == STATUS_RUNNING
+        raise SandboxNotRunningError,
+              "Sandbox #{uuid} is #{status.inspect}, not 'running'. " \
+              "Call start to resume an idle-stopped box."
+      end
+      if ssh_host.nil? || ssh_port.nil?
+        raise SandboxNotRunningError,
+              "Sandbox #{uuid} has no SSH endpoint yet (host/port unknown)."
+      end
+      if @private_key_openssh.nil?
+        raise Error,
+              "No private key available for this sandbox - attach with " \
+              "Sandbox.connect(uuid, private_key: ...)."
+      end
+
+      @transport = Ssh::NetSshTransport.new(
+        host: ssh_host,
+        port: ssh_port,
+        private_key_openssh: @private_key_openssh
+      )
+    end
+
+    def close_transport
+      @transport&.close
+      @transport = nil
+    end
+  end
+end

data/lib/xshellz/ssh.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "net/ssh"
+require "net/sftp"
+require "shellwords"
+require "stringio"
+
+module Xshellz
+  # SSH/SFTP data plane, behind a small transport interface for testability.
+  #
+  # The real implementation (NetSshTransport) speaks SSH as +root+ to the
+  # sandbox. Host keys are auto-accepted (+verify_host_key: :never+):
+  # sandboxes are throwaway boxes whose host keys are generated at spawn
+  # time, so there is no out-of-band fingerprint to pin against.
+  module Ssh
+    ENV_NAME = /\A[A-Za-z_][A-Za-z0-9_]*\z/
+
+    # Wrap a command with optional +cd+ and environment exports.
+    #
+    # Environment variable names are validated (sshd rarely honours
+    # +AcceptEnv+, so variables are exported in the remote shell instead).
+    def self.build_shell_command(command, cwd: nil, env: nil)
+      parts = []
+      if env && !env.empty?
+        exports = env.map do |key, value|
+          raise Error, "Invalid environment variable name: #{key.inspect}" unless key.to_s.match?(ENV_NAME)
+
+          "#{key}=#{Shellwords.escape(value.to_s)}"
+        end
+        parts << "export #{exports.join(" ")}"
+      end
+      parts << "cd #{Shellwords.escape(cwd)}" if cwd
+      parts << command
+      parts.join(" && ")
+    end
+
+    # Load/validate an OpenSSH-format private key string; raises a helpful
+    # Xshellz::Error when it cannot be parsed.
+    def self.load_private_key!(private_key)
+      Net::SSH::KeyFactory.load_data_private_key(private_key.to_s, nil, false)
+    rescue StandardError => e
+      raise Error,
+            "Could not load the private key. Expected an unencrypted " \
+            "OpenSSH-format private key (e.g. Sandbox#private_key_openssh). " \
+            "Details: #{e.class}: #{e.message}"
+    end
+
+    # Real SSH transport: exec over a session channel, files over SFTP.
+    #
+    # The private key is handed to net-ssh in memory via +key_data+ - it
+    # never touches disk. Requires the ed25519 + bcrypt_pbkdf gems (declared
+    # as runtime dependencies) for net-ssh to accept ed25519 keys.
+    class NetSshTransport
+      POLL_INTERVAL = 0.02
+
+      def initialize(host:, port:, private_key_openssh:, username: "root", connect_timeout: 30)
+        @ssh = Net::SSH.start(
+          host,
+          username,
+          port: port,
+          key_data: [private_key_openssh],
+          keys: [],
+          keys_only: true,
+          auth_methods: ["publickey"],
+          non_interactive: true,
+          # Sandbox host keys are minted at spawn time; nothing to pin against.
+          verify_host_key: :never,
+          timeout: connect_timeout
+        )
+        @sftp = nil
+      end
+
+      # Execute a command; optional block receives (:stdout | :stderr, chunk)
+      # as output arrives. Returns a CommandResult; a non-zero exit code does
+      # NOT raise.
+      def exec(command, timeout: nil, &block)
+        stdout = +""
+        stderr = +""
+        exit_code = nil
+
+        channel = @ssh.open_channel do |ch|
+          ch.exec(command) do |_, success|
+            raise Error, "Failed to start command on the sandbox: #{command.inspect}" unless success
+
+            ch.on_data do |_, data|
+              stdout << data
+              block&.call(:stdout, data)
+            end
+            ch.on_extended_data do |_, _type, data|
+              stderr << data
+              block&.call(:stderr, data)
+            end
+            ch.on_request("exit-status") do |_, buffer|
+              exit_code = buffer.read_long
+            end
+          end
+        end
+
+        deadline = timeout && (monotonic + timeout)
+        timed_out = false
+        @ssh.loop(POLL_INTERVAL) do
+          timed_out = !deadline.nil? && monotonic > deadline
+          channel.active? && !timed_out
+        end
+
+        if timed_out && channel.active?
+          close_channel_quietly(channel)
+          raise CommandTimeoutError,
+                "Command did not finish within #{timeout} seconds: #{command.inspect}"
+        end
+
+        CommandResult.new(stdout: stdout, stderr: stderr, exit_code: exit_code || -1)
+      end
+
+      def read_file(path)
+        sftp.download!(path)
+      end
+
+      def write_file(path, data)
+        sftp.upload!(StringIO.new(data), path)
+        nil
+      end
+
+      def upload(local_path, remote_path)
+        sftp.upload!(local_path, remote_path)
+        nil
+      end
+
+      def download(remote_path, local_path)
+        sftp.download!(remote_path, local_path)
+        nil
+      end
+
+      def close
+        @sftp = nil
+        @ssh.close unless @ssh.closed?
+      end
+
+      private
+
+      def sftp
+        @sftp ||= Net::SFTP::Session.new(@ssh).connect!
+      end
+
+      def monotonic
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def close_channel_quietly(channel)
+        channel.close
+        @ssh.loop(POLL_INTERVAL) { channel.active? }
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/xshellz/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Xshellz
+  VERSION = "0.1.0"
+end

data/lib/xshellz.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "xshellz/version"
+require_relative "xshellz/errors"
+require_relative "xshellz/models"
+require_relative "xshellz/keys"
+require_relative "xshellz/client"
+require_relative "xshellz/ssh"
+require_relative "xshellz/sandbox"
+
+# xShellz Ruby SDK - throwaway, gVisor-isolated Linux sandboxes.
+#
+# Quickstart:
+#
+#   require "xshellz"
+#
+#   Xshellz::Sandbox.create do |sbx|
+#     result = sbx.run("ruby -e 'puts 6*7'")
+#     puts result.stdout # "42"
+#   end
+module Xshellz
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: xshellz
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- xShellz
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bcrypt_pbkdf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: ed25519
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: net-sftp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: net-ssh
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Spawn throwaway, gVisor-isolated Linux sandboxes and run commands in
+  them from your own program - control plane over HTTPS, data plane over SSH/SFTP.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/xshellz.rb
+- lib/xshellz/client.rb
+- lib/xshellz/errors.rb
+- lib/xshellz/keys.rb
+- lib/xshellz/models.rb
+- lib/xshellz/sandbox.rb
+- lib/xshellz/ssh.rb
+- lib/xshellz/version.rb
+homepage: https://github.com/xshellz/xshellz-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/xshellz/xshellz-ruby
+  source_code_uri: https://github.com/xshellz/xshellz-ruby
+  changelog_uri: https://github.com/xshellz/xshellz-ruby/releases
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for xShellz sandboxes.
+test_files: []