xshellz 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fae387e6b5028c2064007a18564008e3e9ee33ecf740f38d038d6e9b37c4b707
-  data.tar.gz: f26c57baadbe0d628c8e9cd24442b3b846303e9747e2f079995f43f7048eaada
+  metadata.gz: 23f86718f159f861cc34d791397cbfdb0aea3c106e24073d976caf20ac5ba014
+  data.tar.gz: c3048208aac6d5622c482cf33b812e9c8108e48bfdd29a43bf715530b88c75d1
 SHA512:
-  metadata.gz: 1356a6f340d78bc8267dea29fc6712680da93660bc5dd9b42f9119593fcb1d39e9b0b48aaa27130cba6a909e96d9dfbc7fe51867c6f00ff8bce84316a398fb93
-  data.tar.gz: 6fd6696f8eb7d23fe0035ae7f0381b0702b6d0dd4d0ce1ce6a31c29871f174450e229ce7b1c37582fdf46f9ce9b2431680cf1782660c15364ce05291194e8f25
+  metadata.gz: 2a9b1d1545c1c6df00e08134e432bc9fa3a9a07d5abbca41e4b2cc552c1e13a318911bad5d9cd46c3b510d404ce72e3bed56a5ecfc9370bd2b3541d0a78a88cf
+  data.tar.gz: 8e83a370828f5cd052b195045bae0c127262dc811c919ebce0f9aa111fd7d8b29fc8d1c2afe31124d6e941abff051bec4d228e50814796cb8c6485cbc752fd97

data/README.md

@@ -1,138 +1,196 @@
 # 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.
