kosa8 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '059d3ca9753fb52d517a80038164038e51621d2ae4a2393fcb8f79481e9c8c95'
+  data.tar.gz: 10c6b5dd4914af9371fe21b17230df7ac38c85275fbb16c1fa60e1f10487bbc3
+SHA512:
+  metadata.gz: 8774ce6bba2044d40ec5f051d84be6b057944469bda072eb52bacb8104d025f8a6cda96f5da6ca244c0eeee1207730b42f096118a93a96ad3d9454a8a740a2b0
+  data.tar.gz: 2207cecb3af2ca7dadfe4aa1252f29a0886b5e583534da78fe04682e5882b04235a9ff6a52fa16b546a9a1f3ad300c006a2b5413b92fe4350ca324448ebe7fed

data/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 kosa8
+
+This license covers the source code in this repository (the kosa8
+TypeScript SDK packages, @kosa8/sdk and @kosa8/ai-sdk-sandbox) only. It does
+not cover kosa8 itself (the kosa8 CLI, the kosa8d daemon or any other kosa8
+software), which is licensed separately.
+
+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,55 @@
+# kosa8 (Ruby)
+
+The Ruby SDK for [kosa8](https://kosa8.com): microVM sandboxes for AI agents. No dependencies; Ruby 2.6+.
+Method for method it matches [`@kosa8/sdk`](https://github.com/kosa8ai/kosa8-js), the Python `kosa8` package and `kosa8-go`.
+
+```ruby
+require "kosa8"
+
+k = Kosa8::Client.new                     # local daemon at ~/.kosa8/run/kosa8.sock
+k.create_sandbox(name: "demo", egress_allow: ["pypi.org"])
+sb = k.sandbox("demo")
+sb.pull("python:3.12-alpine")
+puts sb.run("python:3.12-alpine", ["python", "-c", "print(6*7)"]).stdout  # 42
+
+sb.checkpoint(label: "clean")             # restore point, shared with `kosa8 rewind`
+sb.rewind(to: "clean")                    # back to it, processes resumed
+best = sb.explore(["make test", "make test-fast"])  # best-of-N on forks
+sb.delete
+```
+
+## Connecting
+
+| Option | Default |
+|---|---|
+| `socket_path:` | `~/.kosa8/run/kosa8.sock` |
+| `host:` / `KOSA8_HOST` | a remote worker: `https://`, `http://` (loopback only unless `insecure: true` / `KOSA8_INSECURE=1`), `tcp://`, `unix://` |
+| `token:` / `KOSA8_TOKEN` | sent as `Authorization: Bearer` to a remote worker |
+| `actor:` | `"tool"` (`human`, `agent`, `tool`), sent as `X-Kosa8-Actor` |
+| `agent_token:` / `KOSA8_AGENT_TOKEN` | sent as `X-Kosa8-Agent-Token` |
+
+## Errors
+
+All errors inherit `Kosa8::Error` and carry the daemon's message and remediation:
+`ConnectionError`, `BadRequestError`, `AuthError`, `PolicyError` › `ApprovalRequiredError` (`#approval`),
+`NotFoundError`, `ConflictError`, `UnsupportedError`, `StreamError` (`#stdout`/`#stderr` so far),
+`CheckpointError`, `TimeoutError`. Methods that a policy may gate take `approval:`.
+
+## API
+
+Daemon: `health`, `version`, `pull`.
+Sandboxes: `list_sandboxes`, `get_sandbox`, `create_sandbox`, `start_sandbox`, `stop_sandbox`, `delete_sandbox`,
+`pull_into_sandbox`, `sandbox_images`, `sandbox_containers`, `sandbox_egress`.
+Processes: `run`, `start_container`, `exec`, `exec_frames`, `start_interactive`, `write_stdin`, `attach`.
+Snapshots: `snapshot`, `list_snapshots`, `restore_snapshot`, `delete_snapshot`, `fork`, `explore`.
+Checkpoints: `checkpoint`, `list_checkpoints`, `rewind` (store: `~/.kosa8/checkpoints.json`, flock-shared with the CLI).
+`client.sandbox(id)` binds them to one sandbox.
+
+## Development
+
+```sh
+ruby -w test/test_client.rb      # mock daemon on a unix socket
+ruby examples/smoke.rb           # live, against a running `kosa8 daemon`
+```
+
+MIT licensed.

data/lib/kosa8/checkpoints.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+
+module Kosa8
+  # pkg/checkpoint MaxPerSandbox.
+  MAX_CHECKPOINTS_PER_SANDBOX = 10
+
+  def self.validate_sandbox_name(name)
+    if !name.is_a?(String) || name.empty? || name.start_with?(".") || name.include?("/") || name.include?("\\")
+      raise CheckpointError, "invalid sandbox name #{name.inspect}"
+    end
+
+    name
+  end
+
+  # Keeps stacks in memory; nothing is shared with the CLI.
+  class MemoryCheckpointStore
+    def initialize
+      @data = {}
+      @mu = Mutex.new
+    end
+
+    def load
+      @mu.synchronize { Marshal.load(Marshal.dump(@data)) }
+    end
+
+    # Runs the block on the stacks and saves what it leaves.
+    def update
+      @mu.synchronize do
+        d = Marshal.load(Marshal.dump(@data))
+        r = yield d
+        @data = d
+        r
+      end
+    end
+  end
+
+  # The store the kosa8 CLI uses: ~/.kosa8/checkpoints.json (0600, rewritten
+  # atomically), locked with the same flock on checkpoints.json.lock, so
+  # `kosa8 rewind` sees checkpoints taken here and the other way round.
+  class FileCheckpointStore
+    attr_reader :path
+
+    def initialize(path = nil)
+      @path = path || File.join(Dir.home, ".kosa8", "checkpoints.json")
+      @mu = Mutex.new
+    end
+
+    def load
+      d = JSON.parse(File.read(@path))
+      d.is_a?(Hash) ? d : {}
+    rescue Errno::ENOENT, JSON::ParserError
+      {} # a corrupt store must not make the sandbox unusable
+    end
+
+    def update
+      @mu.synchronize do
+        FileUtils.mkdir_p(File.dirname(@path), mode: 0o700)
+        File.open("#{@path}.lock", File::RDWR | File::CREAT, 0o600) do |lock|
+          lock.flock(File::LOCK_EX)
+          d = load
+          r = yield d
+          tmp = "#{@path}.tmp"
+          File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |f| f.write(JSON.pretty_generate(d)) }
+          File.chmod(0o600, tmp)
+          File.rename(tmp, @path)
+          r
+        end
+      end
+    end
+  end
+
+  # The stack logic of pkg/checkpoint over any store. Records are hashes with
+  # the CLI's JSON keys: id, sandbox, label, auto (omitted when false), created.
+  class CheckpointBook
+    def initialize(store)
+      @store = store
+    end
+
+    def self.seq(id, sandbox)
+      pre = "#{sandbox}-ckpt-"
+      return 0 unless id.start_with?(pre)
+
+      id[pre.length..-1][/\A\d+/].to_i
+    end
+
+    # The next id and the ids to evict to stay at the cap.
+    def next_id(sandbox)
+      Kosa8.validate_sandbox_name(sandbox)
+      list = @store.load[sandbox] || []
+      n = list.length + 1
+      list.each { |c| v = self.class.seq(c["id"].to_s, sandbox); n = v + 1 if v >= n }
+      over = list.length + 1 - MAX_CHECKPOINTS_PER_SANDBOX
+      evict = over.positive? ? list.first(over).map { |c| c["id"] } : []
+      ["#{sandbox}-ckpt-#{n}", evict]
+    end
+
+    def record(id, sandbox, label, evicted = [])
+      Kosa8.validate_sandbox_name(sandbox)
+      rec = { "id" => id, "sandbox" => sandbox, "label" => label.to_s,
+              "created" => Time.now.utc.iso8601(9) }
+      @store.update do |d|
+        d[sandbox] = (d[sandbox] || []).reject { |c| evicted.include?(c["id"]) } + [rec]
+      end
+      rec
+    end
+
+    # Oldest first.
+    def list(sandbox)
+      (@store.load[sandbox] || []).each_with_index.sort_by { |c, i| [Kosa8.parse_time(c["created"]), i] }.map(&:first)
+    end
+
+    def latest(sandbox)
+      l = list(sandbox)
+      raise CheckpointError, "no checkpoints for #{sandbox.inspect} — take one with checkpoint or `kosa8 checkpoint #{sandbox}`" if l.empty?
+
+      l.last
+    end
+
+    # By id or (case-insensitive) label, newest first.
+    def resolve(sandbox, ref)
+      list(sandbox).reverse.find { |c| c["id"] == ref || c["label"].to_s.casecmp(ref.to_s).zero? } ||
+        raise(CheckpointError, "no checkpoint #{ref.inspect} for sandbox #{sandbox.inspect}")
+    end
+
+    # Drops everything after id; returns the dropped ids.
+    def pop(sandbox, id)
+      @store.update do |d|
+        list = d[sandbox] || []
+        i = list.index { |c| c["id"] == id }
+        raise CheckpointError, "no checkpoint #{id.inspect} for sandbox #{sandbox.inspect}" if i.nil?
+
+        d[sandbox] = list.first(i + 1)
+        list[(i + 1)..-1].map { |c| c["id"] }
+      end
+    end
+
+    # Forgets a sandbox's stack; returns its ids.
+    def forget(sandbox)
+      @store.update { |d| (d.delete(sandbox) || []).map { |c| c["id"] } }
+    end
+  end
+
+  def self.parse_time(s)
+    Time.iso8601(s.to_s) # handles the Go CLI's nanosecond timestamps
+  rescue ArgumentError
+    Time.at(0)
+  end
+end

data/lib/kosa8/client.rb

@@ -0,0 +1,472 @@
+# frozen_string_literal: true
+
+module Kosa8
+  # The outcome of a run, exec or attach.
+  ExecResult = Struct.new(:exit_code, :stdout, :stderr, keyword_init: true) do
+    def ok?
+      exit_code.zero?
+    end
+  end
+
+  ExploreBranch = Struct.new(:name, :variant, :exit, :output, :error, :duration_ms, keyword_init: true)
+  ExploreResult = Struct.new(:parent, :branches, :winner, :removed, keyword_init: true)
+
+  TRANSIENT = /connection refused|EOF|connection reset|broken pipe|no such file or directory|stream ended|ECONNREFUSED|ECONNRESET|unreachable/i.freeze
+
+  # Typed client for the kosa8 native API (/kosa8/v1) over the daemon's unix
+  # socket, or a remote worker via KOSA8_HOST / KOSA8_TOKEN.
+  #
+  #   k = Kosa8::Client.new
+  #   k.create_sandbox(name: "demo", egress: "deny")
+  #   k.pull_into_sandbox("demo", "alpine:latest")
+  #   puts k.run("demo", "alpine:latest", ["echo", "hi"]).stdout
+  class Client
+    attr_reader :transport, :checkpoints
+
+    def initialize(socket_path: nil, host: nil, token: nil, insecure: false, actor: "tool", agent_token: nil,
+                   headers: {}, timeout: nil, checkpoint_store: nil, env: ENV)
+      @transport = Transport.new(socket_path: socket_path, host: host, token: token, insecure: insecure, actor: actor,
+                                 agent_token: agent_token, headers: headers, timeout: timeout, env: env)
+      @checkpoints = CheckpointBook.new(checkpoint_store || FileCheckpointStore.new)
+    end
+
+    # --- daemon ---------------------------------------------------------------
+
+    # GET /kosa8/v1/health: daemon status and version.
+    def health
+      @transport.json("GET", "/kosa8/v1/health")
+    end
+
+    def version
+      health["version"]
+    end
+
+    # POST /kosa8/v1/pull: pull an image into the host engine.
+    def pull(ref, approval: nil)
+      @transport.json("POST", "/kosa8/v1/pull", body: { ref: ref }, approval: approval)
+    end
+
+    # --- sandboxes ------------------------------------------------------------
+
+    def list_sandboxes
+      @transport.json("GET", "/kosa8/v1/sandboxes") || []
+    end
+
+    # By id, then by name; nil when there is none.
+    def get_sandbox(id_or_name)
+      l = list_sandboxes
+      l.find { |s| s["id"] == id_or_name } || l.find { |s| s["name"] == id_or_name }
+    end
+
+    # POST /kosa8/v1/sandboxes: boot a microVM sandbox.
+    # egress: "deny" | "any" | "fakenet" | "allow:host,host" | { allow: [...] }
+    def create_sandbox(name: nil, cpus: nil, mem_mb: nil, disk_gb: nil, mounts: nil, egress: nil, egress_allow: nil,
+                       capture: nil, labels: nil, broker: nil, approval: nil)
+      body = {}
+      body[:name] = name if name
+      body[:cpus] = cpus if cpus
+      body[:mem_mb] = mem_mb if mem_mb
+      body[:disk_gb] = disk_gb if disk_gb
+      body[:mounts] = mounts if mounts
+      e = Client.egress_string(egress, egress_allow)
+      body[:egress] = e if e
+      body[:capture] = capture unless capture.nil?
+      body[:labels] = labels if labels
+      body[:broker] = broker if broker
+      @transport.json("POST", "/kosa8/v1/sandboxes", body: body, approval: approval)
+    end
+
+    # POST …/up: boot a stopped sandbox from its own disk.
+    def start_sandbox(sandbox, approval: nil)
+      @transport.json("POST", sb(sandbox, "up"), approval: approval)
+    end
+
+    # POST …/down: stop without deleting (the disk is kept).
+    def stop_sandbox(sandbox, approval: nil)
+      @transport.json("POST", sb(sandbox, "down"), approval: approval)
+    end
+
+    # DELETE /kosa8/v1/sandboxes/{id}; its checkpoints go too unless keep_checkpoints.
+    def delete_sandbox(sandbox, wipe: false, keep_checkpoints: false, approval: nil)
+      out = @transport.json("DELETE", sb(sandbox), query: { wipe: wipe }, approval: approval) || {}
+      dropped = 0
+      unless keep_checkpoints
+        begin
+          ids = @checkpoints.forget(sandbox)
+          ids.each do |sid|
+            delete_snapshot(sid, wipe: wipe, approval: approval)
+          rescue Error
+            nil
+          end
+          dropped = ids.length
+        rescue Error
+          nil # bookkeeping debris, not a failed delete
+        end
+      end
+      out.merge("checkpoints_dropped" => dropped)
+    end
+
+    # POST …/pull: pull an image into the sandbox's private engine.
+    def pull_into_sandbox(sandbox, ref, approval: nil)
+      @transport.json("POST", sb(sandbox, "pull"), body: { ref: ref }, approval: approval)
+    end
+
+    def sandbox_images(sandbox)
+      @transport.json("GET", sb(sandbox, "images")) || []
+    end
+
+    def sandbox_containers(sandbox)
+      @transport.json("GET", sb(sandbox, "containers")) || []
+    end
+
+    # GET …/egress: the policy the host enforces and what it decided.
+    def sandbox_egress(sandbox)
+      @transport.json("GET", sb(sandbox, "egress"))
+    end
+
+    # --- processes ------------------------------------------------------------
+
+    # POST …/run: run a container to completion. The image must already be in
+    # the sandbox (pull_into_sandbox). Callbacks see output as it arrives.
+    def run(sandbox, image, args = [], env: nil, on_stdout: nil, on_stderr: nil, on_status: nil, timeout: nil, approval: nil)
+      body = { image: image, args: args.to_a }
+      e = Client.env_list(env)
+      body[:env] = e if e
+      collect(on_stdout, on_stderr, on_status) do |h|
+        @transport.frames("POST", sb(sandbox, "run"), body: body, approval: approval, timeout: timeout, &h)
+      end
+    end
+
+    # POST …/start: start a detached container; returns its id.
+    def start_container(sandbox, image, args = [], approval: nil)
+      @transport.json("POST", sb(sandbox, "start"), body: { image: image, args: args.to_a }, approval: approval)["id"]
+    end
+
+    # POST …/exec: run a command in a running container of the sandbox.
+    def exec(sandbox, container, args, on_stdout: nil, on_stderr: nil, timeout: nil, approval: nil)
+      collect(on_stdout, on_stderr, nil) do |h|
+        exec_frames(sandbox, container, args, timeout: timeout, approval: approval, &h)
+      end
+    end
+
+    # The raw frame stream of an exec; yields each frame.
+    def exec_frames(sandbox, container, args, timeout: nil, approval: nil, &blk)
+      @transport.frames("POST", sb(sandbox, "exec"), body: { container: container, args: args.to_a },
+                                                    approval: approval, timeout: timeout, &blk)
+    end
+
+    # POST …/start-interactive: start a container with stdin held open.
+    def start_interactive(sandbox, image, args = [], env: nil, tty: false, approval: nil)
+      @transport.json("POST", sb(sandbox, "start-interactive"),
+                      body: { image: image, args: args.to_a, env: Client.env_list(env), tty: tty },
+                      approval: approval)["id"]
+    end
+
+    # POST …/containers/{cid}/stdin: a String, an IO, or an Enumerable of chunks (sent chunked).
+    def write_stdin(sandbox, container, data, approval: nil)
+      @transport.json("POST", sb(sandbox, "containers", Kosa8.enc(container), "stdin"), raw_body: data, approval: approval)
+    end
+
+    # POST …/containers/{cid}/attach: follow a container's output until it exits.
+    def attach(sandbox, container, on_stdout: nil, on_stderr: nil, timeout: nil, approval: nil)
+      collect(on_stdout, on_stderr, nil) do |h|
+        @transport.frames("POST", sb(sandbox, "containers", Kosa8.enc(container), "attach"),
+                          approval: approval, timeout: timeout, &h)
+      end
+    end
+
+    # --- snapshots and forks --------------------------------------------------
+
+    # POST …/snapshot: capture memory, processes and disks.
+    def snapshot(sandbox, id: nil, encrypt: false, approval: nil)
+      body = {}
+      body[:id] = id if id
+      body[:encrypt] = true if encrypt
+      @transport.json("POST", sb(sandbox, "snapshot"), body: body, approval: approval)
+    end
+
+    def list_snapshots
+      @transport.json("GET", "/kosa8/v1/snapshots") || []
+    end
+
+    # POST /kosa8/v1/snapshots/{id}/restore: boot a sandbox from a snapshot, processes resumed.
+    def restore_snapshot(snapshot_id, name: nil, label: nil, allow_tampered: false, approval: nil)
+      body = {}
+      body[:name] = name if name
+      body[:label] = label if label
+      body[:allow_tampered] = true if allow_tampered
+      @transport.json("POST", "/kosa8/v1/snapshots/#{Kosa8.enc(snapshot_id)}/restore", body: body, approval: approval)
+    end
+
+    def delete_snapshot(snapshot_id, wipe: false, force: false, approval: nil)
+      @transport.json("DELETE", "/kosa8/v1/snapshots/#{Kosa8.enc(snapshot_id)}",
+                      query: { wipe: wipe, force: force }, approval: approval)
+    end
+
+    # POST …/fork: n live copies of a running sandbox.
+    # Returns { "forks" => [...], "snapshot" => ..., "fork_ms" => ..., "count" => n }.
+    def fork(sandbox, n = 1, prefix: nil, label: nil, approval: nil)
+      body = { n: n }
+      body[:prefix] = prefix if prefix
+      body[:label] = label if label
+      @transport.json("POST", sb(sandbox, "fork"), body: body, approval: approval)
+    end
+
+    # Best-of-N, as `kosa8 explore`: forks the sandbox once per variant, runs
+    # each (sh -c VARIANT in image) concurrently in its own branch, keeps the
+    # fastest successful branch and deletes the rest.
+    def explore(sandbox, variants, image: "alpine:latest", keep_all: false, keep: nil, timeout: 120, prefix: nil,
+                pull: true, approval: nil)
+      variants = variants.to_a
+      raise Error, "give at least two variants; with one there is nothing to compare" if variants.length < 2
+
+      pull_into_sandbox(sandbox, image, approval: approval) if pull
+      prefix ||= "#{sandbox}-explore-#{Time.now.to_i % 100_000}"
+      forked = fork(sandbox, variants.length, prefix: prefix, approval: approval)
+      names = (forked["forks"] || []).map { |f| f["id"] }.select { |x| x.is_a?(String) }
+      if names.length < variants.length
+        raise Error, "forked #{names.length} branches for #{variants.length} variants; see list_sandboxes for what was created"
+      end
+
+      branches = names.zip(variants).map do |name, v|
+        Thread.new { run_branch(name, image, v, timeout, approval) }
+      end.map(&:value)
+      winner = ""
+      best = nil
+      branches.each do |b|
+        if b.error.nil? && b.exit.zero? && (best.nil? || b.duration_ms < best)
+          winner = b.name
+          best = b.duration_ms
+        end
+      end
+      if keep
+        raise Error, "keep #{keep} is not one of the branches (#{names.join(', ')}); all of them were kept" unless names.include?(keep)
+
+        winner = keep
+      end
+      removed = 0
+      unless keep_all
+        branches.each do |b|
+          next if b.name == winner
+
+          begin
+            @transport.json("DELETE", sb(b.name), approval: approval)
+            removed += 1
+          rescue Error
+            nil # reported by the count
+          end
+        end
+      end
+      ExploreResult.new(parent: sandbox, branches: branches, winner: winner, removed: removed)
+    end
+
+    # --- checkpoints (client-side over snapshots, as pkg/checkpoint) ------------
+
+    # Save a restore point: a snapshot <sandbox>-ckpt-<n> on the sandbox's stack,
+    # the same store `kosa8 checkpoint` uses; the oldest is evicted past 10.
+    def checkpoint(sandbox, label: "", approval: nil)
+      cid, evict = @checkpoints.next_id(sandbox)
+      snap = snapshot(sandbox, id: cid, approval: approval)
+      evict.each do |old| # evict only once the replacement exists
+        delete_snapshot(old, approval: approval)
+      rescue Error
+        nil
+      end
+      rec = @checkpoints.record(cid, sandbox, label, evict)
+      { "checkpoint" => rec, "evicted" => evict, "snapshot" => snap }
+    end
+
+    # A sandbox's restore points, oldest first.
+    def list_checkpoints(sandbox)
+      @checkpoints.list(sandbox)
+    end
+
+    # Undo: put the sandbox back to a checkpoint (id or label; default the
+    # latest) under the same name, processes resumed. Checkpoints taken after
+    # the target are discarded. The current state is lost.
+    def rewind(sandbox, to: nil, approval: nil)
+      target = to ? @checkpoints.resolve(sandbox, to) : @checkpoints.latest(sandbox)
+      # The sandbox must go first: the restored VM takes its name. A refusal
+      # here leaves everything as it was, and is raised as is.
+      @transport.json("DELETE", sb(sandbox), approval: approval)
+      begin
+        restored = restore_snapshot(target["id"], name: sandbox, approval: approval)
+      rescue Error => e
+        raise CheckpointError, "restore failed and #{sandbox} is now stopped: #{e.message} — recover with " \
+                               "restore_snapshot(#{target['id'].inspect}, name: #{sandbox.inspect})"
+      end
+      dropped = []
+      begin
+        dropped = @checkpoints.pop(sandbox, target["id"])
+        dropped.each do |sid|
+          delete_snapshot(sid, approval: approval)
+        rescue Error
+          nil
+        end
+      rescue Error
+        nil # bookkeeping
+      end
+      { "sandbox" => restored["sandbox"], "checkpoint" => target, "dropped" => dropped,
+        "restore_ms" => restored["restore_ms"] }
+    end
+
+    # A handle bound to one sandbox.
+    def sandbox(sandbox_id)
+      Sandbox.new(self, sandbox_id)
+    end
+
+    def self.egress_string(egress, allow)
+      if allow && !allow.empty?
+        raise Error, "egress_allow already limits the network to the hosts it lists; do not also set egress" if egress && egress != "deny"
+
+        return "allow:" + allow.map { |h| h.to_s.strip }.join(",")
+      end
+      return nil if egress.nil?
+      return egress if egress.is_a?(String)
+
+      hosts = (egress[:allow] || egress["allow"] || []).to_a
+      raise Error, 'an egress allow-list needs at least one host; use egress: "deny" for no network' if hosts.empty?
+
+      "allow:" + hosts.map { |h| h.to_s.strip }.join(",")
+    end
+
+    def self.env_list(env)
+      return nil if env.nil?
+      return env.map { |k, v| "#{k}=#{v}" } if env.is_a?(Hash)
+
+      env.to_a
+    end
+
+    private
+
+    def sb(id, *rest)
+      (["/kosa8/v1/sandboxes", Kosa8.enc(id)] + rest).join("/")
+    end
+
+    def collect(on_stdout, on_stderr, on_status)
+      out = +"".b
+      err = +"".b
+      result = nil
+      handler = lambda do |f|
+        next if result
+
+        if f["done"]
+          if f["error"]
+            raise StreamError.new(f["error"], stdout: Client.utf8(out), stderr: Client.utf8(err), daemon_message: f["error"])
+          end
+
+          result = ExecResult.new(exit_code: f["exit"].is_a?(Integer) ? f["exit"] : 0, stdout: Client.utf8(out),
+                                  stderr: Client.utf8(err))
+          next
+        end
+        data = f["data"]
+        next if data.nil? || data.empty?
+
+        case f["stream"]
+        when "stderr"
+          err << data
+          on_stderr&.call(data)
+        when "status"
+          on_status&.call(data)
+        else
+          out << data
+          on_stdout&.call(data)
+        end
+      end
+      yield handler
+      result || raise(StreamError.new("stream ended unexpectedly (no final frame)", stdout: Client.utf8(out),
+                                                                                    stderr: Client.utf8(err)))
+    end
+
+    def self.utf8(b)
+      b.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+
+    def run_branch(name, image, variant, timeout, approval)
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      b = ExploreBranch.new(name: name, variant: variant, exit: -1, output: "", error: nil)
+      # A freshly restored branch can refuse the first connection while its
+      # engine settles; retry connection-level failures briefly, as the CLI does.
+      4.times do |attempt|
+        begin
+          res = run(name, image, ["sh", "-c", variant], timeout: timeout, approval: approval)
+          b.exit = res.exit_code
+          b.output = (res.stdout + res.stderr).chomp
+          b.error = nil
+          break
+        rescue Error => e
+          b.error = e.message
+          b.output = (e.stdout + e.stderr).chomp if e.is_a?(StreamError)
+          break if e.is_a?(TimeoutError) || b.error !~ TRANSIENT
+
+          sleep((attempt + 1) * 0.5)
+        end
+      end
+      b.duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).to_i
+      b
+    end
+  end
+
+  # The client's sandbox methods bound to one sandbox id.
+  class Sandbox
+    attr_reader :id, :client
+
+    def initialize(client, id)
+      @client = client
+      @id = id
+    end
+
+    def inspect
+      "#<Kosa8::Sandbox #{@id}>"
+    end
+
+    def info
+      @client.get_sandbox(@id)
+    end
+
+    def checkpoints
+      @client.list_checkpoints(@id)
+    end
+
+    def images
+      @client.sandbox_images(@id)
+    end
+
+    def containers
+      @client.sandbox_containers(@id)
+    end
+
+    def egress
+      @client.sandbox_egress(@id)
+    end
+
+    def run(image, args = [], **kw)
+      @client.run(@id, image, args, **kw)
+    end
+
+    def start_container(image, args = [], **kw)
+      @client.start_container(@id, image, args, **kw)
+    end
+
+    def exec(container, args, **kw)
+      @client.exec(@id, container, args, **kw)
+    end
+
+    def pull(ref, **kw)
+      @client.pull_into_sandbox(@id, ref, **kw)
+    end
+
+    def fork(n = 1, **kw)
+      @client.fork(@id, n, **kw)
+    end
+
+    def explore(variants, **kw)
+      @client.explore(@id, variants, **kw)
+    end
+
+    { start: :start_sandbox, stop: :stop_sandbox, delete: :delete_sandbox, snapshot: :snapshot,
+      checkpoint: :checkpoint, rewind: :rewind }.each do |name, target|
+      define_method(name) { |**kw| @client.public_send(target, @id, **kw) }
+    end
+  end
+end

