Guides / Ruby / API reference

Ruby API reference

Everything public in the kosa8 gem, version 0.1.2: every class, method, keyword argument and default, what each returns and what it raises. Signatures are copied from the source in lib/. Keys in returned hashes are the daemon's own JSON names, as strings.

What this is, in plain words

This page is the dictionary. The quickstart and the developer guide show how the pieces fit together; this page lists every piece, with the exact names to type and the exact things you get back. You do not need to read it top to bottom: search it for the method you are calling.

A few words used throughout: the daemon is the kosa8 background service on your machine. The gem sends it requests over a unix socket (a file that acts like a network port, only reachable from your own computer). A keyword argument is a Ruby argument passed by name, as in run(…, timeout: 30). A hash is Ruby's dictionary type; most methods return the daemon's answer as one.

The gem

gem "kosa8", "~> 0.1.2"  # Gemfile (or: gem install kosa8 -v 0.1.2)
require "kosa8"           # loads version, errors, transport, checkpoints, client

Ruby 2.6 or later (required_ruby_version >= 2.6). No dependencies: the gem uses only the standard library (net/http, json, socket, openssl, base64, uri, fileutils, time). MIT licensed.

Kosa8::Client

Kosa8::Client.new(
  socket_path: nil,
  host: nil,
  token: nil,
  insecure: false,
  actor: "tool",
  agent_token: nil,
  headers: {},
  timeout: nil,
  checkpoint_store: nil,
  env: ENV
)

All arguments are keyword arguments. Constructing a client sends nothing: it works out where to connect (and raises Kosa8::Error for a refused address or a bad actor) and sets up the checkpoint store.

Conventions for every method

• approval: Methods that list approval: nil send it, stripped, as the X-Kosa8-Approval header; a blank string sends nothing. Methods without it (health, version, the list_* and sandbox_* readers, get_sandbox, list_checkpoints) send none.
• Errors. Any method that talks to the daemon can raise Kosa8::ConnectionError (daemon unreachable), Kosa8::TimeoutError (a connect or read timeout passed), and the HTTP error class matching the daemon's status. Only the extra errors are listed per method.
• Paths below are shortened: … is /kosa8/v1. Every sandbox, container and snapshot id put into a path is percent-encoded with Kosa8.enc, so c/1 is sent as c%2F1.
• Query flags such as wipe: are sent as ?wipe=1 when true and left out when false or nil.
• Returned hashes are JSON.parse output: string keys, Integer and Float numbers. The list_* methods and sandbox_images / sandbox_containers return [] when the daemon answers with an empty body or null.

Daemon

Sandboxes

create_sandbox keywords

Running code

• args is converted with to_a. There is no shell unless you ask for one: ["sh", "-c", "echo $HOME"].
• env: a hash ({ "A" => "1" }, sent as ["A=1"]) or an array of "K=V" strings.
• Callbacks (on_stdout:, on_stderr:, on_status:) are anything with call, such as a lambda. Each is called with one chunk, a binary String, as it arrives, on the calling thread. on_status gets daemon status lines (such as image pulling) that are not part of stdout or stderr. Frames with a stream other than stderr or status count as stdout.
• timeout: seconds for this call, overriding the client's. It bounds the wait for each read from the daemon, not the whole run: a command that keeps printing can run longer. With no timeout anywhere, these calls wait as long as the command runs (since 0.1.1). A timeout stops the client waiting; it does not stop the command, which keeps running in the sandbox.
• Exit codes. A non-zero exit is a result, not an exception: exit_code holds it. If the final frame carries no integer exit, exit_code is 0.
• Extra errors for run, exec and attach: Kosa8::StreamError when the stream ends with an error frame (image not in the sandbox, no such container, executable not found) or with no final frame. Its stdout/stderr hold the output so far. A line that is not valid NDJSON raises Kosa8::ProtocolError (since 0.1.1). An HTTP error before streaming starts raises the typed HTTP error.
• One body is the whole of stdin. The daemon closes the process's stdin when the body of a write_stdin ends. Since 0.1.1 the client remembers each [sandbox, container] it has written to, and a second write_stdin for the same pair raises Kosa8::Error (stdin of container … was already sent and is closed …) instead of the daemon's silent {"ok"=>true} (0.1.0). The pair is marked before the request is sent, so if that first request fails (daemon unreachable, say), the same client will refuse a retry; use a new container. A different Client object does not know about the first write. To stream input, pass one IO or Enumerator.
• Your callbacks' exceptions come out unchanged (since 0.1.1). An exception raised in on_stdout, on_stderr, on_status or an exec_frames block ends the call and is re-raised as the same object; 0.1.0 relabelled an IOError there as ConnectionError.