+[![CI](https://github.com/xshellz/xshellz-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/xshellz/xshellz-ruby/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/xshellz)](https://rubygems.org/gems/xshellz)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-```bash
-gem install xshellz
-```
+The official Ruby SDK for [xShellz](https://xshellz.com) sandboxes: spawn a
+real Linux box from your program, run anything in it, throw it away.
 
-```ruby
-require "xshellz"
+**What is a sandbox?** A sandbox is a small, disposable Linux computer that
+runs in the cloud, isolated from everything else (including your machine), so
+whatever runs inside it cannot touch your files or your network. That makes it
+the safe place to run untrusted things: AI-generated code, build scripts,
+scrapers, other people's projects.
 
-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 xShellz sandbox is a full Linux environment - root shell, package
+manager, network access - running under
+[gVisor](https://gvisor.dev) kernel isolation. Spawning is synchronous:
+`Sandbox.create` returns once the box is reachable, typically in a few
+seconds.
 
-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.
+## Quickstart
 
-## Authentication
+1. **Install the gem:**
 
-The SDK authenticates with an xShellz personal access token (PAT) carrying the
-`read` and `write` scopes:
+   ```bash
+   gem install xshellz
+   ```
 
-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:
+2. **Get an API key.** Sign up at [app.xshellz.com](https://app.xshellz.com),
+   then create a personal access token with `read` and `write` scopes under
+   Settings -> API tokens (or via the API: `POST /v1/auth/tokens`). Export it:
 
-```bash
-export XSHELLZ_API_KEY="your-token"
-```
+   ```bash
+   export XSHELLZ_API_KEY="your-token"
+   ```
 
-or pass it explicitly: `Xshellz::Sandbox.create(api_key: "your-token")`.
+3. **Hello world:**
 
-Config precedence: explicit argument > `XSHELLZ_API_KEY` / `XSHELLZ_API_URL`
-environment variables > default (`https://api.xshellz.com/v1`).
+   ```ruby
+   require "xshellz"
 
-To target a staging or self-hosted control plane:
+   Xshellz::Sandbox.create do |sbx|
+     puts sbx.run("echo hello from $(hostname)").stdout
+   end
+   # the box is destroyed when the block exits
+   ```
 
-```bash
-export XSHELLZ_API_URL="https://api.staging.example.com/v1"
-```
+## Recipes
 
-## Usage
-
-### Run commands
+### Run a command
 
 ```ruby
-Xshellz::Sandbox.create(name: "build-box") do |sbx|
+Xshellz::Sandbox.create 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
+  # A non-zero exit code does NOT raise - it's data, like a local subprocess:
+  sbx.run("false").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
+  # cwd, env, and live output streaming:
+  sbx.run("make test", cwd: "/srv/app", env: { "CI" => "1" }) do |stream, chunk|
     print(chunk) if stream == :stdout
   end
 end
 ```
 
-### Files (SFTP)
+### A permanent named box that survives restarts
+
+`get_or_create` finds your box by name, or creates it, and remembers the SSH
+key for you in `~/.xshellz/keys/` - so the same line works on every run, from
+any process, forever:
+
+```ruby
+sbx = Xshellz::Sandbox.get_or_create("my-dev-box")
+sbx.run("echo persists across runs > ~/note.txt")
+# ... later, in a different script or on a different day:
+sbx = Xshellz::Sandbox.get_or_create("my-dev-box") # same box, same files
+```
+
+A stopped (idled) box is started automatically. Keys are plaintext files with
+`0600` permissions - delete the key file and `kill` the box to revoke, or pass
+`keystore: false` to keep keys purely in memory.
+
+### Run a background job
+
+`spawn` starts a process that keeps running after your script disconnects:
+
+```ruby
+job = sbx.spawn("python3 train.py", name: "train")
+job.pid       # => 4242
+job.running?  # => true
+job.logs(tail_lines: 20) # last 20 lines of combined stdout+stderr
+job.stop      # SIGTERM, then SIGKILL after a grace period
+
+sbx.jobs.each { |j| puts "#{j.id} running=#{j.running?}" }
+```
+
+### Run AI-generated code safely
+
+`run_code` writes a snippet to a temp file in the sandbox, executes the right
+interpreter, and always cleans the file up. If the code is malicious, it can
+only harm a disposable box:
+
+```ruby
+result = sbx.run_code("python", generated_code, timeout: 60)
+puts result.stdout
+```
+
+Supported languages: `python` (python3), `node`, `bash`, `ruby`, `php`.
+
+### Files: up and down
 
 ```ruby
 sbx.write_file("/tmp/config.json", '{"debug": true}')
-data = sbx.read_file("/tmp/config.json") # => String
+sbx.read_file("/tmp/config.json") # => String
 
 sbx.upload("local.txt", "/tmp/remote.txt")
 sbx.download("/tmp/remote.txt", "out.txt")
 ```
 
-### Lifecycle
+### Check resource usage
 
 ```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
+stats = sbx.stats
+puts "mem #{stats.mem_used_mb}/#{stats.mem_allowed_mb} MB, cpu #{stats.cpu_percent}%"
+
+top = sbx.procs
+top.procs.each { |p| puts "#{p.pid} #{p.comm} #{p.cpu}%" }
 ```
 
-### Typed errors
+### Open a web terminal
+
+Get a browser-ready root shell for the box - no SSH client needed. The signed
+URL expires after about an hour; mint a fresh one each time:
 
 ```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
+puts sbx.terminal_url
 ```
 
-- `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`)
+### Provision every new box the same way (boxfile)
+
+The account-level boxfile is a package manifest applied whenever a NEW box is
+created - preinstall your dependencies once:
+
+```ruby
+Xshellz::Sandbox.set_boxfile(<<~BOX)
+  apt jq ripgrep
+  pip requests
+BOX
+Xshellz::Sandbox.get_boxfile # => the saved manifest
+```
+
+## API reference
+
+Every public method, its parameters, return shapes, and errors are documented
+in **[docs/API.md](docs/API.md)**.
+
+## Configuration
+
+| Environment variable | Meaning | Default |
+|---|---|---|
+| `XSHELLZ_API_KEY` | Personal access token (`read` + `write` scopes) | - (required) |
+| `XSHELLZ_API_URL` | Control-plane base URL | `https://api.xshellz.com/v1` |
+
+Explicit arguments (`api_key:`, `api_url:`) always win over the environment.
+
+## Error types
+
+| Error | Meaning |
+|---|---|
+| `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::MissingKeyError` | `get_or_create` found the box but no private key for it |
+| `Xshellz::SandboxNotRunningError` | Operation needs a `running` box |
+| `Xshellz::CommandTimeoutError` | `run(timeout: ...)` exceeded |
+| `Xshellz::UnsupportedLanguageError` | `run_code` got a language it doesn't know |
+| `Xshellz::ApiError` | Any other 4xx/5xx (carries `.status` and `.body`) |
+
+## v0 limits
+
+- **Free tier: 1 concurrent sandbox.** A second `Sandbox.create` raises
+  `Xshellz::QuotaError` while one exists - attach to the existing box instead
+  (`get_or_create` / `Sandbox.connect`), or `kill` it first.
+- **Free boxes idle-stop after ~30 minutes.** The box (its `/home` and your
+  key) is preserved; `sbx.start` - or `get_or_create` - resumes it.
+- Sandbox creation is throttled to 10 requests/minute per account.
 
 ## How it works
 
 - **Control plane**: HTTPS to `api.xshellz.com/v1` (create / list / start /
-  destroy), authenticated by your PAT.
+  destroy / stats), authenticated by your token.
 - **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
@@ -142,20 +200,11 @@ end
   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):
+No local Ruby toolchain is required - the whole test suite (with the >= 80%
+coverage gate) runs inside a `ruby:3.3` container, gems cached in a named
+volume:
 
 ```bash
 docker compose run --rm test

data/lib/xshellz/client.rb

@@ -86,6 +86,10 @@ module Xshellz
       request("POST", path, body)
     end
 
+    def put(path, body = nil)
+      request("PUT", path, body)
+    end
+
     def delete(path)
       request("DELETE", path)
     end

data/lib/xshellz/errors.rb

@@ -22,6 +22,15 @@ module Xshellz
   # The sandbox is not in the +running+ state (or no longer exists).
   class SandboxNotRunningError < Error; end
 
+  # +Sandbox.get_or_create+ found an existing sandbox by name but no private
+  # key for it: none was passed explicitly and the keystore has no key file
+  # (or the keystore is disabled). The message says where a key was expected.
+  class MissingKeyError < Error; end
+
+  # +Sandbox#run_code+ was called with a language it does not know how to
+  # execute. The message lists the supported languages.
+  class UnsupportedLanguageError < Error; end
+
   # A command executed with +run(timeout: ...)+ exceeded its deadline.
   class CommandTimeoutError < Error; end
 

data/lib/xshellz/job_handle.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Xshellz
+  # A background process started with +Sandbox#spawn+ (or listed by
+  # +Sandbox#jobs+).
+  #
+  # The process runs detached inside the sandbox (+nohup+, disowned) and its
+  # combined stdout+stderr goes to +log_path+ (+~/.xshellz/jobs/<id>.log+ in
+  # the box). The handle survives SDK restarts: +Sandbox#jobs+ rebuilds
+  # handles from the pid files the spawn command leaves behind.
+  class JobHandle
+    STOP_POLL_INTERVAL = 0.2
+
+    # Short job id (name-prefixed when +spawn+ was given a name).
+    attr_reader :id
+
+    # Pid of the detached process inside the sandbox.
+    attr_reader :pid
+
+    # Path of the job's log file inside the sandbox.
+    attr_reader :log_path
+
+    def initialize(sandbox:, id:, pid:)
+      @sandbox = sandbox
+      @id = id
+      @pid = Integer(pid)
+      @log_path = "~/.xshellz/jobs/#{id}.log"
+    end
+
+    # Live probe: is the process still running? (+kill -0+ inside the box.)
+    def running?
+      @sandbox.run("kill -0 #{pid} 2>/dev/null").ok?
+    end
+
+    # The last +tail_lines+ lines of the job's log (stdout+stderr combined).
+    def logs(tail_lines: 100)
+      @sandbox.run("tail -n #{Integer(tail_lines)} #{log_path} 2>/dev/null").stdout
+    end
+
+    # Stop the job: SIGTERM, then SIGKILL if it is still alive after +grace+
+    # seconds. Returns true when the process exited from the SIGTERM alone.
+    def stop(grace: 5)
+      @sandbox.run("kill -TERM #{pid} 2>/dev/null")
+      deadline = monotonic + grace
+      loop do
+        return true unless running?
+
+        if monotonic >= deadline
+          @sandbox.run("kill -KILL #{pid} 2>/dev/null")
+          return false
+        end
+        sleep(STOP_POLL_INTERVAL)
+      end
+    end
+
+    def inspect
+      "#<Xshellz::JobHandle id=#{id.inspect} pid=#{pid} log=#{log_path.inspect}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/xshellz/keystore.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Xshellz
+  # Local on-disk private-key store backing +Sandbox.get_or_create+.
+  #
+  # One file per sandbox name (sanitized), OpenSSH private key inside,
+  # +0600+ permissions, in +~/.xshellz/keys/+ by default.
+  #
+  # Security note: keys are stored in PLAINTEXT on disk, protected only by
+  # file permissions (0600, directory 0700). Anyone who can read the file can
+  # SSH into the sandbox. Delete the file (+delete+) and kill the box to
+  # revoke; pass +keystore: false+ to +get_or_create+ to keep keys purely
+  # in-memory instead.
+  class Keystore
+    # Characters allowed to survive sanitization into a key file name.
+    SAFE_NAME = /[^A-Za-z0-9._-]+/
+
+    attr_reader :dir
+
+    def self.default_dir
+      File.join(Dir.home, ".xshellz", "keys")
+    end
+
+    # Turn a sandbox name into a safe file basename (no separators, no
+    # leading dots - so no traversal and no hidden files).
+    def self.sanitize(name)
+      cleaned = name.to_s.gsub(SAFE_NAME, "_").sub(/\A\.+/, "_")
+      raise ArgumentError, "Cannot derive a key file name from #{name.inspect}" if cleaned.empty?
+
+      cleaned
+    end
+
+    def initialize(dir: self.class.default_dir)
+      @dir = File.expand_path(dir)
+    end
+
+    # The absolute path where +name+'s key lives (whether or not it exists).
+    def path_for(name)
+      File.join(dir, "#{self.class.sanitize(name)}.key")
+    end
+
+    # Persist an OpenSSH private key for +name+ (0600). Returns the path.
+    def save(name, private_key_openssh)
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      path = path_for(name)
+      File.write(path, private_key_openssh, perm: 0o600)
+      File.chmod(0o600, path)
+      path
+    end
+
+    # The stored key for +name+, or nil when none exists.
+    def load(name)
+      path = path_for(name)
+      File.file?(path) ? File.read(path) : nil
+    end
+
+    # Remove the stored key for +name+. Returns true when a file was deleted.
+    def delete(name)
+      path = path_for(name)
+      return false unless File.file?(path)
+
+      File.delete(path)
+      true
+    end
+  end
+end

data/lib/xshellz/models.rb

@@ -53,4 +53,88 @@ module Xshellz
       )
     end
   end
+
+  # Live resource usage for a running sandbox (+Sandbox#stats+), mirroring
+  # the control plane's wire fields. +*_allowed_*+ fields are the plan
+  # ceilings so used/allowed gauges need no second call.
+  SandboxStats = Struct.new(
+    :mem_used_mb,
+    :mem_limit_mb,
+    :mem_allowed_mb,
+    :cpu_percent,
+    :cpu_allowed_vcpus,
+    :cpu_throttled_periods,
+    :pids_current,
+    :pids_allowed,
+    :disk_used_mb,
+    :disk_allowed_mb,
+    :net_rx_mb,
+    :net_tx_mb,
+    :blk_read_mb,
+    :blk_write_mb,
+    keyword_init: true
+  ) do
+    # Build a +SandboxStats+ from the API's JSON payload (tolerant of
+    # missing keys).
+    def self.from_api(payload)
+      payload ||= {}
+      new(
+        mem_used_mb: (payload["mem_used_mb"] || 0).to_i,
+        mem_limit_mb: (payload["mem_limit_mb"] || 0).to_i,
+        mem_allowed_mb: (payload["mem_allowed_mb"] || 0).to_i,
+        cpu_percent: (payload["cpu_percent"] || 0.0).to_f,
+        cpu_allowed_vcpus: (payload["cpu_allowed_vcpus"] || 0.0).to_f,
+        cpu_throttled_periods: (payload["cpu_throttled_periods"] || 0).to_i,
+        pids_current: (payload["pids_current"] || 0).to_i,
+        pids_allowed: (payload["pids_allowed"] || 0).to_i,
+        disk_used_mb: (payload["disk_used_mb"] || 0).to_i,
+        disk_allowed_mb: (payload["disk_allowed_mb"] || 0).to_i,
+        net_rx_mb: (payload["net_rx_mb"] || 0).to_i,
+        net_tx_mb: (payload["net_tx_mb"] || 0).to_i,
+        blk_read_mb: (payload["blk_read_mb"] || 0).to_i,
+        blk_write_mb: (payload["blk_write_mb"] || 0).to_i
+      )
+    end
+  end
+
+  # One process row from +Sandbox#procs+.
+  ProcessInfo = Struct.new(:pid, :comm, :cpu, :mem, keyword_init: true) do
+    def self.from_api(payload)
+      payload ||= {}
+      new(
+        pid: (payload["pid"] || 0).to_i,
+        comm: payload["comm"].to_s,
+        cpu: (payload["cpu"] || 0.0).to_f,
+        mem: (payload["mem"] || 0.0).to_f
+      )
+    end
+  end
+
+  # Top processes + session info for a running sandbox (+Sandbox#procs+).
+  #
+  # +procs+ is an Array<ProcessInfo>; +sessions+ counts active SSH sessions;
+  # +agents+ lists detected agent processes (e.g. "claude") by name.
+  SandboxProcs = Struct.new(
+    :procs,
+    :sessions,
+    :agents,
+    :disk_used_mb,
+    :disk_allowed_mb,
+    keyword_init: true
+  ) do
+    # Build a +SandboxProcs+ from the API's JSON payload (tolerant of
+    # missing keys).
+    def self.from_api(payload)
+      payload ||= {}
+      rows = payload["procs"]
+      rows = [] unless rows.is_a?(Array)
+      new(
+        procs: rows.map { |row| ProcessInfo.from_api(row) },
+        sessions: (payload["sessions"] || 0).to_i,
+        agents: Array(payload["agents"]).map(&:to_s),
+        disk_used_mb: (payload["disk_used_mb"] || 0).to_i,
+        disk_allowed_mb: (payload["disk_allowed_mb"] || 0).to_i
+      )
+    end
+  end
 end

data/lib/xshellz/sandbox.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "securerandom"
+require "shellwords"
+
 module Xshellz
   # A remote sandbox: control plane over HTTPS, data plane over SSH.
   #
@@ -14,6 +17,18 @@ module Xshellz
   #   end
   class Sandbox
     STATUS_RUNNING = "running"
+    STATUS_STOPPED = "stopped"
+
+    JOBS_DIR = "~/.xshellz/jobs"
+
+    # Interpreters +run_code+ knows how to execute, keyed by language name.
+    RUN_CODE_LANGUAGES = {
+      "python" => { command: "python3", extension: ".py" },
+      "node" => { command: "node", extension: ".js" },
+      "bash" => { command: "bash", extension: ".sh" },
+      "ruby" => { command: "ruby", extension: ".rb" },
+      "php" => { command: "php", extension: ".php" }
+    }.freeze
 
     # The last-known control-plane state (a SandboxInfo).
     attr_reader :info
@@ -83,6 +98,56 @@ module Xshellz
       new(info: info, client: client, private_key_openssh: private_key)
     end
 
+    # Get-or-create a PERMANENT named sandbox: find the account's sandbox
+    # whose name is exactly +name+, or create one with that name.
+    #
+    # The private key is persisted in a local keystore
+    # (+~/.xshellz/keys/<name>.key+, 0600) so a later +get_or_create+ from
+    # another process can re-attach without you handling key material:
+    #
+    # - Not found -> create; persist the generated key in the keystore.
+    # - Found -> attach with the explicit +private_key+ if given, else the
+    #   keystore's key; a stopped box is started first. When no key can be
+    #   found, raises MissingKeyError telling you where one was expected.
+    #
+    # +keystore+ accepts +:default+ (=> +~/.xshellz/keys/+), a directory
+    # String, a +Keystore+ instance, or +false+/+nil+ to disable persistence
+    # entirely (then +get_or_create+ can only create-or-error, unless you
+    # pass +private_key+).
+    #
+    # Security note: the keystore holds plaintext private keys on disk
+    # (0600). Delete the key file and kill the box to revoke.
+    def self.get_or_create(name, api_key: nil, api_url: nil, http: nil, private_key: nil, keystore: :default)
+      name = name.to_s
+      raise ArgumentError, "get_or_create requires a non-empty sandbox name" if name.empty?
+
+      store = resolve_keystore(keystore)
+      client = Client.new(api_key: api_key, api_url: api_url, http: http)
+
+      found = client.get("/shells/agent")
+                    .map { |item| SandboxInfo.from_api(item) }
+                    .find { |info| info.name == name }
+      return create_named(client, name, store) if found.nil?
+
+      key = private_key || store&.load(name)
+      if key.nil?
+        hint = if store.nil?
+                 "the keystore is disabled, so pass private_key: ..."
+               else
+                 "expected a key file at #{store.path_for(name)}"
+               end
+        raise MissingKeyError,
+              "Sandbox #{name.inspect} already exists but no private key is " \
+              "available to attach to it (#{hint}). Pass private_key: ..., " \
+              "or kill the box and let get_or_create recreate it."
+      end
+      Ssh.load_private_key!(key)
+
+      sandbox = new(info: found, client: client, private_key_openssh: key)
+      sandbox.start if sandbox.status == STATUS_STOPPED
+      sandbox
+    end
+
     # List the account's active sandboxes (a bare array on the wire).
     #
     # @return [Array<SandboxInfo>]
@@ -91,6 +156,26 @@ module Xshellz
       client.get("/shells/agent").map { |item| SandboxInfo.from_api(item) }
     end
 
+    # The account's saved +xshellz.box+ provisioning manifest, or nil when
+    # none is saved (+GET /shells/agent/boxfile+).
+    #
+    # The boxfile is applied when a NEW box is created: it is seeded into
+    # +~/xshellz.box+ on every fresh box, so destroy+recreate reproduces
+    # your package environment (preinstall deps, etc.).
+    def self.get_boxfile(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/boxfile") || {})["manifest"]
+    end
+
+    # Save the account's +xshellz.box+ manifest (+PUT /shells/agent/boxfile+,
+    # max 16 KB). Pass nil (or a blank string) to clear it. Returns the
+    # stored manifest (nil when cleared). Applies to boxes created AFTER the
+    # save - existing boxes are not touched.
+    def self.set_boxfile(manifest, api_key: nil, api_url: nil, http: nil)
+      client = Client.new(api_key: api_key, api_url: api_url, http: http)
+      (client.put("/shells/agent/boxfile", { "manifest" => manifest }) || {})["manifest"]
+    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|
@@ -101,6 +186,33 @@ module Xshellz
             "Sandbox #{uuid} was not found among this account's active sandboxes."
     end
 
+    class << self
+      private
+
+      def resolve_keystore(keystore)
+        case keystore
+        when :default then Keystore.new
+        when nil, false then nil
+        when String then Keystore.new(dir: keystore)
+        else keystore
+        end
+      end
+
+      def create_named(client, name, store)
+        keypair = Keys.generate
+        payload = client.post(
+          "/shells/agent",
+          { "ssh_public_key" => keypair.public_key_line, "name" => name }
+        )
+        store&.save(name, keypair.private_key_openssh)
+        new(
+          info: SandboxInfo.from_api(payload),
+          client: client,
+          private_key_openssh: keypair.private_key_openssh
+        )
+      end
+    end
+
     # ------------------------------------------------------------------ #
     # Properties
     # ------------------------------------------------------------------ #
@@ -171,6 +283,76 @@ module Xshellz
       transport.download(remote_path, local_path)
     end
 
+    # Start +command+ as a detached background process inside the sandbox
+    # and return immediately with a JobHandle.
+    #
+    # The process survives this SDK disconnecting (nohup, stdin from
+    # /dev/null); combined stdout+stderr goes to +~/.xshellz/jobs/<id>.log+
+    # in the box. +name+ (optional) prefixes the generated job id.
+    #
+    # @return [JobHandle]
+    def spawn(command, name: nil)
+      job_id = generate_job_id(name)
+      script = "mkdir -p #{JOBS_DIR} && " \
+               "nohup bash -c #{Shellwords.escape(command)} " \
+               "> #{JOBS_DIR}/#{job_id}.log 2>&1 < /dev/null & " \
+               "echo $! > #{JOBS_DIR}/#{job_id}.pid; echo $!"
+      result = transport.exec(script)
+      pid = result.stdout[/\d+/]
+      if !result.ok? || pid.nil?
+        raise Error,
+              "Failed to spawn background job #{job_id.inspect} " \
+              "(exit #{result.exit_code}): #{result.stderr.strip}"
+      end
+
+      JobHandle.new(sandbox: self, id: job_id, pid: pid)
+    end
+
+    # List the sandbox's background jobs (every job ever spawned whose
+    # +~/.xshellz/jobs/<id>.pid+ file still exists). Check liveness per
+    # handle with +running?+; read output with +logs+.
+    #
+    # @return [Array<JobHandle>]
+    def jobs
+      listing = transport.exec(
+        "mkdir -p #{JOBS_DIR} && for f in #{JOBS_DIR}/*.pid; do " \
+        '[ -e "$f" ] || continue; ' \
+        'printf "%s %s\n" "$(basename "$f" .pid)" "$(cat "$f")"; done'
+      )
+      listing.stdout.each_line.filter_map do |line|
+        id, pid = line.split
+        next if id.nil? || pid.nil? || !pid.match?(/\A\d+\z/)
+
+        JobHandle.new(sandbox: self, id: id, pid: pid)
+      end
+    end
+
+    # Execute a snippet of code in the sandbox: write it to a temp file,
+    # run the matching interpreter, always delete the temp file.
+    #
+    # Supported languages: python (python3), node, bash, ruby, php. An
+    # unknown language raises UnsupportedLanguageError. Semantics otherwise
+    # match +run+ (same cwd/env/timeout/stream-block, non-zero exit is
+    # data, returns a CommandResult).
+    #
+    # @return [CommandResult]
+    def run_code(language, code, cwd: nil, env: nil, timeout: nil, &block)
+      interpreter = RUN_CODE_LANGUAGES[language.to_s.downcase]
+      if interpreter.nil?
+        raise UnsupportedLanguageError,
+              "Unsupported run_code language #{language.inspect}. " \
+              "Supported languages: #{RUN_CODE_LANGUAGES.keys.join(", ")}."
+      end
+
+      path = "/tmp/xshellz-run-#{SecureRandom.hex(6)}#{interpreter[:extension]}"
+      write_file(path, code)
+      begin
+        run("#{interpreter[:command]} #{Shellwords.escape(path)}", cwd: cwd, env: env, timeout: timeout, &block)
+      ensure
+        delete_remote_file_quietly(path)
+      end
+    end
+
     # ------------------------------------------------------------------ #
     # Lifecycle (control plane)
     # ------------------------------------------------------------------ #
@@ -195,6 +377,44 @@ module Xshellz
       self
     end
 
+    # Reboot a running box (+POST /shells/agent/{uuid}/restart+): re-runs
+    # the entrypoint; +/home+ is preserved. Returns self with refreshed
+    # info; the SSH connection is re-established on the next data-plane
+    # call.
+    def restart
+      payload = @client.post("/shells/agent/#{uuid}/restart")
+      @info = SandboxInfo.from_api(payload)
+      close_transport
+      self
+    end
+
+    # Live resource usage (+GET /shells/agent/{uuid}/stats+): memory, CPU,
+    # pids, disk, network and block IO, each alongside the plan-allowed
+    # ceiling.
+    #
+    # @return [SandboxStats]
+    def stats
+      SandboxStats.from_api(@client.get("/shells/agent/#{uuid}/stats"))
+    end
+
+    # Top processes + active SSH session count inside the box
+    # (+GET /shells/agent/{uuid}/procs+).
+    #
+    # @return [SandboxProcs]
+    def procs
+      SandboxProcs.from_api(@client.get("/shells/agent/#{uuid}/procs"))
+    end
+
+    # Mint a fresh signed web-terminal URL for this box
+    # (+GET /shells/agent/{uuid}/terminal+). Open it in a browser for a
+    # root shell - no SSH client needed. The embedded HMAC token expires
+    # after ~1 hour; call again for a fresh URL rather than storing it.
+    #
+    # @return [String]
+    def terminal_url
+      (@client.get("/shells/agent/#{uuid}/terminal") || {})["url"].to_s
+    end
+
     # Destroy the sandbox (+DELETE /shells/agent/{uuid}+). Idempotent: a 404
     # (already gone) is swallowed.
     def kill
@@ -266,5 +486,20 @@ module Xshellz
       @transport&.close
       @transport = nil
     end
+
+    # A short unique job id, safe to interpolate into shell paths
+    # unquoted; prefixed with the sanitized job name when one was given.
+    def generate_job_id(name)
+      suffix = SecureRandom.hex(4)
+      return suffix if name.to_s.empty?
+
+      "#{Keystore.sanitize(name)}-#{suffix}"
+    end
+
+    def delete_remote_file_quietly(path)
+      transport.exec("rm -f #{Shellwords.escape(path)}")
+    rescue StandardError
+      nil
+    end
   end
 end

data/lib/xshellz/version.rb

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

data/lib/xshellz.rb

@@ -4,8 +4,10 @@ require_relative "xshellz/version"
 require_relative "xshellz/errors"
 require_relative "xshellz/models"
 require_relative "xshellz/keys"
+require_relative "xshellz/keystore"
 require_relative "xshellz/client"
 require_relative "xshellz/ssh"
+require_relative "xshellz/job_handle"
 require_relative "xshellz/sandbox"
 
 # xShellz Ruby SDK - throwaway, gVisor-isolated Linux sandboxes.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xshellz
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - xShellz
@@ -78,7 +78,9 @@ files:
 - lib/xshellz.rb
 - lib/xshellz/client.rb
 - lib/xshellz/errors.rb
+- lib/xshellz/job_handle.rb
 - lib/xshellz/keys.rb
+- lib/xshellz/keystore.rb
 - lib/xshellz/models.rb
 - lib/xshellz/sandbox.rb
 - lib/xshellz/ssh.rb