data/lib/kosa8/errors.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Kosa8
+  # Every error this gem raises. The daemon's own words are kept in
+  # +daemon_message+ and +remediation+, as @kosa8/sdk does.
+  class Error < StandardError
+    attr_reader :status, :daemon_message, :remediation, :method, :path, :body
+
+    def initialize(message = nil, status: nil, daemon_message: nil, remediation: nil, method: nil, path: nil, body: nil)
+      super(message)
+      @status = status
+      @daemon_message = daemon_message
+      @remediation = remediation
+      @method = method
+      @path = path
+      @body = body
+    end
+  end
+
+  class ConnectionError < Error; end # daemon unreachable
+  class ApiError < Error; end        # any HTTP error answer
+  class BadRequestError < ApiError; end   # 400
+  class AuthError < ApiError; end         # 401
+  class PolicyError < ApiError; end       # 403
+  class NotFoundError < ApiError; end     # 404
+  class ConflictError < ApiError; end     # 409
+  class UnsupportedError < ApiError; end  # 501
+
+  # 403 that a signed approval would lift; +approval+ is the daemon's refusal.
+  class ApprovalRequiredError < PolicyError
+    attr_reader :approval
+
+    def initialize(message = nil, approval: {}, **kw)
+      super(message, **kw)
+      @approval = approval
+    end
+  end
+
+  # A stream ended with an error frame (or none); output so far is kept.
+  class StreamError < Error
+    attr_reader :stdout, :stderr
+
+    def initialize(message = nil, stdout: "", stderr: "", **kw)
+      super(message, **kw)
+      @stdout = stdout
+      @stderr = stderr
+    end
+  end
+
+  class CheckpointError < Error; end
+  class TimeoutError < Error; end
+
+  BY_STATUS = {
+    400 => BadRequestError, 401 => AuthError, 403 => PolicyError,
+    404 => NotFoundError, 409 => ConflictError, 501 => UnsupportedError
+  }.freeze
+
+  # The typed error for an HTTP error answer: the daemon's message with its
+  # remediation in parentheses, as the CLI and MCP server print it.
+  def self.error_from_response(status, body, method:, path:)
+    msg = nil
+    rem = nil
+    approval = nil
+    if body.is_a?(Hash)
+      msg = body["error"].is_a?(String) && !body["error"].empty? ? body["error"] : body["message"]
+      rem = body["remediation"] if body["remediation"].is_a?(String) && !body["remediation"].empty?
+      approval = body["approval"] if status == 403 && body["approval"].is_a?(Hash) && body["approval"]["why"].is_a?(String)
+    elsif body.is_a?(String) && !body.strip.empty?
+      msg = body.strip
+    end
+    base = msg.is_a?(String) && !msg.empty? ? msg : "request failed with HTTP #{status}"
+    text = rem ? "#{base} (#{rem})" : base
+    kw = { status: status, daemon_message: msg, remediation: rem, method: method, path: path, body: body }
+    return ApprovalRequiredError.new(text, approval: approval, **kw) if approval
+
+    (BY_STATUS[status] || ApiError).new(text, **kw)
+  end
+end