Snapshots and fork

In our tests, once every copy made by fork had been deleted, its snapshot had gone too (delete_snapshot on it answered NotFoundError).

explore

explore(sandbox, variants, image: "alpine:latest", keep_all: false, keep: nil, timeout: 120,
        prefix: nil, pull: true, approval: nil)  # => Kosa8::ExploreResult

Best-of-N, as kosa8 explore does it. In order:

1. variants.to_a; fewer than two raises Kosa8::Error (give at least two variants; with one there is nothing to compare) before anything is sent.
2. If pull: pull_into_sandbox(sandbox, image).
3. fork(sandbox, variants.length, prefix: …). The default prefix is "#{sandbox}-explore-#{Time.now.to_i % 100_000}". If fewer branches come back than variants, raises Kosa8::Error (forked N branches for M variants; see list_sandboxes for what was created); the branches made are not deleted.
4. One Ruby Thread per branch runs run(branch, image, ["sh", "-c", variant], timeout: timeout). A failure whose message matches Kosa8::TRANSIENT (connection refused, EOF, reset, broken pipe, "no such file or directory", stream ended, unreachable) is retried up to four attempts in all, sleeping 0.5, 1 and 1.5 seconds between them (since 0.1.1 there is no sleep after the last). A TimeoutError is never retried. Branch failures are recorded in the branch's error, not raised.
5. The winner is the successful branch (no error, exit 0) with the smallest duration_ms, or "" if none succeeded. keep: names a branch to keep instead; a name that is not a branch raises Kosa8::Error (keep X is not one of the branches (…); all of them were kept) and nothing is deleted.
6. Unless keep_all, every branch other than the winner is deleted with DELETE …/sandboxes/{branch} (errors ignored, counted in removed). With no winner, that is every branch. The parent sandbox is never touched.

One quirk worth knowing: TRANSIENT also matches "No such file or directory". Because variants run through sh -c, a command missing from the image is an ordinary exit 127 (in our test, "python3 -V" on Alpine came back as exit=127 error=nil, no retry). But in an image with no sh at all, the run fails with … not found in $PATH: No such file or directory, which the code treats as transient and retries four times (read from the code; not reproduced).

Checkpoints

Checkpoints are kept on the client side, over snapshots, in the same file and format the kosa8 CLI uses (~/.kosa8/checkpoints.json), so kosa8 checkpoint ls and kosa8 rewind see what the gem did and the other way round.

• to: a checkpoint id or label. Labels match case-insensitively and the newest match wins. Without it, the latest checkpoint.
• Extra errors: Kosa8::CheckpointError for no checkpoints (no checkpoints for "x" — take one with checkpoint or `kosa8 checkpoint x`), a to: that matches nothing (no checkpoint "nope" for sandbox "x"), or, in checkpoint, an invalid sandbox name (empty, starting with a dot, containing / or \).
• A failed restore. The sandbox is deleted first, because the restored machine takes its name. A refusal of that delete is raised as is and changes nothing. If the restore then fails, rewind raises Kosa8::CheckpointError with the message restore failed and NAME no longer exists (it was deleted to free its name for the restore): … — the checkpoint is intact; recover with restore_snapshot("ID", name: "NAME") (0.1.0 said "is now stopped", which was wrong), and e.cause is the daemon's error. At that point the sandbox is gone and the checkpoint's snapshot is intact; run the call the message names.
• Concurrent checkpoints. The next id is read from the store before the snapshot is taken and written after, so two checkpoint calls on the same sandbox at the same moment (two threads, or the gem and the CLI) can pick the same id. Since 0.1.2, when the snapshot is refused with a ConflictError whose message contains "already exists", the call steps to the next number (ckpt-n+1) and tries again, up to 10 attempts in all; a 409 for any other reason, or the tenth refusal, is raised. The eviction list is the one computed before the first attempt. 0.1.0 raised on the first collision; 0.1.1 retried only when list_snapshots already showed the other snapshot, which often it did not.

