bsdkrun 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14072fa1b965040c136001ee65a8ef384205cbc119ef91658c387e2ed84100fb
-  data.tar.gz: c3981e13c6a964c084b3a1b54a051801ab373eda107f74dd869e789242c744df
+  metadata.gz: d1b2ffdacfec58cee3714b8ca96ecc133604655d423e264444d8f41ea88393e5
+  data.tar.gz: 848ec7c03c5489a41daf404135c3bbfdcfb126449ecb712ddf920ea7377bc822
 SHA512:
-  metadata.gz: 5dcbfd7f46c6e412acc0eccc6ccbe639fdffaf875a8ac56e8af0bbac4ec4654804a149f8eff78316ad0ca06cf2338414de320cf6ba05ca8a8ea11d579167c92e
-  data.tar.gz: 165af797cc3af4b111c9fad1c02f8f1b788d1e900e1d49715e8547b02e8849b768b21ed3cc81d4f922accb073b46f33f7400d7ff854f5868de92869802d3699a
+  metadata.gz: a86228909ae198caab0e630bac039179fc115317118f321a1aa193683ee6fb10ccfdc56ae1d05d42cad3ebad712897b5979c0b3b75cd0fe9b64bef0406d1d5ae
+  data.tar.gz: aef36636aef92124b1c78695648c929bfee4f60e134b9ef0a2d5588693827994e8023f62c91f39cd2d1a19c74e7e1a6a3d99a99c2aca9df51ba53bf03022368e

data/README.md

@@ -9,14 +9,14 @@ dependencies** — just the Ruby standard library (`open3`, `json`, `pathname`).
 ```ruby
 require "bsdkrun"
 
-box = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
+sbx = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
 
 # exec argv directly, with env / stdin / a PTY / a working dir:
-puts box.exec(["uname", "-a"]).text
-box.exec(["apk", "add", "curl"], throw_on_error: true)
-box.run_command("curl", ["-fsSL", "https://example.com"])
+puts sbx.exec(["uname", "-a"]).text
+sbx.exec(["apk", "add", "curl"], throw_on_error: true)
+sbx.run_command("curl", ["-fsSL", "https://example.com"])
 
-box.stop
+sbx.stop
 ```
 
 ## Install