data/lib/kosa8/transport.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "net/http"
+require "openssl"
+require "socket"
+require "uri"
+
+module Kosa8
+  APPROVAL_HEADER = "X-Kosa8-Approval"
+  ACTOR_HEADER = "X-Kosa8-Actor"
+  AGENT_TOKEN_HEADER = "X-Kosa8-Agent-Token"
+
+  # $HOME/.kosa8/run/kosa8.sock (pkg/paths).
+  def self.default_socket_path
+    File.join(Dir.home, ".kosa8", "run", "kosa8.sock")
+  end
+
+  # Where requests go: a unix socket or a remote worker.
+  Endpoint = Struct.new(:kind, :socket_path, :scheme, :host, :port, :base_path, :token, keyword_init: true) do
+    def target
+      kind == :unix ? "unix://#{socket_path}" : "#{scheme}://#{host}:#{port}"
+    end
+  end
+
+  def self.loopback?(host)
+    h = host.to_s.delete("[]")
+    h == "localhost" || h == "::1" || h.start_with?("127.")
+  end
+
+  # The CLI's KOSA8_HOST rules: no host means the local socket; https://,
+  # http://, tcp://, unix:// or a bare host:port select a worker; plain http to a
+  # non-loopback host is refused unless insecure (or KOSA8_INSECURE=1).
+  # KOSA8_TOKEN is used only for a host that came from KOSA8_HOST.
+  def self.resolve_endpoint(host: nil, socket_path: nil, token: nil, insecure: false, env: ENV)
+    explicit = !host.nil? && !host.empty?
+    raw = (explicit ? host : env["KOSA8_HOST"].to_s).strip.sub(%r{/+\z}, "")
+    return Endpoint.new(kind: :unix, socket_path: socket_path || default_socket_path) if raw.empty?
+
+    h = raw.sub(%r{\A([A-Za-z][A-Za-z0-9+.-]*)://}) { "#{Regexp.last_match(1).downcase}://" }
+    if h.start_with?("unix://")
+      return Endpoint.new(kind: :unix, socket_path: h.sub("unix://", ""))
+    elsif h.start_with?("tcp://")
+      h = "http://" + h.sub("tcp://", "")
+    elsif h =~ %r{\A([a-z][a-z0-9+.-]*)://} && !%w[http https].include?(Regexp.last_match(1))
+      raise Error, "KOSA8_HOST scheme \"#{Regexp.last_match(1)}\" is not supported; use http://, https://, tcp:// or unix://"
+    elsif h !~ %r{\Ahttps?://}
+      h = "http://" + h
+    end
+    u = begin
+      URI.parse(h)
+    rescue URI::InvalidURIError
+      nil
+    end
+    raise Error, "KOSA8_HOST #{raw.inspect} names no host" if u.nil? || u.host.nil? || u.host.empty?
+
+    if u.scheme == "http" && !insecure && env["KOSA8_INSECURE"] != "1" && !loopback?(u.host)
+      raise Error, "refusing to talk to #{u.host}:#{u.port} over plain http: the token and every request would cross " \
+                   "the network unencrypted. Use https://#{u.host}:#{u.port} (a worker behind a TLS-terminating tunnel " \
+                   "or proxy), or pass insecure: true / KOSA8_INSECURE=1 if this link is already private and trusted"
+    end
+    token = env["KOSA8_TOKEN"] if (token.nil? || token.empty?) && !explicit
+    Endpoint.new(kind: :tcp, scheme: u.scheme, host: u.host, port: u.port, base_path: u.path.to_s.sub(%r{/+\z}, ""),
+                 token: token && !token.empty? ? token : nil)
+  end
+
+  def self.enc(s)
+    URI.encode_www_form_component(s.to_s).gsub("+", "%20")
+  end
+
+  # Net::HTTP over a unix socket.
+  class UnixHTTP < Net::HTTP
+    attr_accessor :socket_path
+
+    def connect
+      io = UNIXSocket.new(@socket_path)
+      @socket = Net::BufferedIO.new(io, read_timeout: @read_timeout, continue_timeout: @continue_timeout,
+                                        debug_output: @debug_output)
+      on_connect
+    end
+  end
+
+  # An IO-like over an Enumerable of string chunks, for a chunked request body.
+  class ChunkReader
+    def initialize(chunks)
+      @enum = chunks.each
+      @buf = +""
+      @eof = false
+    end
+
+    def read(len = nil, outbuf = nil)
+      until @eof || (len && @buf.bytesize >= len)
+        begin
+          @buf << @enum.next.to_s.b
+        rescue StopIteration
+          @eof = true
+        end
+      end
+      return nil if @buf.empty? && len
+
+      out = len ? @buf.byteslice(0, len) : @buf
+      @buf = len ? (@buf.byteslice(len..-1) || +"") : +""
+      outbuf ? outbuf.replace(out) : out
+    end
+  end
+
+  # Sends requests to the daemon; the client builds on it.
+  class Transport
+    attr_reader :endpoint
+
+    def initialize(socket_path: nil, host: nil, token: nil, insecure: false, actor: "tool", agent_token: nil,
+                   headers: {}, timeout: nil, env: ENV)
+      @endpoint = Kosa8.resolve_endpoint(host: host, socket_path: socket_path, token: token, insecure: insecure, env: env)
+      raise Error, "actor must be human, agent or tool, not #{actor.inspect}" unless %w[human agent tool].include?(actor)
+
+      @actor = actor
+      @agent_token = agent_token || env["KOSA8_AGENT_TOKEN"]
+      @headers = headers || {}
+      @timeout = timeout
+    end
+
+    # One request; yields the Net::HTTPResponse (body unread) and returns the block's value.
+    def raw(method, path, query: nil, body: nil, raw_body: nil, approval: nil, timeout: nil)
+      full = (@endpoint.kind == :tcp ? @endpoint.base_path.to_s : "") + path
+      q = (query || {}).each_with_object([]) do |(k, v), a|
+        next if v.nil? || v == false
+
+        a << [k.to_s, v == true ? "1" : v.to_s]
+      end
+      full += "?" + URI.encode_www_form(q) unless q.empty?
+      req = Net::HTTPGenericRequest.new(method, !raw_body.nil? || !body.nil?, true, full)
+      req["Accept"] = "application/json"
+      req[ACTOR_HEADER] = @actor
+      @headers.each { |k, v| req[k] = v }
+      if !raw_body.nil?
+        req["Content-Type"] = "application/octet-stream"
+        if raw_body.is_a?(String)
+          req.body = raw_body
+        else
+          req["Transfer-Encoding"] = "chunked"
+          req.body_stream = raw_body.respond_to?(:read) ? raw_body : ChunkReader.new(raw_body)
+        end
+      elsif !body.nil?
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      req[APPROVAL_HEADER] = approval.strip if approval && !approval.strip.empty?
+      req[AGENT_TOKEN_HEADER] = @agent_token if @agent_token && !@agent_token.empty?
+      req["Authorization"] = "Bearer #{@endpoint.token}" if @endpoint.kind == :tcp && @endpoint.token
+      http = connection
+      t = timeout || @timeout
+      if t
+        http.open_timeout = [t, 30].min
+        http.read_timeout = t
+      end
+      begin
+        http.start { |h| h.request(req) { |resp| return yield(resp) } }
+      rescue Net::ReadTimeout, Net::OpenTimeout => e
+        raise TimeoutError.new("#{method} #{path} timed out talking to #{@endpoint.target}: #{e.message}",
+                               method: method, path: path)
+      rescue SystemCallError, IOError, SocketError, OpenSSL::SSL::SSLError => e
+        hint = e.is_a?(Errno::ENOENT) || e.is_a?(Errno::ECONNREFUSED) ? " (is kosa8 installed and its daemon running? start it with `kosa8 daemon start`)" : ""
+        raise ConnectionError.new("kosa8 daemon unreachable at #{@endpoint.target}: #{e.message}#{hint}",
+                                  method: method, path: path)
+      end
+    end
+
+    # A request whose answer is JSON.
+    def json(method, path, **kw)
+      raw(method, path, **kw) do |resp|
+        text = resp.read_body.to_s
+        parsed = decode(text)
+        raise Kosa8.error_from_response(resp.code.to_i, parsed, method: method, path: path) if resp.code.to_i >= 400
+
+        parsed
+      end
+    end
+
+    # A request whose answer is NDJSON frames; yields each, data decoded from base64.
+    def frames(method, path, **kw)
+      raw(method, path, **kw) do |resp|
+        if resp.code.to_i >= 400
+          raise Kosa8.error_from_response(resp.code.to_i, decode(resp.read_body.to_s), method: method, path: path)
+        end
+
+        buf = +""
+        resp.read_body do |chunk|
+          buf << chunk
+          while (i = buf.index("\n"))
+            line = buf.slice!(0..i).strip
+            yield Kosa8.decode_frame(JSON.parse(line)) unless line.empty?
+          end
+        end
+        line = buf.strip
+        yield Kosa8.decode_frame(JSON.parse(line)) unless line.empty?
+        nil
+      end
+    end
+
+    private
+
+    def connection
+      if @endpoint.kind == :unix
+        h = UnixHTTP.new("kosa8", 80)
+        h.socket_path = @endpoint.socket_path
+        h
+      else
+        h = Net::HTTP.new(@endpoint.host, @endpoint.port)
+        h.use_ssl = @endpoint.scheme == "https"
+        h
+      end
+    end
+
+    def decode(text)
+      return nil if text.strip.empty?
+
+      JSON.parse(text)
+    rescue JSON::ParserError
+      text
+    end
+  end
+
+  def self.decode_frame(f)
+    f["data"] = Base64.strict_decode64(f["data"]) if f["data"].is_a?(String) && !f["data"].empty?
+    f
+  end
+end

data/lib/kosa8/version.rb

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

data/lib/kosa8.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The Ruby SDK for kosa8: microVM sandboxes for AI agents.
+# Method for method it matches @kosa8/sdk (TypeScript), kosa8 (Python) and kosa8-go.
+require_relative "kosa8/version"
+require_relative "kosa8/errors"
+require_relative "kosa8/transport"
+require_relative "kosa8/checkpoints"
+require_relative "kosa8/client"

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: kosa8
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- kosa8
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-03 00:00:00.000000000 Z
+dependencies: []
+description: 'Typed client for the kosa8 daemon: sandboxes, run/exec streams, snapshots,
+  fork, best-of-N explore and checkpoints shared with the kosa8 CLI. No dependencies.'
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/kosa8.rb
+- lib/kosa8/checkpoints.rb
+- lib/kosa8/client.rb
+- lib/kosa8/errors.rb
+- lib/kosa8/transport.rb
+- lib/kosa8/version.rb
+homepage: https://kosa8.com
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/kosa8ai/kosa8-rb
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: 'Ruby SDK for kosa8: microVM sandboxes for AI agents'
+test_files: []