Helpers

Kosa8::Sandbox

Kosa8::Sandbox.new(client, id)   # usually: client.sandbox("name")
sb.id        # => "doc-rb-demo"
sb.client    # => the Kosa8::Client
sb.inspect   # => "#<Kosa8::Sandbox doc-rb-demo>"

Each method calls the client method with the sandbox id filled in and passes the remaining keyword arguments through, so the keywords, results and errors are the client's.

Not on the handle: restore_snapshot, delete_snapshot, list_snapshots (they are about snapshots, not this sandbox). Call them on sb.client.

Structs

All three are Structs built with keyword_init: true, so they have readers and writers for each member, to_h, and value equality.

Kosa8::ExecResult

ExecResult = Struct.new(:exit_code, :stdout, :stderr, keyword_init: true)
r.exit_code  # Integer
r.stdout     # String, UTF-8, invalid bytes replaced
r.stderr     # String, the same
r.ok?        # exit_code.zero?

Kosa8::ExploreBranch

ExploreBranch = Struct.new(:name, :variant, :exit, :output, :error, :duration_ms, keyword_init: true)
b.name         # the branch sandbox's id, such as "doc-rb-g2-e2"
b.variant      # the shell command it ran
b.exit         # Integer; -1 if it never ran
b.output       # stdout + stderr, trailing newline removed (chomp)
b.error        # the last error message, or nil
b.duration_ms  # Integer, including retries

Kosa8::ExploreResult

ExploreResult = Struct.new(:parent, :branches, :winner, :removed, keyword_init: true)
x.parent     # the sandbox explored
x.branches   # Array of ExploreBranch, in variant order
x.winner     # the kept branch's name, or "" when none succeeded
x.removed    # Integer: branches deleted

A real one, from three variants ("sleep 2; echo slow", "echo fast", "echo broken; exit 1"):

"doc-rb-g2-e2"
2
#<struct Kosa8::ExploreBranch name="doc-rb-g2-e1", variant="sleep 2; echo slow", exit=0, output="slow", error=nil, duration_ms=2508>
#<struct Kosa8::ExploreBranch name="doc-rb-g2-e2", variant="echo fast", exit=0, output="fast", error=nil, duration_ms=506>
#<struct Kosa8::ExploreBranch name="doc-rb-g2-e3", variant="echo broken; exit 1", exit=1, output="broken", error=nil, duration_ms=484>

Result shapes

Other methods return the daemon's JSON as plain hashes and arrays. The keys you will meet most, as kosa8 0.9.36 sent them in our tests:

A real sandbox record, from create_sandbox(name: "doc-rb-guide", cpus: 2, mem_mb: 1024, egress_allow: ["example.com"], labels: { "team" => "docs" }):

{"id"=>"doc-rb-guide", "name"=>"doc-rb-guide", "created"=>"2026-11-03T01:39:22.091122-05:00", "state"=>"running", "cpus"=>2, "mem_mb"=>1024, "disk_gb"=>32, "egress"=>"allow:example.com", "ip"=>"192.168.127.2", "labels"=>{"team"=>"docs"}}

Transport and endpoints

Kosa8::Transport

Kosa8::Transport.new(socket_path: nil, host: nil, token: nil, insecure: false, actor: "tool",
                     agent_token: nil, headers: {}, timeout: nil, env: ENV)

The same connection keywords as Client.new, without checkpoint_store:. It opens a new connection for every request (no keep-alive), so one transport can be used from several threads at once.