@@ -77,15 +77,34 @@ Bsdkrun::Sandbox.create(os: "kernel", kernel: "netbsd", format: "elf", disk: "ro
 
 Every `create` runs the machine **detached** and returns a `Sandbox` handle.
 
+### Environment variables
+
+`env:` sets the guest environment for the machine's entrypoint. It is merged
+over the image's own config, so a key the image already defines is replaced
+rather than duplicated.
+
+```ruby
+sbx = Bsdkrun::Sandbox.create(
+  os: "linux",
+  image: "node:22",
+  env: { "NODE_ENV" => "production", "PORT" => "3000" },
+  command: ["node", "server.js"]
+)
+```
+
+Linux guests only — BSD guests boot their own init, so there is no generated
+init to export into; set those from `exec` after boot. For a single command
+rather than the whole machine, `exec` takes its own `env:`.
+
 ## Running commands
 
 `exec` is the primary programmatic entrypoint. No shell parsing — pass an argv
 array (or a program name plus `args:`).
 
 ```ruby
-box.exec(["ls", "-la", "/etc"])
+sbx.exec(["ls", "-la", "/etc"])
 
-box.exec("ruby",
+sbx.exec("ruby",
   args: ["-e", "puts ENV['X']"],
   env: { "X" => "hi" },
   cwd: "/app",
@@ -96,7 +115,7 @@ box.exec("ruby",
   throw_on_error: true)      # raise on non-zero exit (default: false)
 
 # Vercel-Sandbox-style alias:
-result = box.run_command("uname", ["-a"])
+result = sbx.run_command("uname", ["-a"])
 result.stdout       # raw stdout
 result.text         # stdout, trailing newlines trimmed
 result.exit_code
@@ -111,21 +130,74 @@ The callbacks run as chunks arrive, and the same bytes remain buffered in the
 returned result. They do not require `tty`; a PTY changes command semantics and
 may merge stderr into stdout.
 
+## Caching
+
+`sbx.cache` saves a guest directory under a key and restores it later, so a
+rebuild can pick up where the last one left off. **A miss is not an error** —
+check `restored` rather than rescuing.
+
+```ruby
+key = "deps-#{lock_hash}"
+hit = sbx.cache.restore(key: key, restore_keys: ["deps-"])
+unless hit.restored
+  sbx.exec(["npm", "ci"])
+  sbx.cache.save("/app/node_modules", key: key, compression: "zstd")
+end
+
+Bsdkrun::Caches.ls          # every stored entry, newest first
+Bsdkrun::Caches.rm([key])   # or Bsdkrun::Caches.rm(all: true)
+```
+
+`restore_keys` are prefixes tried in order when the exact key misses; within a
+prefix the newest matching entry wins, and `hit.key` says which one was used.
+Formats are `gzip` (default), `zstd`, `estargz` and `none`.
+
+Where entries live is host configuration, not an SDK concern: the default is
+this host's disk, and `BSDKRUN_CACHE_BACKEND=s3` + `BSDKRUN_CACHE_S3_*` (or
+`~/.config/bsdkrun/cache.toml`) points them at a bucket instead.
+
+## Files
+
+`sbx.fs` reads and writes files in the guest. Parent directories are created
+for you, and everything is byte-exact — `read_file` returns a binary string.
+
+```ruby
+sbx.fs.write_file("/app/main.py", "print('hi')")
+sbx.fs.write_file("/app/logo.png", png_bytes)
+
+text  = sbx.fs.read_text("/app/out.json")
+bytes = sbx.fs.read_file("/app/logo.png")
+
+sbx.fs.upload("./src", "/app/src")                       # file or directory
+sbx.fs.download("/app/dist", "./dist", recursive: true)
+```
+
+`upload` looks at the local path to decide whether to recurse; `download` cannot
+(the path is in the guest), so say so for a directory. A directory's *contents*
+land in the destination: uploading `./src` to `/app/src` leaves the guest's
+`/app/src` holding what `./src` holds.
+
+Failures raise `Bsdkrun::FileTransferFailed`, which carries the offending `path`.
+
+> Transfers ride the same in-guest agent as `exec`, so the sandbox must be
+> running. A directory copy also needs `tar` in the guest; single files need
+> only the shell every bootable image already has.
+
 ## Lifecycle & inventory
 
 ```ruby
-box  = Bsdkrun::Sandbox.create(os: "linux", image: "alpine", command: ["sleep", "300"])
-same = Bsdkrun::Sandbox.get(box.id)          # reconnect (prefix ok)
+sbx  = Bsdkrun::Sandbox.create(os: "linux", image: "alpine", command: ["sleep", "300"])
+same = Bsdkrun::Sandbox.get(sbx.id)          # reconnect (prefix ok)
 all  = Bsdkrun::Sandbox.list(all: true)      # Array<SandboxInfo>
 
-box.status        # SandboxInfo | nil
-box.running?      # true / false
-box.logs          # console log (String)
-box.shell         # interactive shell (inherits the terminal)
-box.stop          # BSD guests clean-poweroff; Linux SIGTERM
-box.start         # restart in place — resumes its own disk/rootfs (data persists)
-box.update(cpus: 4, mem: 2048)               # applies on next start
-box.remove(force: true)
+sbx.status        # SandboxInfo | nil
+sbx.running?      # true / false
+sbx.logs          # console log (String)
+sbx.shell         # interactive shell (inherits the terminal)
+sbx.stop          # BSD guests clean-poweroff; Linux SIGTERM
+sbx.start         # restart in place — resumes its own disk/rootfs (data persists)
+sbx.update(cpus: 4, mem: 2048)               # applies on next start
+sbx.remove(force: true)
 ```
 
 Host-level namespaces:
@@ -147,11 +219,11 @@ Bsdkrun::System.versions("netbsd")             # Array<String>
 Bsdkrun::Sandbox.create(os: "linux", image: "alpine", net: { ports: ["2222:22"] })
 
 # agent-managed key-based SSH
-box.ssh_setup                                  # install local ~/.ssh/*.pub keys
-box.ssh_setup(user: "tsiry", key: "~/.ssh/work.pub")
+sbx.ssh_setup                                  # install local ~/.ssh/*.pub keys
+sbx.ssh_setup(user: "tsiry", key: "~/.ssh/work.pub")
 
 # put a guest on your tailnet
-box.tailscale_up(authkey: "tskey-auth-...", hostname: "web")
+sbx.tailscale_up(authkey: "tskey-auth-...", hostname: "web")
 ```
 
 ### Global networks — reach machines by name
@@ -228,6 +300,37 @@ the new machine's id. `run_solo5` boots a MirageOS unikernel under the
 `stop`/`start`/`remove`/`update`/`commit` return a
 `CommandResult` (`exit_code`, `stdout`, `stderr`).
 
+### Snapshots
+
+A snapshot is a **copy-on-write clone of a machine's disk state** — instant to
+take, free until the two sides diverge. `branch` boots a new machine from one
+(or from a machine, which is snapshotted first); `restore`/`rollback` put one
+back, leaving the machine stopped. A BSD guest is powered off to snapshot it:
+a mounted UFS cannot be cloned consistently.
+
+```ruby
+snap = client.snapshot(machine_id, name: "before-upgrade")
+client.snapshots(machine: machine_id)      # newest first
+branch_id = client.branch(snap.name, name: "web-test")
+client.restore(machine_id, snap.name)      # or client.rollback(machine_id)
+client.remove_snapshots(snap.name)
+```
+
+### Docker
+
+bsdkrun runs one `docker:dind` microVM and serves its API on a host unix
+socket, so the host's own `docker` CLI drives the same engine these calls do.
+Starting is idempotent — the VM has a fixed name, so it resumes rather than
+creating a second.
+
+```ruby
+status = client.docker_start(cpus: 4, mem: 4096)   # or just docker_status
+puts status.socket
+client.docker_containers.each { |c| puts "#{c.name} #{c.state} #{c.ports}" }
+client.docker_container("restart", "web")
+puts client.docker_logs("web", tail: 50)
+```
+
 For a live terminal instead of a one-shot `exec`, use `shell`:
 
 ```ruby

data/lib/bsdkrun/args.rb

@@ -28,6 +28,17 @@ module Bsdkrun
     # +--name+ flag if a name is set.
     # @param o [Hash]
     # @return [Array<String>]
+    # +-e K=V+ per entry, sorted by key.
+    #
+    # A hash has no argv order of its own, so sorting is what makes the command
+    # line — and the tests that assert on it — deterministic. The guest sees the
+    # same environment either way.
+    def env_args(env)
+      return [] if env.nil? || env.empty?
+
+      env.to_h.sort_by { |k, _| k.to_s }.flat_map { |k, v| ["-e", "#{k}=#{v}"] }
+    end
+
     def name_args(o)
       o[:name] ? ["--name", o[:name].to_s] : []
     end
@@ -81,7 +92,9 @@ module Bsdkrun
       a.push("--initramfs") if opts[:initramfs]
       a.push("-v", opts[:volume]) if opts[:volume]
       Array(opts[:mounts]).each { |m| a.push("--mount", m) }
+      Array(opts[:attach_disk]).each { |d| a.push("--attach-disk", d) }
       a.push("--entrypoint", opts[:entrypoint]) if opts[:entrypoint]
+      a.concat(env_args(opts[:env]))
       a.push("--console", opts[:console]) if opts[:console]
       a.concat(net_args(opts[:net])).concat(name_args(opts)).concat(vm_args(opts))
       cmd = opts[:command]

data/lib/bsdkrun/cache.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Bsdkrun
+  # A stored cache entry, as +cache ls+ reports it.
+  CacheEntry = Struct.new(:key, :path, :compression, :size, :created, :digest, keyword_init: true) do
+    def self.from(row)
+      new(
+        key: row["key"].to_s,
+        path: row["path"].to_s,
+        compression: row["compression"].to_s,
+        size: row["size"].to_i,
+        created: row["created"].to_i,
+        digest: row["digest"].to_s
+      )
+    end
+  end
+
+  # What a restore did. A miss is not an error — check +restored+.
+  RestoreResult = Struct.new(
+    :restored, :requested_key, :key, :path, :size, :compression, :created,
+    keyword_init: true
+  )
+
+  # Save and restore guest directories under a key, reached as {Sandbox#cache}.
+  #
+  # Entries are keyed, so a rebuild can pick up where the last one left off:
+  #
+  #   hit = sbx.cache.restore(key: key, restore_keys: ["deps-"])
+  #   unless hit.restored
+  #     sbx.exec(["npm", "ci"])
+  #     sbx.cache.save("/app/node_modules", key: key)
+  #   end
+  #
+  # Where entries live — host disk or S3 — is host configuration, not an SDK
+  # concern: set +BSDKRUN_CACHE_BACKEND+ / +BSDKRUN_CACHE_S3_*+, or write
+  # +~/.config/bsdkrun/cache.toml+.
+  class Cache
+    # @param id [String] the machine's id.
+    def initialize(id)
+      @id = id
+    end
+
+    # Archive the guest directory at +path+ under +key+.
+    #
+    # @param path [String] absolute path in the guest.
+    # @param key [String] key to store under.
+    # @param compression [String] gzip (default), zstd, estargz or none.
+    # @param force [Boolean] replace an entry that already has this key.
+    # @return [CacheEntry]
+    def save(path, key:, compression: "gzip", force: false)
+      args = ["cache", "save", "#{@id}:#{path}", "--key", key, "--json"]
+      args += ["--compression", compression] unless compression == "gzip"
+      args << "--force" if force
+      CacheEntry.from(json(args, "bsdkrun cache save"))
+    end
+
+    # Restore a stored tree.
+    #
+    # @param key [String]
+    # @param path [String, nil] defaults to where the entry was saved from.
+    # @param restore_keys [Array<String>] prefixes tried in order on a miss.
+    # @return [RestoreResult]
+    def restore(key:, path: nil, restore_keys: [])
+      target = path ? "#{@id}:#{path}" : @id
+      args = ["cache", "restore", target, "--key", key, "--json"]
+      args += ["--restore-keys", *restore_keys] unless restore_keys.empty?
+      row = json(args, "bsdkrun cache restore")
+      RestoreResult.new(
+        restored: !!row["restored"],
+        requested_key: row["requested_key"].to_s,
+        key: row["key"],
+        path: row["path"],
+        size: row["size"],
+        compression: row["compression"],
+        created: row["created"]
+      )
+    end
+
+    private
+
+    def json(args, label)
+      out = Process.run!(args, label: label).stdout
+      JSON.parse(out.strip.empty? ? "{}" : out)
+    end
+  end
+
+  # Host-level cache operations, mirroring {Bsdkrun.volumes}.
+  module Caches
+    module_function
+
+    # @return [Array<CacheEntry>] every stored entry, newest first.
+    def ls
+      out = Process.run!(["cache", "ls", "--json"], label: "bsdkrun cache ls").stdout
+      JSON.parse(out.strip.empty? ? "[]" : out).map { |row| CacheEntry.from(row) }
+    end
+
+    # Remove entries by key, or every one with <tt>all: true</tt>.
+    # @return [void]
+    def rm(keys = [], all: false)
+      args = ["cache", "rm"]
+      if all
+        args << "--all"
+      else
+        args += Array(keys)
+      end
+      Process.run!(args, label: "bsdkrun cache rm")
+      nil
+    end
+  end
+end

data/lib/bsdkrun/client.rb

@@ -35,10 +35,16 @@ module Bsdkrun
     # +web/src/lib/api.ts+'s +MACHINE_FIELDS+ fragment exactly.
     MACHINE_FIELDS = <<~GQL.freeze
       id name image kind command status running exitCode pid detached
-      cpus mem volume stateDir createdAt finishedAt network netIp
+      cpus mem volume stateDir createdAt finishedAt network netIp origin
       ports { bind host guest }
     GQL
 
+    # The +Snapshot+ selection, likewise shared by every snapshot document.
+    SNAPSHOT_FIELDS = <<~GQL.freeze
+      id name machineId machineName kind image path parent description
+      cpus mem size createdAt ports { bind host guest }
+    GQL
+
     # @return [String] the GraphQL endpoint URL (normalized).
     attr_reader :url
 
@@ -242,6 +248,269 @@ module Bsdkrun
       )
     end
 
+    # ---- ai agents -------------------------------------------------------------
+    #
+    # A sandbox is a machine, so its terminal is the ordinary {#shell} with the
+    # argv {#ai_shell_command} returns.
+
+    AI_AGENT_FIELDS = "id label flavor description installed running"
+    AI_SESSION_FIELDS = "id name agent running workspace createdAt"
+
+    # The coding agents, and whether each one's sandbox image is built.
+    # @return [Array<AiAgent>]
+    def ai_agents
+      data = request("{ aiAgents { #{AI_AGENT_FIELDS} } }")
+      (data["aiAgents"] || []).map { |a| AiAgent.from_graphql(a) }
+    end
+
+    # Agent sandboxes, newest first.
+    # @return [Array<AiSession>]
+    def ai_sessions
+      data = request("{ aiSessions { #{AI_SESSION_FIELDS} } }")
+      (data["aiSessions"] || []).map { |s| AiSession.from_graphql(s) }
+    end
+
+    # Start (or reuse) a sandbox; returns its machine id.
+    #
+    # @param agent [String] +claude+, +codex+, ...
+    # @param workspace [String, nil] a directory **on the engine's host**.
+    # @param new [Boolean] boot a second sandbox against the same saved login.
+    # @return [String]
+    def ai_start(agent, cpus: nil, mem: nil, workspace: nil, new: false)
+      data = request(
+        "mutation($input:AiStartInput!){ aiStart(input:$input) }",
+        { input: { agent: agent, cpus: cpus, mem: mem,
+                   workspace: workspace, new: new } }
+      )
+      data["aiStart"].to_s
+    end
+
+    # The argv that starts the agent's TUI — pass it to {#shell}.
+    # @return [Array<String>]
+    def ai_shell_command(agent, machine_id)
+      data = request(
+        "query($agent:String!,$machineId:String!){ " \
+        "aiShellCommand(agent:$agent, machineId:$machineId) }",
+        { agent: agent, machineId: machine_id }
+      )
+      Array(data["aiShellCommand"])
+    end
+
+    # Stop an agent's sandboxes. Its saved login survives.
+    # @return [CommandResult]
+    def ai_stop(agent)
+      run_command_mutation(
+        "aiStop",
+        "mutation($agent:String!){ aiStop(agent:$agent){ exitCode stdout stderr } }",
+        { agent: agent }
+      )
+    end
+
+    # Remove an agent's sandboxes, and unless +keep_home+ its saved login too.
+    # @return [CommandResult]
+    def ai_remove(agent, keep_home: false)
+      run_command_mutation(
+        "aiRemove",
+        "mutation($agent:String!,$keepHome:Boolean!){ " \
+        "aiRemove(agent:$agent, keepHome:$keepHome){ exitCode stdout stderr } }",
+        { agent: agent, keepHome: keep_home }
+      )
+    end
+
+    # ---- docker --------------------------------------------------------------
+    #
+    # bsdkrun runs one +docker:dind+ microVM and serves its API on a host unix
+    # socket, so these drive the same engine the host's +docker+ CLI does.
+
+    DOCKER_STATUS_FIELDS = <<~GQL.freeze
+      running machineId machineRunning socket socketReady apiPort version
+      containers images mounts disk diskSize
+    GQL
+
+    DOCKER_CONTAINER_FIELDS = "id name image command state status ports created"
+
+    # Is the Docker engine up, and where is its socket?
+    # @return [DockerStatus]
+    def docker_status
+      data = request("{ dockerStatus { #{DOCKER_STATUS_FIELDS} } }")
+      DockerStatus.from_graphql(data["dockerStatus"])
+    end
+
+    # Containers in the engine.
+    # @param all [Boolean] include stopped ones (default true).
+    # @return [Array<DockerContainer>]
+    def docker_containers(all: true)
+      data = request(
+        "query($all:Boolean!){ dockerContainers(all:$all){ #{DOCKER_CONTAINER_FIELDS} } }",
+        { all: all }
+      )
+      (data["dockerContainers"] || []).map { |c| DockerContainer.from_graphql(c) }
+    end
+
+    # Start (or resume) the engine, returning its status once it answers.
+    #
+    # Idempotent: the VM has a fixed name, so this resumes the existing one
+    # rather than creating a second.
+    #
+    # @param cpus [Integer, nil]
+    # @param mem [Integer, nil]
+    # @param mounts [Array<String>] host dirs to share, +PATH+ or +HOST:GUEST+.
+    # @param no_home [Boolean] do not share +$HOME+ (shared by default).
+    # @param publish_bind [String, nil] +mirror+ (default) or a fixed address.
+    # @param disk_size [String, nil] a dedicated image store, e.g. +60G+.
+    # @return [DockerStatus]
+    def docker_start(cpus: nil, mem: nil, mounts: [], no_home: false,
+                     publish_bind: nil, disk_size: nil)
+      data = request(
+        "mutation($input:DockerStartInput!){ dockerStart(input:$input){ " \
+        "#{DOCKER_STATUS_FIELDS} } }",
+        { input: { cpus: cpus, mem: mem, mounts: Array(mounts), noHome: no_home,
+                   publishBind: publish_bind, diskSize: disk_size } }
+      )
+      DockerStatus.from_graphql(data["dockerStart"])
+    end
+
+    # Stop the engine. Images and containers stay on its disk.
+    # @return [CommandResult]
+    def docker_stop
+      run_command_mutation(
+        "dockerStop",
+        "mutation{ dockerStop{ exitCode stdout stderr } }",
+        {}
+      )
+    end
+
+    # start | stop | restart | kill | pause | unpause | rm.
+    # @param action [String]
+    # @param ids [String, Array<String>]
+    # @return [CommandResult]
+    def docker_container(action, ids)
+      run_command_mutation(
+        "dockerContainer",
+        "mutation($action:String!,$ids:[String!]!){ " \
+        "dockerContainer(action:$action, ids:$ids){ exitCode stdout stderr } }",
+        { action: action, ids: Array(ids) }
+      )
+    end
+
+    # One container's logs (stdout+stderr, most recent +tail+ lines).
+    # @param id [String]
+    # @param tail [Integer]
+    # @return [String]
+    def docker_logs(id, tail: 200)
+      data = request(
+        "query($id:String!,$tail:Int!){ dockerContainerLogs(id:$id, tail:$tail) }",
+        { id: id, tail: tail }
+      )
+      data["dockerContainerLogs"].to_s
+    end
+
+    # ---- snapshots ---------------------------------------------------------
+    #
+    # A snapshot is a copy-on-write clone of a machine's disk state: instant to
+    # take, free until the two sides diverge. {#branch} boots a new machine
+    # from one; {#restore}/{#rollback} put one back.
+
+    # List snapshots, newest first.
+    # @param machine [String, nil] only this machine's, when given.
+    # @return [Array<SnapshotInfo>]
+    def snapshots(machine: nil)
+      data = request(
+        "query($machine:String){ snapshots(machine:$machine){ #{SNAPSHOT_FIELDS} } }",
+        { machine: machine }
+      )
+      (data["snapshots"] || []).map { |s| SnapshotInfo.from_graphql(s) }
+    end
+
+    # Capture a machine's disk state.
+    #
+    # A BSD guest is powered off first — a mounted UFS cannot be cloned
+    # consistently — so the machine is left stopped; {#start} brings it back.
+    #
+    # @param id [String]
+    # @param name [String, nil] defaults to +<machine>-<n>+.
+    # @param description [String]
+    # @return [SnapshotInfo]
+    def snapshot(id, name: nil, description: "")
+      data = request(
+        "mutation($id:String!,$name:String,$description:String!){ " \
+        "snapshotMachine(id:$id, name:$name, description:$description){ #{SNAPSHOT_FIELDS} } }",
+        { id: id, name: name, description: description }
+      )
+      SnapshotInfo.from_graphql(data["snapshotMachine"])
+    end
+
+    # Delete snapshots and their data. Machines branched from them are
+    # unaffected.
+    # @param names [String, Array<String>]
+    # @return [CommandResult]
+    def remove_snapshots(names)
+      run_command_mutation(
+        "removeSnapshots",
+        "mutation($names:[String!]!){ removeSnapshots(names:$names){ exitCode stdout stderr } }",
+        { names: Array(names) }
+      )
+    end
+
+    # Put a machine's disk state back to one of its snapshots.
+    #
+    # +force+ stops the machine first (it holds the very files being
+    # replaced); +backup+ snapshots the state being overwritten, which is a
+    # CoW clone and therefore free. The machine is left stopped.
+    #
+    # @param id [String]
+    # @param snapshot [String]
+    # @param force [Boolean]
+    # @param backup [Boolean]
+    # @return [CommandResult]
+    def restore(id, snapshot, force: true, backup: true)
+      run_command_mutation(
+        "restoreMachine",
+        "mutation($id:String!,$snapshot:String!,$force:Boolean!,$backup:Boolean!){ " \
+        "restoreMachine(id:$id, snapshot:$snapshot, force:$force, backup:$backup){ " \
+        "exitCode stdout stderr } }",
+        { id: id, snapshot: snapshot, force: force, backup: backup }
+      )
+    end
+
+    # Restore a machine to its most recent snapshot.
+    # @param id [String]
+    # @param force [Boolean]
+    # @param backup [Boolean]
+    # @return [CommandResult]
+    def rollback(id, force: true, backup: true)
+      run_command_mutation(
+        "rollbackMachine",
+        "mutation($id:String!,$force:Boolean!,$backup:Boolean!){ " \
+        "rollbackMachine(id:$id, force:$force, backup:$backup){ exitCode stdout stderr } }",
+        { id: id, force: force, backup: backup }
+      )
+    end
+
+    # Boot a NEW machine from a snapshot — or from a machine, which is
+    # snapshotted first — and return the new machine's id.
+    #
+    # The state is cloned, never booted in place, so the source is untouched
+    # and one snapshot can be branched any number of times. With no +ports+,
+    # the snapshot's own forwards are inherited, with any host port that is
+    # already taken swapped for a free one.
+    #
+    # @param snapshot [String] snapshot name/id, or a machine id.
+    # @param name [String, nil]
+    # @param cpus [Integer, nil]
+    # @param mem [Integer, nil]
+    # @param ports [Array<String>]
+    # @param no_ports [Boolean]
+    # @return [String] the new machine's id.
+    def branch(snapshot, name: nil, cpus: nil, mem: nil, ports: [], no_ports: false)
+      data = request(
+        "mutation($input:BranchInput!){ branchSnapshot(input:$input) }",
+        { input: { snapshot: snapshot, name: name, cpus: cpus, mem: mem,
+                   ports: Array(ports), noPorts: no_ports } }
+      )
+      data["branchSnapshot"].to_s
+    end
+
     # One-shot console log fetch. Use {#follow_logs} to stream instead.
     # @param id [String]
     # @param boot [Boolean] bsdkrun's own boot log instead of the guest console.
@@ -293,6 +562,7 @@ module Bsdkrun
         net: net_input(o[:net]),
         volume: o[:volume],
         mounts: o[:mounts] || [],
+        attachDisk: o[:attach_disk] || [],
         env: o[:env] || [],
         entrypoint: o[:entrypoint],
         initramfs: o[:initramfs] || false,

data/lib/bsdkrun/errors.rb

@@ -50,6 +50,19 @@ module Bsdkrun
     end
   end
 
+  # A guest filesystem operation was refused (see {FileSystem}).
+  class FileTransferFailed < Error
+    # @return [String] the path that could not be transferred.
+    attr_reader :path
+
+    # @param message [String]
+    # @param path [String]
+    def initialize(message, path)
+      @path = path
+      super(message)
+    end
+  end
+
   # A GraphQL request to a remote +bsdkrund+ daemon failed — a transport
   # failure, a non-JSON response, or a +body["errors"]+ entry that was not an
   # auth failure. Mirrors +web/src/lib/graphql.ts+'s +GraphQLError+.

data/lib/bsdkrun/filesystem.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Bsdkrun
+  # Files in a running sandbox, reached as {Sandbox#fs}.
+  #
+  # Every call goes through the guest's exec agent, so the sandbox has to be
+  # running — there is no offline write.
+  #
+  # @example
+  #   sbx.fs.write_file("/app/main.py", "print('hi')")
+  #   sbx.fs.read_text("/app/out.json")
+  #   sbx.fs.upload("./src", "/app/src")
+  #   sbx.fs.download("/app/dist", "./dist", recursive: true)
+  class FileSystem
+    # @param id [String] the machine's id.
+    def initialize(id)
+      @id = id
+    end
+
+    # Write +data+ to +path+ in the guest, creating parent directories.
+    #
+    # @param path [String] absolute path in the guest.
+    # @param data [String] text or binary content.
+    # @return [void]
+    # @raise [FileTransferFailed]
+    def write_file(path, data)
+      res = Process.run(["cp", "-", "#{@id}:#{path}"], stdin: data, binary: true)
+      check!(res, path)
+      nil
+    end
+
+    # Read +path+ from the guest as bytes (ASCII-8BIT).
+    #
+    # @param path [String]
+    # @return [String] binary string.
+    # @raise [FileTransferFailed]
+    def read_file(path)
+      res = Process.run(["cp", "#{@id}:#{path}", "-"], binary: true)
+      check!(res, path)
+      res.stdout
+    end
+
+    # Read +path+ from the guest and tag it with +encoding+.
+    #
+    # @param path [String]
+    # @param encoding [String]
+    # @return [String]
+    def read_text(path, encoding: "UTF-8")
+      read_file(path).force_encoding(encoding)
+    end
+
+    # Copy a host file or directory into the guest.
+    #
+    # A directory's *contents* land in +remote_path+, so
+    # <tt>upload("./src", "/app/src")</tt> leaves the guest's +/app/src+ holding
+    # what +./src+ holds. Whether it recurses is decided by looking at the local
+    # path, so callers do not have to say which kind of thing it is.
+    #
+    # @param local_path [String]
+    # @param remote_path [String]
+    # @return [void]
+    # @raise [FileTransferFailed]
+    def upload(local_path, remote_path)
+      unless File.exist?(local_path)
+        raise FileTransferFailed.new("cannot upload #{local_path}: no such file or directory",
+                                     local_path)
+      end
+      args = ["cp"]
+      args << "-r" if File.directory?(local_path)
+      args += [local_path.to_s, "#{@id}:#{remote_path}"]
+      check!(Process.run(args), local_path)
+      nil
+    end
+
+    # Copy a file or directory out of the guest onto the host.
+    #
+    # Pass <tt>recursive: true</tt> for a directory; unlike {#upload} it cannot
+    # be detected here, because the path lives in the guest and answering would
+    # cost an extra round trip.
+    #
+    # @param remote_path [String]
+    # @param local_path [String]
+    # @param recursive [Boolean]
+    # @return [void]
+    # @raise [FileTransferFailed]
+    def download(remote_path, local_path, recursive: false)
+      args = ["cp"]
+      args << "-r" if recursive
+      args += ["#{@id}:#{remote_path}", local_path.to_s]
+      check!(Process.run(args), remote_path)
+      nil
+    end
+
+    private
+
+    def check!(res, path)
+      return if res.exit_code.zero?
+
+      # The CLI already explains these well; strip its "Error: " prefix.
+      text = res.stderr.to_s.strip.sub(/\AError:\s*/, "")
+      text = "file transfer failed for #{path}" if text.empty?
+      raise FileTransferFailed.new(text, path)
+    end
+  end
+end

data/lib/bsdkrun/process.rb

@@ -26,15 +26,23 @@ module Bsdkrun
     # @param env [Hash] extra environment merged onto the process env.
     # @param stdin [String, nil] data piped to the child's stdin.
     # @param log_level [Integer] bsdkrun global log level (0=off .. 5=trace).
+    # @param binary [Boolean] keep stdout as bytes (ASCII-8BIT) instead of text.
+    #   Needed by {FileSystem#read_file}: appending a chunk of arbitrary bytes to
+    #   a UTF-8 buffer raises Encoding::CompatibilityError, so a PNG read back
+    #   out of a guest would blow up mid-transfer rather than return.
     # @return [RawResult]
-    def run(args, env: {}, stdin: nil, log_level: 0, on_stdout: nil, on_stderr: nil)
+    def run(args, env: {}, stdin: nil, log_level: 0, on_stdout: nil, on_stderr: nil, binary: false)
       bin = Binary.resolve
       full = ["--log-level", log_level.to_s, *args]
       merged_env = env.to_h.transform_keys(&:to_s).transform_values(&:to_s)
-      out = +""
+      out = binary ? (+"").b : +""
       err = +""
       status = nil
       Open3.popen3(merged_env, bin, *full) do |child_in, child_out, child_err, wait|
+        if binary
+          child_in.binmode
+          child_out.binmode
+        end
         writer = Thread.new { child_in.write(stdin) if stdin; child_in.close }
         stdout_reader = Thread.new do
           while (chunk = child_out.readpartial(8192) rescue nil)

data/lib/bsdkrun/sandbox.rb

@@ -9,9 +9,9 @@ module Bsdkrun
   # with {Sandbox.list}.
   #
   # @example
-  #   box = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
-  #   box.exec(["uname", "-a"]).text
-  #   box.stop
+  #   sbx = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
+  #   sbx.exec(["uname", "-a"]).text
+  #   sbx.stop
   class Sandbox
     ID_RE = /\A[0-9a-f]{6,}\z/
     SSH_PORT_RE = /ssh -p (\d+)/
@@ -32,6 +32,18 @@ module Bsdkrun
       @ssh_port = ssh_port
     end
 
+    # Read and write files in the guest.
+    # @return [FileSystem]
+    def fs
+      @fs ||= FileSystem.new(@id)
+    end
+
+    # Save and restore guest directories under a key.
+    # @return [Cache]
+    def cache
+      @cache ||= Cache.new(@id)
+    end
+
     class << self
       # Boot a new microVM and return a handle to it.
       #

data/lib/bsdkrun/types.rb

@@ -34,7 +34,7 @@ module Bsdkrun
   SandboxInfo = Data.define(
     :id, :name, :image, :kind, :command, :status, :running, :exit_code,
     :pid, :detached, :cpus, :mem, :volume, :state_dir, :network, :net_ip,
-    :created_at, :finished_at, :ports
+    :created_at, :finished_at, :ports, :origin
   ) do
     # Map a +ps --json+ row (String keys) to a typed instance.
     # @param row [Hash]
@@ -60,7 +60,8 @@ module Bsdkrun
         net_ip: row["net_ip"],
         created_at: row["created_at"].to_i,
         finished_at: to_i_or_nil(row["finished_at"]),
-        ports: (row["ports"] || []).map { |p| PortForward.from_row(p) }
+        ports: (row["ports"] || []).map { |p| PortForward.from_row(p) },
+        origin: row["origin"]
       )
     end
 
@@ -96,11 +97,190 @@ module Bsdkrun
         net_ip: m["netIp"],
         created_at: m["createdAt"].to_i,
         finished_at: to_i_or_nil(m["finishedAt"]),
-        ports: (m["ports"] || []).map { |p| PortForward.from_row(p) }
+        ports: (m["ports"] || []).map { |p| PortForward.from_row(p) },
+        origin: m["origin"]
       )
     end
   end
 
+  # A machine snapshot: one machine's disk state, captured under a name.
+  #
+  # A copy-on-write clone rather than a memory image — the files the guest
+  # wrote, not what it was executing. {Bsdkrun::Client#branch} boots a new
+  # machine from one; {Bsdkrun::Client#restore} puts one back.
+  SnapshotInfo = Data.define(
+    :id, :name, :machine_id, :machine_name, :kind, :image, :path, :parent,
+    :description, :cpus, :mem, :ports, :size, :created_at
+  ) do
+    # Map a GraphQL +Snapshot+ (camelCase) to a typed instance.
+    # @param s [Hash]
+    # @return [SnapshotInfo]
+    def self.from_graphql(s)
+      new(
+        id: s["id"].to_s,
+        name: s["name"].to_s,
+        machine_id: s["machineId"].to_s,
+        machine_name: (s["machineName"] || "").to_s,
+        kind: s["kind"].to_s,
+        image: (s["image"] || "").to_s,
+        path: (s["path"] || "").to_s,
+        parent: s["parent"],
+        description: (s["description"] || "").to_s,
+        cpus: s["cpus"].to_i,
+        mem: s["mem"].to_i,
+        ports: (s["ports"] || []).map { |p| PortForward.from_row(p) },
+        size: s["size"],
+        created_at: s["createdAt"].to_i
+      )
+    end
+
+    # Map a +bsdkrun snapshots --json+ row (snake_case).
+    # @param row [Hash]
+    # @return [SnapshotInfo]
+    def self.from_row(row)
+      new(
+        id: row["id"].to_s,
+        name: row["name"].to_s,
+        machine_id: row["machine_id"].to_s,
+        machine_name: (row["machine_name"] || "").to_s,
+        kind: row["kind"].to_s,
+        image: (row["image"] || "").to_s,
+        path: (row["path"] || "").to_s,
+        parent: row["parent"],
+        description: (row["description"] || "").to_s,
+        cpus: row["cpus"].to_i,
+        mem: row["mem"].to_i,
+        ports: (row["ports"] || []).map { |p| PortForward.from_row(p) },
+        size: row["size"],
+        created_at: row["created_at"].to_i
+      )
+    end
+  end
+
+  # A coding agent bsdkrun can sandbox.
+  #
+  # Each runs in a disposable microVM with a persistent login, a shared skills
+  # store, and only the folder you choose to share.
+  AiAgent = Data.define(
+    :id, :label, :flavor, :description, :installed, :running
+  ) do
+    # @param a [Hash]
+    # @return [AiAgent]
+    def self.from_graphql(a)
+      new(
+        id: a["id"].to_s,
+        label: a["label"].to_s,
+        flavor: a["flavor"].to_s,
+        description: (a["description"] || "").to_s,
+        installed: !!a["installed"],
+        running: a["running"].to_i
+      )
+    end
+
+    class << self
+      alias from_row from_graphql
+    end
+  end
+
+  # One agent sandbox. It is a machine, so +logs+/+stop+ work on +id+.
+  AiSession = Data.define(
+    :id, :name, :agent, :running, :workspace, :created_at
+  ) do
+    # @param s [Hash]
+    # @return [AiSession]
+    def self.from_graphql(s)
+      new(
+        id: s["id"].to_s,
+        name: s["name"].to_s,
+        agent: s["agent"].to_s,
+        running: !!s["running"],
+        workspace: s["workspace"],
+        created_at: (s["createdAt"] || s["created_at"]).to_i
+      )
+    end
+
+    class << self
+      alias from_row from_graphql
+    end
+  end
+
+  # The Docker engine VM: whether it is up, and how to reach it.
+  #
+  # bsdkrun runs one +docker:dind+ microVM and serves its API on a host unix
+  # socket, so the host's own +docker+ CLI drives the same engine.
+  DockerStatus = Data.define(
+    :running, :machine_id, :machine_running, :socket, :socket_ready, :api_port,
+    :version, :containers, :images, :mounts, :disk, :disk_size
+  ) do
+    # @param s [Hash] a GraphQL +DockerStatus+ (camelCase).
+    # @return [DockerStatus]
+    def self.from_graphql(s)
+      new(
+        running: !!s["running"],
+        machine_id: s["machineId"],
+        machine_running: !!s["machineRunning"],
+        socket: s["socket"].to_s,
+        socket_ready: !!s["socketReady"],
+        api_port: to_i_or_nil(s["apiPort"]),
+        version: s["version"],
+        containers: to_i_or_nil(s["containers"]),
+        images: to_i_or_nil(s["images"]),
+        mounts: Array(s["mounts"]),
+        disk: s["disk"],
+        disk_size: to_i_or_nil(s["diskSize"])
+      )
+    end
+
+    # @param row [Hash] a +bsdkrun docker status --json+ row (snake_case).
+    # @return [DockerStatus]
+    def self.from_row(row)
+      new(
+        running: !!row["running"],
+        machine_id: row["machine_id"],
+        machine_running: !!row["machine_running"],
+        socket: row["socket"].to_s,
+        socket_ready: !!row["socket_ready"],
+        api_port: to_i_or_nil(row["api_port"]),
+        version: row["version"],
+        containers: to_i_or_nil(row["containers"]),
+        images: to_i_or_nil(row["images"]),
+        mounts: Array(row["mounts"]),
+        disk: row["disk"],
+        disk_size: to_i_or_nil(row["disk_size"])
+      )
+    end
+  end
+
+  # A container in the Docker engine VM — a trimmed +docker ps+ row.
+  DockerContainer = Data.define(
+    :id, :name, :image, :command, :state, :status, :ports, :created
+  ) do
+    # @return [Boolean] whether the container is up.
+    def running?
+      state == "running"
+    end
+
+    # Both the GraphQL object and +docker ps --json+ use these field names.
+    # @param c [Hash]
+    # @return [DockerContainer]
+    def self.from_graphql(c)
+      new(
+        id: c["id"].to_s,
+        name: c["name"].to_s,
+        image: c["image"].to_s,
+        command: (c["command"] || "").to_s,
+        state: c["state"].to_s,
+        status: c["status"].to_s,
+        ports: Array(c["ports"]),
+        created: c["created"].to_i
+      )
+    end
+
+    class << self
+      alias from_row from_graphql
+    end
+  end
+
   # An image as reported by +bsdkrun images --json+.
   ImageInfo = Data.define(:id, :reference, :digest, :size, :rootfs, :created_at) do
     # @param row [Hash]

data/lib/bsdkrun/version.rb

@@ -2,5 +2,5 @@
 
 module Bsdkrun
   # The bsdkrun Ruby SDK version.
-  VERSION = "0.3.2"
+  VERSION = "0.5.0"
 end

data/lib/bsdkrun.rb

@@ -5,6 +5,8 @@ require_relative "bsdkrun/errors"
 require_relative "bsdkrun/binary"
 require_relative "bsdkrun/process"
 require_relative "bsdkrun/args"
+require_relative "bsdkrun/cache"
+require_relative "bsdkrun/filesystem"
 require_relative "bsdkrun/types"
 require_relative "bsdkrun/sandbox"
 require_relative "bsdkrun/images"
@@ -23,9 +25,9 @@ require_relative "bsdkrun/client"
 # @example
 #   require "bsdkrun"
 #
-#   box = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
-#   puts box.exec(["uname", "-a"]).text
-#   box.stop
+#   sbx = Bsdkrun::Sandbox.create(os: "linux", image: "alpine")
+#   puts sbx.exec(["uname", "-a"]).text
+#   sbx.stop
 module Bsdkrun
   class << self
     # Force the SDK to use a specific +bsdkrun+ binary, bypassing discovery.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsdkrun
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Tsiry Sandratraina
@@ -51,8 +51,10 @@ files:
 - lib/bsdkrun.rb
 - lib/bsdkrun/args.rb
 - lib/bsdkrun/binary.rb
+- lib/bsdkrun/cache.rb
 - lib/bsdkrun/client.rb
 - lib/bsdkrun/errors.rb
+- lib/bsdkrun/filesystem.rb
 - lib/bsdkrun/images.rb
 - lib/bsdkrun/networks.rb
 - lib/bsdkrun/process.rb