boxd 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f49524201855c87e4519d024cb44bea9aa8e1025e447063abb6bc54d051ed45d
+  data.tar.gz: 1477bd7f3e17f61fc33774ba39ee6556b410a6d1b61fcf93cd6f97caf50374e4
+SHA512:
+  metadata.gz: 726612934833830a0280c892c10edc75a0dc3ce7d9cfc88f3d83dc4177bd32335e6558c25336b35bef226c783eca578c92e17665b476ae3d194d22b9d5949fb0
+  data.tar.gz: 9650055697701481d8e7cea406db62c7cd37604b0a8c1e45ef8b1a5b9f95a3ebc494ab504edee7df24e384008cad5a4b144f9ccbe4e483ed1760f062c60b74a9

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 — 2026-06-04
+
+Initial release. CLI-backed v0.
+
+- `Boxd::Compute` entry point with `#boxes` / `#whoami`
+- `Boxd::BoxService` with `#list`, `#get`, `#find`, `#create`, `#fork`, `#fork_or_get`, `#ephemeral`
+- `Boxd::Box` with `#exec`, `#exec!`, `#write_file`, `#read_file`, `#suspend`, `#resume`, `#reboot`, `#destroy`, `#refresh!`, `#wait_for`
+- Block-form streaming exec yielding `(stream, line)` tuples
+- Typed errors: `AuthenticationError`, `NotFoundError`, `ExecError`, `TimeoutError`, `QuotaExceededError`, `CLIMissingError`, ...
+- 5 example recipes under `examples/`
+- Live smoke test in `spec/smoke_test.rb`

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 boxd contributors
+
+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,277 @@
+# boxd
+
+**Ruby SDK for [boxd.sh](https://boxd.sh) — fork a running Linux VM in ~160 milliseconds.**
+
+```ruby
+require "boxd"
+
+box = Boxd::Compute.new.boxes.fork("dev-golden", name: "my-fork")
+box.url            # => "https://my-fork.boxd.sh"
+box.exec!(["uptime"])
+box.suspend        # idle is ~free; resume is sub-millisecond
+```
+
+That's the whole pitch. The VM is real Linux on a real KVM hypervisor — sudo, kernel modules, Docker, persistent disk. The fork inherits live memory, open sockets, the running process tree. The URL is HTTPS at boot. Idle is sub-microsecond resume away.
+
+Anything you'd build with a container, a serverless function, a CDE, or a code-interpreter sandbox — try it on a boxd VM and see if you stop reaching for the workaround.
+
+---
+
+## Why this gem exists
+
+Modal, Daytona, E2B, Vercel Sandbox, Cloudflare Sandbox, Fly Sprites — every AI-sandbox platform of 2026 ships a Python or TypeScript SDK and stops there. Ruby is left in the cold.
+
+But the Ruby world hasn't gone anywhere. Rails is still the front door to a generation of startups, Heroku-shaped operators still want a real shell on a real machine, and a whole community of CLI-tool authors lives in `bin/` directories Ruby still owns.
+
+This gem is the boxd primitive in the idiom Ruby developers expect: snake_case, blocks for ephemeral resources, typed exceptions, `frozen_string_literal: true` on every file. Pair it with `ruby-openai`, `anthropic`, `langchain-ruby`, or whatever else you already trust — and you have a working agent loop in twenty lines.
+
+---
+
+## Install
+
+```bash
+gem install boxd
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "boxd"
+```
+
+You'll need the `boxd` CLI on `$PATH` (this gem wraps it in v0 — see [Status](#status)):
+
+```bash
+curl -fsSL https://boxd.sh/install.sh | sh
+boxd login
+```
+
+That's the whole setup. The gem reads your CLI credentials automatically; no API keys to wrangle unless you want to pin one explicitly (`Boxd::Compute.new(api_key: "bxd_…")`).
+
+<a id="boxd-dev"></a>
+
+## boxd-dev — a one-liner dev box for any GitHub or GitLab repo
+
+Installing the gem also drops a `boxd-dev` binary on your `$PATH`. Give it a GitHub repo and you're in a tmux session with the repo cloned, deps installed, and Claude one keystroke away:
+
+```bash
+boxd-dev chad/phoenix                            # `owner/repo` shorthand → GitHub
+boxd-dev https://github.com/chad/phoenix.git     # any HTTPS clone URL
+boxd-dev git@github.com:chad/phoenix.git         # SSH-style remotes
+boxd-dev https://gitlab.com/group/proj           # other forges work too
+boxd-dev                                         # no arg → connects to your default dev VM
+```
+
+What it actually does, end to end:
+
+1. Confirms the repo exists (via `gh repo view` for GitHub).
+2. Forks your golden VM into a per-repo box (`dev-<repo>`), in ~160 ms — or resumes the existing one if you've used it before.
+3. Ensures a persistent tmux session named `dev` is running.
+4. If the repo isn't cloned yet, kicks off `/usr/local/bin/dev-bootstrap` inside that tmux session — clones the repo and runs the project's setup script (or falls back to ecosystem defaults: `npm install`, `cargo fetch`, `mix deps.get`, `bundle install`, `uv sync`, etc.).
+5. SSHes you straight into the tmux session so you see the bootstrap happen live, then land at a shell in the repo directory.
+
+Subsequent runs against the same repo skip steps 1–4 and just attach. Suspended VMs cost ~$0 and resume in sub-millisecond; you can keep one per project indefinitely.
+
+Want it as `boxd dev <repo>` instead of `boxd-dev`? When boxd's CLI grows git/`gh`-style plugin autoload (it doesn't today), no code change here — same binary becomes the subcommand.
+
+---
+
+## A 15-minute tutorial, in five steps
+
+The [`examples/`](examples) directory is the tutorial. Each file is a self-contained, runnable Ruby program that introduces one more capability. Read them in order and you've seen the whole surface.
+
+### Lesson 1 — Run untrusted code in a disposable VM
+
+→ [`examples/01_run_untrusted_llm_code.rb`](examples/01_run_untrusted_llm_code.rb)
+
+The classic "code interpreter" pattern. An LLM hands you a Ruby snippet. You don't trust it. So you fork a fresh box, write the file, run it with a timeout, and throw the VM away. The whole pattern is one block:
+
+```ruby
+result = compute.boxes.ephemeral(fork: "dev-golden") do |box|
+  box.write_file("/tmp/snippet.rb", llm_generated_code)
+  box.exec(["ruby", "/tmp/snippet.rb"], timeout: 10)
+end
+```
+
+`ephemeral` destroys the box at end of block — even if the code raises, even if you `Ctrl-C` out. The agent's malicious `rm -rf /` happens to a VM that's about to disappear anyway.
+
+### Lesson 2 — Fork an agent mid-thought
+
+→ [`examples/02_fork_during_thinking.rb`](examples/02_fork_during_thinking.rb)
+
+Your agent is mid-run inside a box. It's holding state in memory — a parsed AST, a populated cache, a half-completed compile. You want to branch its execution and try two different next steps without losing the warm state.
+
+```ruby
+parent  = compute.boxes.fork("dev-golden", name: "parent")
+parent.exec!(["bash", "-lc", "warm-up-stuff-here"])
+
+branch_a = compute.boxes.fork(parent.name, name: "branch-a")
+branch_b = compute.boxes.fork(parent.name, name: "branch-b")
+# Both children inherit the parent's filesystem, memory, and open sockets.
+```
+
+This is the primitive nothing else ships. Vercel and Cloudflare snapshot the filesystem; Modal restores from a deploy-time image. **boxd forks the running process tree.**
+
+### Lesson 3 — Race three agents at the same prompt
+
+→ [`examples/03_parallel_agent_bake_off.rb`](examples/03_parallel_agent_bake_off.rb)
+
+Three agent personalities — architect, designer, hacker — each get their own VM, the same prompt, and a different system message. They build in parallel. You collect the URLs and pick the winner.
+
+```ruby
+%w[architect designer hacker].map do |voice|
+  Thread.new do
+    box = compute.boxes.fork("dev-golden", name: "bake-#{voice}")
+    box.write_file("/tmp/prompt.txt", system_prompt_for(voice) + user_task)
+    box.exec(["bash", "-lc", 'claude -p "$(cat /tmp/prompt.txt)" --dangerously-skip-permissions'])
+    puts "  #{voice} → #{box.url}"
+  end
+end.each(&:join)
+```
+
+Every VM ships Claude Code pre-authenticated to your account, so there's no API key wrangling. Three boxes, three live URLs, three running apps to compare side by side.
+
+### Lesson 4 — Replace your CI runner with a forked golden
+
+→ [`examples/04_ephemeral_ci_runner.rb`](examples/04_ephemeral_ci_runner.rb)
+
+Your CI job needs Docker-in-Docker, sudo, and a warm Cargo cache. GitHub Actions runners are slow and don't trust you with that. Fork a golden that's already loaded with your toolchain instead:
+
+```ruby
+compute.boxes.ephemeral(fork: "ci-golden", name: "ci-#{sha}") do |box|
+  box.exec!(["bash", "-lc", "git checkout #{sha} && ./script/test"]) do |stream, line|
+    print "[#{stream}] #{line}"
+  end
+end
+```
+
+The fork inherits the warm cache. The job runs in ~the time it takes to actually compile. Box auto-suspends when idle. You pay for the CPU you actually used.
+
+### Lesson 5 — A multi-tenant code interpreter
+
+→ [`examples/05_multi_tenant_code_interpreter.rb`](examples/05_multi_tenant_code_interpreter.rb)
+
+You ship a Jupyter-style product where every customer session is its own isolated VM. You want cold-start in under a second, state that persists across sessions, and zero-ish cost between them. With `fork_or_get` plus auto-suspend, the whole pool fits in a class:
+
+```ruby
+def session_for(customer_id)
+  box = compute.boxes.fork_or_get("interpreter-golden",
+                                  name: "ipy-#{customer_id}",
+                                  auto_suspend_timeout: 60)
+  box.resume if box.suspended?
+  box
+end
+```
+
+First call forks the golden in ~160ms. Subsequent calls find the existing VM and resume it in sub-ms. Sixty seconds of network idle and it auto-suspends — disk persists, billing stops.
+
+---
+
+## API reference
+
+### `Boxd::Compute`
+
+```ruby
+compute = Boxd::Compute.new(api_key: "...", environment: "production")
+compute.boxes        # → BoxService
+compute.whoami       # → { user:, keys: [...] }
+```
+
+Process-wide config (Rails-friendly):
+
+```ruby
+Boxd.configure do |c|
+  c.api_key     = ENV["BOXD_API_KEY"]
+  c.environment = "production"   # or "staging"
+end
+```
+
+### `Boxd::BoxService` — `compute.boxes`
+
+| Method | Description |
+|---|---|
+| `#list` | Every box on the account |
+| `#get(name)` | Fetch by name; raises `NotFoundError` |
+| `#find(name)` | Fetch by name; returns `nil` if missing |
+| `#create(name:, auto_suspend_timeout:, restart:)` | New empty VM |
+| `#fork(source, name:, auto_suspend_timeout:)` | Fork an existing VM with full live state |
+| `#fork_or_get(source, name:, **opts)` | Idempotent fork — returns existing box by name, or forks |
+| `#ephemeral(fork: \| create:, name:, **opts) { \|box\| ... }` | Block-scoped VM; destroyed on exit |
+
+### `Boxd::Box`
+
+| Method | Description |
+|---|---|
+| `#exec(cmd, env:, tty:, timeout:, raise_on_error:) { \|stream, line\| ... }` | Run a command; streams via block |
+| `#exec!(cmd, **opts)` | Same; returns stdout `String`, raises on non-zero |
+| `#write_file(path, content_or_io)` | Upload a file (string or anything `#read`-able) |
+| `#read_file(remote, local=nil)` | Download a file; returns local path |
+| `#suspend` / `#pause` | Pause the VM (sub-ms resume) |
+| `#resume` | Wake from suspend |
+| `#reboot` | Cold reboot |
+| `#destroy` | Permanent — disk goes away |
+| `#refresh!` | Refetch status from the API |
+| `#wait_for(status, timeout:)` | Block until status matches |
+| `#url` / `#name` / `#vm_id` / `#status` / `#image` | Cached attrs |
+| `#running?` / `#suspended?` | Status helpers |
+
+### Exceptions
+
+```
+Boxd::Error
+├── Boxd::AuthenticationError    # bad token / not logged in
+├── Boxd::NotFoundError          # VM doesn't exist
+├── Boxd::InvalidArgumentError   # bad request to the API
+├── Boxd::QuotaExceededError     # account limit hit
+├── Boxd::TimeoutError           # exec or operation exceeded its budget
+├── Boxd::ConnectionError        # network/transport issue
+├── Boxd::InternalError          # CLI returned non-JSON / unexpected output
+├── Boxd::CLIMissingError        # `boxd` not on $PATH
+└── Boxd::ExecError              # exec exited non-zero (carries :exit_code, :stdout, :stderr)
+```
+
+---
+
+## Recipes summary
+
+| File | What you learn |
+|---|---|
+| [01_run_untrusted_llm_code.rb](examples/01_run_untrusted_llm_code.rb) | `ephemeral`, `write_file`, `exec` with timeout — the code-interpreter pattern |
+| [02_fork_during_thinking.rb](examples/02_fork_during_thinking.rb) | Forking a *running* VM; preserving live state across branches |
+| [03_parallel_agent_bake_off.rb](examples/03_parallel_agent_bake_off.rb) | Parallel forks; pre-auth'd Claude Code; comparing strategies |
+| [04_ephemeral_ci_runner.rb](examples/04_ephemeral_ci_runner.rb) | Streaming exec; warm-cache forking; replacing your CI runner |
+| [05_multi_tenant_code_interpreter.rb](examples/05_multi_tenant_code_interpreter.rb) | `fork_or_get`; long-lived per-customer VMs; auto-suspend economics |
+
+---
+
+## Status
+
+**v0 (this release)** — wraps the [`boxd` CLI](https://docs.boxd.sh/cli). Works today; production-acceptable for back-end and DevOps use cases where shelling is fine. The public Ruby API is stable across the v1 transition.
+
+**v1 (planned)** — native gRPC client via the `grpc` gem and the `boxd.api.v1` proto. Same public surface; faster, no CLI dependency, first-class streaming.
+
+If you're reaching for something the CLI doesn't expose yet (templates, disks, networks, domains, token management), let us know what you need — open an issue and we'll lift it into the gem.
+
+---
+
+## Contributing
+
+The codebase is small (~500 lines) and meant to stay that way. PRs welcome — especially for:
+
+- Recipes showing real-world patterns
+- Coverage of additional CLI surfaces
+- A native gRPC backend for v1
+
+Run the smoke test against your own boxd account:
+
+```bash
+export BOXD_API_KEY=...
+export BOXD_GOLDEN=dev-golden   # or any box you have
+ruby -Ilib spec/smoke_test.rb
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/bin/boxd-dev

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "boxd"
+require "boxd/dev_command"
+
+Boxd::DevCommand.new(ARGV).run

data/boxd.gemspec

@@ -0,0 +1,47 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "boxd/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "boxd"
+  spec.version       = Boxd::VERSION
+  spec.authors       = ["boxd contributors"]
+  spec.email         = ["hello@boxd.sh"]
+
+  spec.summary       = "Ruby SDK for boxd.sh — forkable KVM microVMs"
+  spec.description   = <<~DESC
+    Idiomatic Ruby client for boxd.sh. Fork a running VM with full state in
+    ~160ms, suspend and resume in sub-ms, run anything inside it, get an
+    HTTPS URL at name.boxd.sh.
+
+    v0 wraps the `boxd` CLI; v1 will speak gRPC natively. The public API
+    is stable across that change.
+  DESC
+  spec.homepage      = "https://boxd.sh"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata = {
+    "homepage_uri"      => "https://boxd.sh",
+    "documentation_uri" => "https://docs.boxd.sh",
+    "source_code_uri"   => "https://github.com/boxd-sh/boxd-ruby",
+    "bug_tracker_uri"   => "https://github.com/boxd-sh/boxd-ruby/issues",
+    "changelog_uri"     => "https://github.com/boxd-sh/boxd-ruby/blob/main/CHANGELOG.md",
+  }
+
+  spec.files = Dir[
+    "lib/**/*.rb",
+    "bin/boxd-dev",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "boxd.gemspec",
+  ]
+  spec.bindir       = "bin"
+  spec.executables  = ["boxd-dev"]
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rake", "~> 13.0"
+end

data/lib/boxd/box.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module Boxd
+  # A Box is the handle to a single VM. Instances are returned from
+  # Compute#boxes operations; you don't construct them directly.
+  class Box
+    attr_reader :name, :vm_id, :url, :status, :image
+
+    def initialize(attrs, backend:)
+      @backend = backend
+      refresh_from(attrs)
+    end
+
+    # Fetch the latest state from the API and update this Box in place.
+    def refresh!
+      refresh_from(@backend.call_json("info", @name))
+      self
+    end
+
+    # Convenience: hash representation of the current cached state.
+    def to_h
+      {
+        name: @name,
+        vm_id: @vm_id,
+        url: @url,
+        status: @status,
+        image: @image,
+      }
+    end
+
+    def running?
+      status == "running"
+    end
+
+    def suspended?
+      %w[hibernated standby paused].include?(status)
+    end
+
+    # Run a command inside the VM.
+    #
+    #   box.exec(["ls", "-la"])                            # sync, blocking
+    #   box.exec(["sleep", "3"], timeout: 1)               # raises TimeoutError
+    #   box.exec(["bash", "-lc", "for i in 1 2 3; ...]) do |stream, chunk|
+    #     # stream is :stdout or :stderr
+    #   end
+    #
+    # Returns Hash {stdout:, stderr:, exit_code:}. Raises ExecError if
+    # `raise_on_error: true` and exit_code != 0.
+    def exec(cmd, env: nil, tty: false, timeout: nil, raise_on_error: false, &block)
+      result =
+        if timeout
+          run_with_timeout(timeout) { @backend.exec_stream(@name, cmd, env: env, tty: tty, &block) }
+        else
+          @backend.exec_stream(@name, cmd, env: env, tty: tty, &block)
+        end
+
+      if raise_on_error && result[:exit_code] != 0
+        raise ExecError.new(
+          "exec exited #{result[:exit_code]}: #{result[:stderr].strip.lines.last}",
+          **result,
+        )
+      end
+      result
+    end
+
+    # Run a command and return stdout as a String, raising on any non-zero
+    # exit. Convenience for one-liners.
+    def exec!(cmd, **opts)
+      r = exec(cmd, **opts, raise_on_error: true)
+      r[:stdout]
+    end
+
+    # Write content to a path inside the VM.
+    #
+    #   box.write_file("/tmp/hello.txt", "hello world")
+    #   box.write_file("/etc/conf",      File.read("./conf"))
+    #   box.write_file("/tmp/blob",      io_object)         # responds to :read
+    def write_file(path, content)
+      data =
+        if content.respond_to?(:read)
+          content.read
+        else
+          content.to_s
+        end
+
+      Tempfile.create(["boxd-write", File.extname(path)]) do |tmp|
+        tmp.binmode
+        tmp.write(data)
+        tmp.flush
+        @backend.call_raw("cp", tmp.path, "#{@name}:#{path}")
+      end
+      path
+    end
+
+    # Copy a file FROM the VM to the local filesystem. Returns the local path.
+    def read_file(remote_path, local_path = nil)
+      local_path ||= Tempfile.new(File.basename(remote_path)).path
+      @backend.call_raw("cp", "#{@name}:#{remote_path}", local_path)
+      local_path
+    end
+
+    def suspend
+      @backend.call_raw("pause", @name)
+      refresh!
+    end
+    alias pause suspend
+
+    def resume
+      @backend.call_raw("resume", @name)
+      refresh!
+    end
+
+    def reboot
+      @backend.call_raw("reboot", @name)
+      refresh!
+    end
+
+    def destroy
+      @backend.call_raw("destroy", @name, "--confirm")
+      @status = "destroyed"
+      self
+    end
+
+    # Wait until status matches `target` (String or Array). Polls `info`.
+    # Returns self on match; raises TimeoutError after `timeout` seconds.
+    def wait_for(target, timeout: 60, interval: 1)
+      targets = Array(target).map(&:to_s)
+      deadline = Time.now + timeout
+      until targets.include?(refresh!.status)
+        raise TimeoutError, "wait_for(#{targets.inspect}) timed out after #{timeout}s; status=#{status}" \
+          if Time.now >= deadline
+        sleep interval
+      end
+      self
+    end
+
+    def inspect
+      "#<Boxd::Box name=#{@name.inspect} status=#{@status.inspect} url=#{@url.inspect}>"
+    end
+
+    private
+
+    def refresh_from(attrs)
+      attrs ||= {}
+      @name   = attrs[:name]   || @name
+      @vm_id  = attrs[:vm_id]  || @vm_id
+      @status = attrs[:status] || @status
+      @image  = attrs[:image]  || @image
+      raw_url = attrs[:url]    || @url
+      @url    = raw_url && (raw_url.start_with?("http") ? raw_url : "https://#{raw_url}")
+    end
+
+    def run_with_timeout(seconds)
+      result = nil
+      thread = Thread.new { result = yield }
+      unless thread.join(seconds)
+        thread.kill
+        raise TimeoutError, "operation exceeded #{seconds}s"
+      end
+      result
+    end
+  end
+end

data/lib/boxd/box_service.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Boxd
+  # Collection accessor for boxes. Exposed as `compute.boxes`.
+  class BoxService
+    def initialize(backend)
+      @backend = backend
+    end
+
+    # List all boxes on the account.
+    def list
+      Array(@backend.call_json("list")).map { |attrs| Box.new(attrs, backend: @backend) }
+    end
+
+    # Get a single box by name. Raises NotFoundError if missing.
+    def get(name)
+      Box.new(@backend.call_json("info", name), backend: @backend)
+    end
+
+    # Like #get, but returns nil if the box doesn't exist.
+    def find(name)
+      get(name)
+    rescue NotFoundError
+      nil
+    end
+
+    # Create a fresh box.
+    #
+    #   compute.boxes.create(name: "my-box", auto_suspend_timeout: 0)
+    def create(name: nil, auto_suspend_timeout: nil, restart: nil)
+      args = ["new"]
+      args.push("--name", name) if name
+      args.push("--auto-suspend-timeout", auto_suspend_timeout.to_s) if auto_suspend_timeout
+      args.push("--restart", restart.to_s) if restart
+      Box.new(@backend.call_json(*args), backend: @backend)
+    end
+
+    # Fork an existing box. `source` is the source box's name or ID.
+    #
+    #   compute.boxes.fork("dev-golden", name: "preview-pr-42")
+    def fork(source, name: nil, auto_suspend_timeout: nil)
+      args = ["fork", source.to_s]
+      args.push("--name", name) if name
+      args.push("--auto-suspend-timeout", auto_suspend_timeout.to_s) if auto_suspend_timeout
+      Box.new(@backend.call_json(*args), backend: @backend)
+    end
+
+    # Fork-or-get: if `name` already exists, return that box; otherwise fork
+    # from `source`. Handy for idempotent provisioning.
+    def fork_or_get(source, name:, **opts)
+      existing = find(name)
+      return existing if existing
+
+      fork(source, name: name, **opts)
+    end
+
+    # Ephemeral: fork a source box, yield it, and destroy when the block
+    # exits (even on exception). Use for one-shot agent tasks where the
+    # fork should disappear afterwards.
+    #
+    #   compute.boxes.ephemeral(fork: "dev-golden") do |box|
+    #     box.exec!(["bash", "-lc", "cargo test"])
+    #   end
+    def ephemeral(fork: nil, create: nil, name: nil, **opts)
+      box =
+        if fork
+          self.fork(fork, name: name, **opts)
+        else
+          create(name: name, **(create || {}), **opts)
+        end
+      yield box
+    ensure
+      box&.destroy if box && box.status != "destroyed"
+    end
+  end
+end

data/lib/boxd/cli_backend.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "shellwords"
+require "tempfile"
+
+module Boxd
+  # CLIBackend shells out to the `boxd` CLI for every operation. v0 of this
+  # gem is built on this; v1 will speak gRPC directly. The public API does
+  # not change between the two — only this file does.
+  class CLIBackend
+    DEFAULT_BIN = "boxd"
+
+    attr_reader :bin, :env
+
+    def initialize(api_key: nil, bin: nil, environment: nil)
+      @bin = bin || ENV["BOXD_BIN"] || DEFAULT_BIN
+      @env = {}
+      @env["BOXD_TOKEN"]       = api_key     if api_key
+      @env["BOXD_ENVIRONMENT"] = environment if environment
+
+      assert_cli_present!
+    end
+
+    # Run `boxd <args>` and parse `--json` output. Raises on non-zero exit
+    # with a typed Boxd::Error subclass when we recognise the failure.
+    def call_json(*args)
+      out, err, status = Open3.capture3(env, bin, "--json", *args.map(&:to_s))
+      unless status.success?
+        raise classify_error(err.empty? ? out : err, args)
+      end
+
+      return nil if out.strip.empty?
+
+      JSON.parse(out, symbolize_names: true)
+    rescue JSON::ParserError => e
+      raise InternalError, "boxd CLI returned non-JSON output for `#{args.join(' ')}`: #{e.message}\n#{out}"
+    end
+
+    # Run `boxd <args>` and return [stdout, stderr] as strings. Used for
+    # commands without --json support.
+    def call_raw(*args)
+      out, err, status = Open3.capture3(env, bin, *args.map(&:to_s))
+      raise classify_error(err.empty? ? out : err, args) unless status.success?
+
+      [out, err]
+    end
+
+    # Stream `boxd exec` for a single command, yielding chunks. Returns
+    # the exit code captured from CLI exit status.
+    #
+    # The CLI does not stream stdout/stderr separately by default; we
+    # capture both via pipes and yield each line as it arrives, tagging
+    # the stream.
+    def exec_stream(vm, cmd, env: nil, tty: false, &block)
+      cli_args = ["exec"]
+      cli_args << "--tty" if tty
+      Array(env).each do |k, v|
+        cli_args.push("-e", "#{k}=#{v}")
+      end
+      cli_args << vm.to_s
+      cli_args << "--"
+      cli_args.concat(Array(cmd).map(&:to_s))
+
+      stdout_buf = +""
+      stderr_buf = +""
+      exit_code  = nil
+
+      Open3.popen3(self.env, bin, *cli_args) do |_stdin, stdout, stderr, wait_thr|
+        threads = []
+        threads << Thread.new do
+          stdout.each_line do |line|
+            stdout_buf << line
+            block&.call(:stdout, line)
+          end
+        end
+        threads << Thread.new do
+          stderr.each_line do |line|
+            stderr_buf << line
+            block&.call(:stderr, line)
+          end
+        end
+        threads.each(&:join)
+        exit_code = wait_thr.value.exitstatus
+      end
+
+      { stdout: stdout_buf, stderr: stderr_buf, exit_code: exit_code }
+    end
+
+    private
+
+    def assert_cli_present!
+      return if system("which #{Shellwords.escape(@bin)} > /dev/null 2>&1")
+
+      raise CLIMissingError, <<~MSG
+        boxd CLI not found on PATH (looked for `#{@bin}`).
+        Install it: curl -fsSL https://boxd.sh/install.sh | sh
+      MSG
+    end
+
+    def classify_error(message, args)
+      msg = message.to_s
+      case msg
+      when /InvalidToken|unauthenticated/i
+        AuthenticationError.new("boxd auth failed: #{msg}")
+      when /not found/i
+        NotFoundError.new("boxd #{args.first}: #{msg}")
+      when /quota|limit/i
+        QuotaExceededError.new(msg)
+      when /timeout/i
+        TimeoutError.new(msg)
+      when /connection|network/i
+        ConnectionError.new(msg)
+      else
+        Error.new("boxd #{args.join(' ')}: #{msg.strip}")
+      end
+    end
+  end
+end

data/lib/boxd/compute.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Boxd
+  # Compute is the entry point. It holds the credentials + CLI backend
+  # and exposes service accessors (currently just #boxes).
+  #
+  #   compute = Boxd::Compute.new(api_key: ENV["BOXD_API_KEY"])
+  #   compute.boxes.list
+  #   compute.whoami
+  #
+  # If api_key: is omitted, the boxd CLI's stored login credentials are
+  # used (i.e. whatever `boxd login` set up locally).
+  class Compute
+    attr_reader :backend
+
+    def initialize(api_key: nil, bin: nil, environment: nil)
+      api_key   ||= Boxd.config.api_key
+      environment ||= Boxd.config.environment
+      @backend = CLIBackend.new(api_key: api_key, bin: bin, environment: environment)
+    end
+
+    def boxes
+      @boxes ||= BoxService.new(@backend)
+    end
+
+    def whoami
+      @backend.call_json("whoami")
+    end
+  end
+
+  # Process-wide defaults. Useful for Rails initializers and scripts.
+  #
+  #   Boxd.configure do |c|
+  #     c.api_key     = ENV["BOXD_API_KEY"]
+  #     c.environment = "production"   # or "staging"
+  #   end
+  class Configuration
+    attr_accessor :api_key, :environment
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+  end
+end

data/lib/boxd/dev_command.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "uri"
+require "shellwords"
+require "open3"
+require "json"
+
+module Boxd
+  # Implements the `boxd-dev` command. Given a repo reference, ensures a
+  # dev VM exists for it (forked from a golden), the repo is cloned and
+  # set up, a persistent tmux session is running, then drops you into it
+  # over SSH.
+  #
+  # Repo references accepted:
+  #   chad/phoenix                                  # GitHub (by convention)
+  #   github.com/chad/phoenix
+  #   https://github.com/chad/phoenix(.git)?
+  #   git@github.com:chad/phoenix.git
+  #   https://gitlab.com/group/proj
+  #   <bare VM name>                                # connect to existing
+  class DevCommand
+    GOLDEN_DEFAULT = "dev-golden"
+    BOOTSTRAP_PATH = "/usr/local/bin/dev-bootstrap"
+
+    def initialize(argv)
+      @argv = argv
+    end
+
+    def run
+      arg = @argv.first || ENV["BOXD_DEV_VM"] || "dev-chad"
+
+      repo = parse_repo(arg)
+      vm   = repo ? "dev-#{repo[:slug]}" : arg
+      golden = ENV.fetch("BOXD_GOLDEN", GOLDEN_DEFAULT)
+
+      preflight_repo!(repo) if repo
+
+      compute = Boxd::Compute.new
+      box     = ensure_vm(compute, vm, golden, repo)
+      prep_tmux(box, repo)
+      exec_attach(box)
+    end
+
+    private
+
+    # ---- repo reference parsing ------------------------------------------
+
+    def parse_repo(arg)
+      case arg
+      when %r{\A([\w.-]+)/([\w.-]+)\z}
+        github("github.com", $1, $2)
+      when %r{\Ahttps?://([\w.-]+\.\w+)/([\w.-]+)/([\w.-]+?)(?:\.git)?/?\z}
+        github($1, $2, $3)
+      when %r{\Agit@([\w.-]+):([\w.-]+)/([\w.-]+?)(?:\.git)?\z}
+        github($1, $2, $3)
+      when %r{\A([\w.-]+\.\w+)/([\w.-]+)/([\w.-]+?)(?:\.git)?\z}
+        github($1, $2, $3)
+      end
+    end
+
+    def github(host, owner, repo)
+      slug = repo.downcase.gsub(/[^a-z0-9-]+/, "-").gsub(/-+/, "-").sub(/\A-/, "").sub(/-\z/, "")
+      {
+        host: host,
+        owner: owner,
+        repo: repo,
+        slug: slug,
+        display: "#{owner}/#{repo}",
+        clone_url: "https://#{host}/#{owner}/#{repo}.git",
+      }
+    end
+
+    # ---- preflight: refuse to fork on a bad repo -------------------------
+
+    def preflight_repo!(repo)
+      return unless repo[:host] == "github.com"
+
+      unless system("command -v gh > /dev/null 2>&1")
+        warn "boxd-dev: gh CLI not found; skipping repo existence check"
+        return
+      end
+
+      return if system("gh repo view #{Shellwords.escape(repo[:display])} > /dev/null 2>&1")
+
+      warn "boxd-dev: #{repo[:display]} not found or inaccessible to your gh account"
+      exit 1
+    end
+
+    # ---- VM lifecycle ----------------------------------------------------
+
+    def ensure_vm(compute, vm, golden, repo)
+      existing = compute.boxes.find(vm)
+      if existing
+        existing.resume if existing.suspended?
+        return existing
+      end
+
+      unless repo
+        warn "boxd-dev: no VM named '#{vm}'"
+        exit 1
+      end
+
+      unless compute.boxes.find(golden)
+        warn "boxd-dev: golden VM '#{golden}' is missing (set BOXD_GOLDEN to override)"
+        exit 1
+      end
+
+      warn "boxd-dev: forking #{golden} → #{vm} (#{repo[:display]})..."
+      compute.boxes.fork(golden, name: vm, auto_suspend_timeout: 0)
+    end
+
+    # ---- tmux + bootstrap ------------------------------------------------
+
+    # Ensure the persistent tmux session "dev" exists on the box. If a
+    # repo arg was given and the clone isn't there yet, kick off the
+    # bootstrap script in pane 0 so the attaching shell sees the build live.
+    def prep_tmux(box, repo)
+      script = +<<~SH
+        set -e
+        if ! tmux has-session -t dev 2>/dev/null; then
+          tmux new-session -d -s dev
+      SH
+
+      if repo
+        script << <<~SH
+          if [ ! -d "$HOME/#{repo[:repo]}" ]; then
+            tmux send-keys -t dev "REPO_URL='#{repo[:clone_url]}' REPO_NAME='#{repo[:repo]}' #{BOOTSTRAP_PATH} && cd ~/#{repo[:repo]}" Enter
+          else
+            tmux send-keys -t dev "cd ~/#{repo[:repo]}" Enter
+          fi
+        SH
+      end
+
+      script << "        fi\n"
+
+      box.exec(["bash", "-c", script])
+    end
+
+    # ---- final SSH attach ------------------------------------------------
+
+    def exec_attach(box)
+      ssh_host = URI(box.url).host
+      exec("ssh", "-t", ssh_host, "--", "tmux new-session -A -s dev")
+    end
+  end
+end

data/lib/boxd/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Boxd
+  class Error < StandardError; end
+
+  class AuthenticationError < Error; end
+  class NotFoundError < Error; end
+  class InvalidArgumentError < Error; end
+  class QuotaExceededError < Error; end
+  class TimeoutError < Error; end
+  class ConnectionError < Error; end
+  class InternalError < Error; end
+  class CLIMissingError < Error; end
+
+  class ExecError < Error
+    attr_reader :exit_code, :stdout, :stderr
+
+    def initialize(message, exit_code:, stdout:, stderr:)
+      super(message)
+      @exit_code = exit_code
+      @stdout = stdout
+      @stderr = stderr
+    end
+  end
+end

data/lib/boxd/version.rb

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

data/lib/boxd.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# boxd — Ruby SDK for boxd.sh
+#
+#   require "boxd"
+#
+#   compute = Boxd::Compute.new(api_key: ENV["BOXD_API_KEY"])
+#   box     = compute.boxes.fork("dev-golden", name: "my-fork")
+#   box.exec!(["bash", "-lc", "echo hello from $(hostname)"])
+#   box.suspend
+#
+# See README.md or examples/ for more.
+
+require "boxd/version"
+require "boxd/errors"
+require "boxd/cli_backend"
+require "boxd/box"
+require "boxd/box_service"
+require "boxd/compute"
+
+module Boxd
+end

metadata

@@ -0,0 +1,96 @@
+--- !ruby/object:Gem::Specification
+name: boxd
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- boxd contributors
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-06-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  Idiomatic Ruby client for boxd.sh. Fork a running VM with full state in
+  ~160ms, suspend and resume in sub-ms, run anything inside it, get an
+  HTTPS URL at name.boxd.sh.
+
+  v0 wraps the `boxd` CLI; v1 will speak gRPC natively. The public API
+  is stable across that change.
+email:
+- hello@boxd.sh
+executables:
+- boxd-dev
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/boxd-dev
+- boxd.gemspec
+- lib/boxd.rb
+- lib/boxd/box.rb
+- lib/boxd/box_service.rb
+- lib/boxd/cli_backend.rb
+- lib/boxd/compute.rb
+- lib/boxd/dev_command.rb
+- lib/boxd/errors.rb
+- lib/boxd/version.rb
+homepage: https://boxd.sh
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://boxd.sh
+  documentation_uri: https://docs.boxd.sh
+  source_code_uri: https://github.com/boxd-sh/boxd-ruby
+  bug_tracker_uri: https://github.com/boxd-sh/boxd-ruby/issues
+  changelog_uri: https://github.com/boxd-sh/boxd-ruby/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+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 boxd.sh — forkable KVM microVMs
+test_files: []