An exception raised by the block given to frames (and so by your callbacks) passes through raw's network rescue unchanged: a Kosa8::Error is re-raised as is, and any other StandardError is carried past the rescue inside the internal Kosa8::CallbackFailure (an Exception subclass) and re-raised as the original object. You never see CallbackFailure yourself. In 0.1.0 such an IOError became a ConnectionError, and a malformed line raised JSON::ParserError.

Kosa8.resolve_endpoint

Kosa8.resolve_endpoint(host: nil, socket_path: nil, token: nil, insecure: false, env: ENV)  # => Kosa8::Endpoint

Where to connect, by the kosa8 CLI's rules:

1. The address is host if it is non-empty, else env["KOSA8_HOST"], stripped of spaces and trailing slashes. Empty: the unix socket at socket_path or Kosa8.default_socket_path.
2. The scheme is lower-cased. unix:///path is a socket (and wins over socket_path). tcp:// is read as http://. No scheme (host:port) is read as http://. Any other scheme raises Kosa8::Error (KOSA8_HOST scheme "ftp" is not supported; use http://, https://, tcp:// or unix://). An address with no host name raises Kosa8::Error (KOSA8_HOST "…" names no host).
3. Plain http to a host other than localhost, ::1 or 127.* raises Kosa8::Error (refusing to talk to 10.0.0.5:7440 over plain http: …) unless insecure or KOSA8_INSECURE=1.
4. The token is token if non-empty; otherwise env["KOSA8_TOKEN"], but only when the address came from KOSA8_HOST, never with an explicit host:. A path in the URL is kept as a prefix for every request. https uses Net::HTTP's default certificate verification.

Kosa8::Endpoint is a Struct (keyword_init) with kind (:unix or :tcp), socket_path, scheme, host, port, base_path, token, and target: "unix:///path" or "scheme://host:port" (the port always shown, as in https://w.example.com:443).

Other module functions and classes

Checkpoint stores

A store holds { "sandbox-name" => [checkpoint record, …] }. It needs two methods: load (returns the data) and update { |data| … } (runs the block on the data, saves what it leaves, and returns the block's value).

Errors

StandardError
└─ Kosa8::Error
   ├─ Kosa8::ConnectionError
   ├─ Kosa8::TimeoutError
   ├─ Kosa8::StreamError              #stdout, #stderr
   ├─ Kosa8::CheckpointError
   ├─ Kosa8::ProtocolError            a frame that is not NDJSON (since 0.1.1)
   └─ Kosa8::ApiError                 any HTTP error status without a closer class (500, 503, …)
      ├─ Kosa8::BadRequestError       400
      ├─ Kosa8::AuthError             401
      ├─ Kosa8::PolicyError           403
      │  └─ Kosa8::ApprovalRequiredError   403 with an approval refusal; #approval
      ├─ Kosa8::NotFoundError         404
      ├─ Kosa8::ConflictError         409
      └─ Kosa8::UnsupportedError      501

Kosa8::Error.new(message = nil, status: nil, daemon_message: nil, remediation: nil, method: nil, path: nil, body: nil)
Kosa8::ApprovalRequiredError.new(message = nil, approval: {}, **kw)
Kosa8::StreamError.new(message = nil, stdout: "", stderr: "", **kw)

Kosa8.error_from_response(status, body, method:, path:)  # => the typed error (not raised)

error_from_response builds the error the client raises for an HTTP status of 400 or more. daemon_message is the body's error if it is a non-empty String, else its message; for a text body, the stripped text. remediation is the body's non-empty remediation. The message is "<daemon_message> (<remediation>)", the daemon message alone, or "request failed with HTTP <status>". A 403 whose body has an approval hash with a String why becomes ApprovalRequiredError; other statuses use Kosa8::BY_STATUS, falling back to ApiError.

Kosa8::TimeoutError is the gem's own class, not Ruby's Timeout::Error, and does not inherit from it. Real messages and how to handle each class: Ruby errors and troubleshooting.