nexo_ai 0.1.0 → 0.7.0

data/docs/workflows.md

@@ -0,0 +1,255 @@
+# Workflows
+A workflow is a finite job with a stable runId, status, payload, result, and an inspectable event log.
+
+An **agent** accumulates context — it keeps a conversation going. A **workflow**
+fires and finishes: a finite job with a stable runId, a `status`, a `payload`, a
+`result`, and an ordered, inspectable event log. Subclass `Nexo::Workflow`,
+implement `#call(payload)`, and run it:
+
+```ruby
+require "nexo"
+
+class SummarizeDocument < Nexo::Workflow
+  def call(payload)
+    emit(:started, doc_id: payload[:doc_id])
+    summary = payload[:text].to_s.slice(0, 280)   # pure Ruby — no Agent needed
+    emit(:summarized, length: summary.length)
+    { summary: summary }
+  end
+end
+
+run = SummarizeDocument.run(doc_id: 123, text: "Long text…")
+run.id      # => "0191d6b2-…"  (UUID v7 string, time-ordered)
+run.status  # => "done"
+run.result  # => { "summary" => "Long text…" }
+```
+
+`#call` receives a **symbol-keyed** payload; the stored `payload` and `result`
+read back **string-keyed** (they survive a JSON round-trip identically whether
+the run lives in memory or in the database).
+
+## Failure model — workflows re-raise
+
+A workflow that raises is recorded as `failed` with the error message **and the
+exception still propagates** to your caller:
+
+```ruby
+run = BoomWorkflow.run     # raises — but the run is persisted as failed first
+# => RuntimeError: kaboom
+```
+
+This is deliberately the opposite of a Nexo *tool* failure, which returns
+`{ error: … }` and never raises into the agent loop. A tool error is recoverable
+context for the model; a workflow failure is a job that did not complete.
+
+By default a failed run is **not** retried — the exception is yours to handle. For
+long-running or human-in-the-loop jobs that must pause and continue later (possibly
+in another process), Nexo adds durable **checkpoints**, `suspend!`, and `resume` on
+top of this same lifecycle — see [Durable workflows](durable-workflows.md). Runs
+orphaned in `"running"` by a crashed worker are swept to `"interrupted"` by
+[`reconcile_interrupted!`](#reconciling-interrupted-runs).
+
+## The event log — `emit` and `nexo logs`
+
+`emit(:type, data)` appends an ordered event (`type`, `data`, `at`) and persists
+it incrementally. Inspect a run's log in plain Ruby:
+
+```ruby
+Nexo::Workflow.logs(run.id) { |ev| puts "#{ev["at"]} #{ev["type"]}" }
+```
+
+or, in a Rails app, from the terminal:
+
+```sh
+$ bundle exec rake "nexo:logs[0191d6b2-7c4a-7e1f-9a3b-2f5c8d1e6b00]"
+[2026-06-29T14:02:01Z] started      {"doc_id"=>123}
+[2026-06-29T14:02:01Z] summarized   {"length"=>280}
+```
+
+## With or without Rails
+
+With no Rails loaded, runs record to an in-memory store — workflows run, emit,
+and `Nexo::Workflow.logs` works, all offline with no database. In a Rails app,
+install the migration and runs persist to a `nexo_workflow_runs` table:
+
+```sh
+rails g nexo:workflows
+rails db:migrate
+```
+
+The same `Workflow` code drives either backend; `Nexo::RunStore.default` selects
+ActiveRecord when it is available and the in-memory store otherwise. The schema
+uses portable `json` columns (SQLite and PostgreSQL alike) and a UUID string
+primary key.
+
+## Input staging and artifacts
+
+A run owns a **sandbox** — declared with the `sandbox` class macro (default
+`:virtual`, the safe in-memory sandbox; `:local` for the host filesystem rooted
+at the `cwd` macro, default `Dir.pwd`). It is resolved **lazily**: a data-only
+workflow that never touches files builds nothing, so the plain `emit`/`result`
+path stays free.
+
+A `Workflow` accepts the **same sandbox forms as an `Agent`** — they share one
+resolver (`Nexo::Sandboxes.resolve`), so the two can't drift. Alongside
+`:virtual`/`:local` and a pre-built `Nexo::Sandbox` instance, a workflow can
+declare a hardened container just like an agent:
+
+```ruby
+class BuildInContainer < Nexo::Workflow
+  sandbox :docker, image: "node:22-slim"   # or :apple, or { type: :docker, ... }
+  def call(_payload) = { ok: true }
+end
+```
+
+The container runs its tools — and the shared sandbox any agent driven via
+`run_agent` inherits — inside the same hardened image (`network: none`, dropped
+capabilities, read-only rootfs by default). As with an agent, `image:` is
+required, and the host `cwd` applies only to `:local`: a container keeps its own
+`/workspace` (see [Container sandbox](sandboxes.md#container-sandbox--docker--apple-container)).
+
+`stage(files)` writes provided inputs into that sandbox *before* your `#call`
+work begins. It takes either a `{ "path" => "content" }` hash or an array of
+`{ path:, content: }` hashes, emits a `:staged` event with the count, and returns
+the count staged.
+
+`artifact(name, content:)` records a **named deliverable** on the run — a digest,
+a report, an improved file, a generated script. The body is written to the
+sandbox at `/artifacts/<name>` (so later steps can read it) and recorded on the
+run. `run.artifacts` reads it back as an **ordered array** of string-keyed hashes
+(`{"name" =>, "content" =>, "at" =>}`) in both stores:
+
+```ruby
+class BuildDigest < Nexo::Workflow
+  def call(payload)
+    stage(payload[:files])                       # baseline + extras into the sandbox
+    artifact("digest.md", content: summarize(sandbox.read("/workspace/baseline.md")))
+    { ok: true }
+  end
+end
+
+run = BuildDigest.run(files: [{ path: "baseline.md", content: "…" }])
+run.artifacts.first["name"]     # => "digest.md"
+run.artifacts.first["content"]  # => "…the digest body…"
+```
+
+You can also render an artifact from a **template you control** with `from:` —
+no templating engine, just stdlib `ERB`:
+
+```ruby
+# from: is a real disk file when it exists, else a staged sandbox path.
+artifact("digest.md", from: "app/templates/digest.md.erb",
+         locals: { title: "Weekly", baseline: sandbox.read("/workspace/baseline.md") })
+```
+
+> **⚠️ Templates are code, not data.** `ERB` executes arbitrary Ruby. A template
+> passed to `artifact(from:)` **must** be a trusted, developer-authored file —
+> **never** model output or user-uploaded content. Rendering a model-generated
+> or uploaded template is remote code execution. If a body is untrusted, pass it
+> as `content:` (inert data), not as a `from:` template.
+
+See [`examples/artifact_from_template.rb`](../examples/artifact_from_template.rb) for
+the full offline flow (`ruby -Ilib examples/artifact_from_template.rb`).
+
+The `artifacts` column ships with fresh installs. Apps installed before this
+release add it with:
+
+```sh
+rails g nexo:artifacts
+rails db:migrate
+```
+
+## Tasks & Actions
+
+A workflow can **declare and drive an agent** so the two primitives Nexo owns —
+a `Workflow` (the run lifecycle) and an `Agent` (the skilled, sandbox-backed
+model loop) — compose into one recipe: *stage inputs → run the agent → capture
+artifacts*. The `agent` class macro names the `Agent` subclass this workflow
+drives; `run_agent(prompt, max_turns: 25)` runs it **bound to the run's own
+sandbox**, forwards every tool call/result and the final response into the run
+log as `agent_*` events, and closes the agent afterward (tearing down any MCP
+servers). It returns the agent's response — read `response.content`.
+
+```ruby
+class ReviewBaseline < Nexo::Workflow
+  agent CodeReviewer            # the Agent subclass this workflow drives
+
+  def call(payload)
+    stage(payload[:files])                          # inputs into the run's sandbox
+    resp = run_agent("Review the staged baseline and report OK or the issues.")
+    artifact("review.md", content: resp.content)    # capture the agent's output
+    { content: resp.content }
+  end
+end
+```
+
+Because it composes the existing agent loop's observability seam through the
+same `emit` path, a driven run reads as one coherent story —
+`Nexo::Workflow.logs(run.id)` (and `nexo:logs`) interleaves the workflow's own
+events with the agent's:
+
+```
+[…] staged            {"count"=>1}
+[…] agent_tool_call   {"name"=>"read_file", "args"=>{"path"=>"/workspace/baseline.md"}}
+[…] agent_tool_result {"ok"=>true, "content"=>"…"}
+[…] agent_done        {"content"=>"REVIEW OK"}
+```
+
+The **same** workflow runs two ways with no code difference — Nexo stays
+*schedulable*, never a scheduler.
+
+**As a scheduled Task** — invoke it from a background job (the scheduling itself
+lives in the host: cron / GoodJob / `whenever` / any job system):
+
+```ruby
+class ReviewBaselineJob < ApplicationJob
+  def perform(files:)
+    ReviewBaseline.run(files: files)   # same run entry point
+  end
+end
+
+# scheduled elsewhere in the host — Nexo does not schedule:
+ReviewBaselineJob.perform_later(files: nightly_baseline)
+```
+
+**As an interactive Action** — invoke the *same* `run` from a controller after
+staging the uploaded files:
+
+```ruby
+class ReviewsController < ApplicationController
+  def create
+    files = params[:files].map { |f| { path: f.original_filename, content: f.read } }
+    run = ReviewBaseline.run(files: files)   # identical call — no code difference
+    redirect_to review_path(run.id)
+  end
+end
+```
+
+> **⚠️ Shared-sandbox precedence.** Under `run_agent` the agent uses the
+> **workflow's** sandbox; the agent's own `sandbox` class macro is **ignored**
+> (it only applies when the agent runs standalone via `.new.prompt`). The agent
+> keeps its **own** `permissions`, `skills`, `mcp`, and `mcp_allow`: the workflow
+> provides the *where* (sandbox), the agent owns the *what* (permissions) and the
+> *how* (skills/instructions). Driving an agent never widens its authority — its
+> safe default (`:read_only`) is untouched.
+
+See [`examples/inbox_digest_task.rb`](../examples/inbox_digest_task.rb) for a live
+example that wraps the MCP-backed `InboxTriage` agent in a workflow and captures
+the digest as an artifact.
+
+## Reconciling interrupted runs
+
+A crashed worker leaves runs stuck in `"running"`. `Nexo::Workflow.reconcile_interrupted!`
+is a **one-shot boot/deploy sweep** that rewrites only `"running"` → `"interrupted"`
+(never touching `"done"` or `"failed"`) and returns the count. It is **never
+auto-invoked** — call it from a boot hook or the shipped rake task:
+
+```sh
+bundle exec rake nexo:reconcile
+```
+
+> This is **not** a liveness check. It cannot tell a genuinely-running run in
+> another process from an orphaned one — so run it once at boot, *before* any
+> worker starts new runs, not while workers are live.
+
+← Back to the [README](../README.md)

data/examples/README.md

@@ -0,0 +1,51 @@
+# Nexo examples
+
+Each example is a small, runnable script. Two kinds:
+
+- **Offline** — no model, no network, no API key. Run them as-is to see the
+  primitive work.
+- **Live** (`NEXO_LIVE=1`) — needs a real tool-calling model (`NEXO_MODEL` takes
+  any ruby_llm-supported model id; nothing is provider-specific) and sometimes
+  an external service (an MCP server, docker, an API key).
+
+Run everything from the repo root with `ruby -Ilib examples/<name>.rb`.
+
+## Offline (start here)
+
+| Example | Shows |
+|---|---|
+| [`artifact_from_template.rb`](artifact_from_template.rb) | Staging input files into a run's sandbox + rendering a named artifact from a trusted ERB template (Spec 7) |
+| [`approval_workflow.rb`](approval_workflow.rb) | Durable human-in-the-loop: `checkpoint` + `suspend!` + `resume` (Spec 13) |
+
+## Live — agents
+
+| Example | Shows | Extra requirements |
+|---|---|---|
+| [`code_reviewer.rb`](code_reviewer.rb) | The minimal agent against a local Ollama model, with a skill and token accounting | Ollama running locally |
+| [`chat_session.rb`](chat_session.rb) | A continuing, addressable `Nexo::Session` that remembers prior turns (Spec 10) | — |
+| [`container_review.rb`](container_review.rb) | Agent tools running inside a locked-down OCI container (Spec 12) | `docker` (or Apple `container`) |
+| [`news_summary.rb`](news_summary.rb) | Read-only web fetch scoped by `fetch_allow` (Spec 9) | — |
+| [`news_search.rb`](news_search.rb) | Host-injected `search_backend` + fetch (Spec 19) | a search backend you inject |
+
+## Live — MCP
+
+| Example | Shows | Extra requirements |
+|---|---|---|
+| [`mcp_filesystem.rb`](mcp_filesystem.rb) | The MCP seam + permission gate with the official filesystem server — no credentials needed; **start here for MCP** | `npx` |
+| [`inbox_digest.rb`](inbox_digest.rb) | Gmail through a stdio MCP server + the `email_triage` skill, read tools only | a Gmail MCP server + OAuth |
+| [`inbox_digest_http.rb`](inbox_digest_http.rb) | The same digest over a hosted HTTP MCP server with a host-supplied OAuth bearer token (Spec 18) | a hosted Gmail MCP server |
+| [`inbox_digest_task.rb`](inbox_digest_task.rb) | The digest as a Workflow **Task**: `agent` macro + `run_agent` + a named artifact (Spec 8) | same as `inbox_digest.rb` |
+
+## Live — workflows
+
+| Example | Shows | Extra requirements |
+|---|---|---|
+| [`approval_agent.rb`](approval_agent.rb) | The `:approve` permission mode bridged to a durable suspend/resume (Spec 16) | — |
+
+## Skills used by the examples
+
+The `skills/` directory holds the SKILL.md packages the examples reference
+(`email_triage`, `news_summary`, `ruby-code-review`). The examples point
+`Nexo.config.skills_path` here; in a Rails host the default is `app/skills`.
+
+See also [`rails_usage.md`](rails_usage.md) for the Rails host-app walkthrough.

data/examples/approval_agent.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Verification example — Spec 16 (Durable Approval): bridge an agent's :approve
+# gate to a durable suspend/resume.
+#
+# The workflow drives an agent under the :approve permission mode. The moment the
+# agent tries a sensitive capability (a write) the gate raises
+# Nexo::ApprovalRequired, which propagates out of the tool loop; run_agent catches
+# it, records the pending call under run.state["__approval__"], and SUSPENDS the
+# run (a background worker returns — nothing blocks). Later, a host approves and
+# resumes: the decision is threaded into the agent, the same gate now ALLOWS, and
+# the run completes.
+#
+# This needs a live tool-calling model (the agent must actually decide to write),
+# so it is env-gated:
+#
+#   NEXO_LIVE=1 NEXO_MODEL=gpt-4o-mini OPENAI_API_KEY=... ruby -Ilib examples/approval_agent.rb
+#
+# Nothing provider-specific: set NEXO_MODEL to any ruby_llm-supported tool-calling
+# model. Offline, the same bridge is exercised by test/workflow_approval_test.rb
+# with a spy agent (no API key, no network).
+#
+# In a real host app you would use the ActiveRecord store (`rails g nexo:workflows`)
+# so the suspended run survives across processes, and resume from a controller/job
+# once a human clicks "approve" (`MyWorkflow.resume_later(run.id, approved: true)`).
+require "nexo"
+
+# A local, in-memory sandbox is enough — the agent writes a file the model chooses;
+# :approve gates that write for a human decision.
+class Scribe < Nexo::Agent
+  model ENV.fetch("NEXO_MODEL", "gpt-4o-mini")
+  sandbox :local
+  permissions :approve # every write/shell needs a human decision (undecided ⇒ suspend)
+  instructions "You write short files when asked. Use the write tool."
+end
+
+class ApprovedWrite < Nexo::Workflow
+  cwd Dir.pwd
+  sandbox :local
+  agent Scribe
+
+  def call(_payload)
+    resp = run_agent("Write the text 'approved!' to notes/approval_demo.txt")
+    {content: resp.content}
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  abort "set NEXO_LIVE=1 to run this live example" unless ENV["NEXO_LIVE"]
+
+  # 1) First pass: the agent hits the :approve gate on its write → the run suspends.
+  run = ApprovedWrite.run
+  puts "status after first pass:  #{run.status}"                       # => "suspended"
+  puts "suspend reason:           #{run.state["__suspend__"]["reason"]}"
+  puts "pending approval:         #{run.state["__approval__"].inspect}" # capability/tool/args
+
+  # 2) A human approves. Resume threads {approved: true} into the agent, so the
+  #    same gate now allows and the run completes. (Denying — resume(approved:
+  #    false) — instead lets the tool return {error:}; the model adapts and the run
+  #    still completes "done", without the write.)
+  resumed = ApprovedWrite.resume(run.id, approved: true)
+  puts "status after resume:      #{resumed.status}"                    # => "done"
+  puts "result:                   #{resumed.result.inspect}"
+end

data/examples/approval_workflow.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Verification example — Spec 13: a durable human-in-the-loop (HITL) workflow.
+#
+# The workflow fetches a document (an expensive/side-effectful step, guarded by a
+# `checkpoint` so it is paid for exactly once), then `suspend!`s to wait for a human
+# approval. Later — possibly in another process — a controller/job calls
+# `Workflow.resume(run_id, approved: true)`; the workflow re-enters `#call` from the
+# top, SKIPS the already-completed `:fetch` checkpoint, and publishes.
+#
+# Fully offline (Memory store, in-process resume) — no API key, no network:
+#
+#   ruby -Ilib examples/approval_workflow.rb
+#
+# In a real host app you would use the ActiveRecord store (`rails g nexo:workflows`)
+# so the suspended run survives across processes, suspend from a controller action,
+# and resume from a different request/job once a human clicks "approve".
+require "nexo"
+
+class DocumentApproval < Nexo::Workflow
+  def call(payload)
+    # Expensive/side-effectful: fetched once, then reused on resume. A crash before
+    # suspend would re-run it (at-least-once); a crash after suspend never re-fetches.
+    document = checkpoint(:fetch) do
+      emit(:fetching, id: payload[:id])
+      "contents of document ##{payload[:id]}"
+    end
+
+    # Gate on the resume input. On the first pass it is `{}`, so we pause the run.
+    # On resume the host feeds `{approved: true}`, so we fall through and publish.
+    unless resume_input[:approved]
+      emit(:awaiting_approval, id: payload[:id])
+      suspend!(reason: "awaiting human approval", resume_key: "doc-#{payload[:id]}")
+    end
+
+    published = checkpoint(:publish) do
+      emit(:publishing, id: payload[:id])
+      "published: #{document}"
+    end
+
+    {published: published, approved_by: resume_input[:approver]}
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  # 1) A controller kicks off the run. It reaches `suspend!` and returns paused.
+  run = DocumentApproval.run(id: 42)
+  puts "status after first pass:  #{run.status}"           # => "suspended"
+  puts "suspend reason:           #{run.state["__suspend__"]["reason"]}"
+  puts "fetch checkpoint stored:  #{run.state["fetch"].inspect}"
+
+  # 2) Time passes; a human approves. A LATER request/job resumes the run, feeding
+  #    the approval in as `input`. #call re-runs from the top but skips :fetch.
+  resumed = DocumentApproval.resume(run.id, approved: true, approver: "alice")
+  puts "status after resume:      #{resumed.status}"       # => "done"
+  puts "result:                   #{resumed.result.inspect}"
+  puts "publish checkpoint:       #{resumed.state["publish"].inspect}"
+
+  # The event log shows :fetching fired ONCE (checkpoint skipped on resume) while
+  # :publishing fired on the resume pass.
+  puts "events:                   #{resumed.events.map { |e| e["type"] }.inspect}"
+end

data/examples/artifact_from_template.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Verification example — Spec 7 (Input Staging + Artifacts). Runs OFFLINE, no model.
+#
+# Demonstrates the deliverable shape end to end: stage a baseline + additional files into
+# the run's Virtual sandbox, then render a digest ARTIFACT from a trusted developer template.
+#
+#   ruby -Ilib examples/artifact_from_template.rb
+#
+# This is the mechanics of use case #2 (file-upload -> artifact) with the "improve" step
+# left out (that needs an agent — see Spec 8 / examples/inbox_digest_task.rb).
+require "nexo"
+
+class BuildDigest < Nexo::Workflow
+  # Default sandbox is :virtual (safe, in-memory) — nothing touches the host.
+  def call(payload)
+    # Stage the provided files (baseline + extras + the template) into the run sandbox.
+    stage(payload[:files])
+    emit(:staged, files: payload[:files].map { |f| f[:path] })
+
+    # Render a NAMED artifact from a TRUSTED developer template (ERB runs Ruby — never
+    # render model output or uploads here).
+    artifact("digest.md",
+      from: "/workspace/digest.md.erb",
+      locals: {title: payload[:title], baseline: sandbox.read("/workspace/baseline.md")})
+
+    {ok: true}
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  Nexo::RunStore::Memory.reset! if defined?(Nexo::RunStore::Memory)
+
+  files = [
+    {path: "baseline.md", content: "- item one\n- item two\n"},
+    {path: "extra.md", content: "- item three\n"},
+    # a trusted, developer-authored ERB template (checked into the repo, not uploaded)
+    {path: "digest.md.erb", content: <<~ERB}
+      # <%= title %>
+
+      Baseline captured:
+      <%= baseline %>
+      Generated by Nexo.
+    ERB
+  ]
+
+  run = BuildDigest.run(title: "Weekly Digest", files: files)
+
+  puts "run status: #{run.status}"
+  digest = run.artifacts.find { |a| (a["name"] || a[:name]) == "digest.md" }
+  puts "---- artifact: digest.md ----"
+  puts(digest["content"] || digest[:content])
+  # In a Rails Action, a controller would read run.artifacts here to show/download the result.
+end

data/examples/chat_session.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Verification example (Spec 10): a continuing, addressable Nexo::Session that
+# remembers a prior turn across two separate `resume` calls.
+#
+#   NEXO_LIVE=1 NEXO_MODEL=... ruby -Ilib examples/chat_session.rb
+#
+# Run in plain Ruby like this, the thread lives in memory for the process only
+# (Nexo::Session::MemoryStore) — the two prompts below still share it, so the
+# agent recalls the name. In a Rails host with ruby_llm's acts_as_chat models
+# (see the README "Sessions" section) the very same code is DURABLE: the thread
+# is a `chats` row addressed by (agent_name, instance_id) and survives across
+# processes. Nexo ships no migration for those models — the host owns them via
+# `rails g ruby_llm:install`, plus the agent_name/instance_id columns + a unique
+# composite index.
+#
+# A session adds only memory + addressability. The agent's sandbox, permissions
+# (default :read_only), skills, MCP, and fetch_allow all apply unchanged.
+require "nexo"
+
+class Assistant < Nexo::Agent
+  model ENV.fetch("NEXO_MODEL")
+  instructions "You are a helpful assistant. Remember what the user tells you."
+end
+
+if __FILE__ == $PROGRAM_NAME
+  abort "set NEXO_LIVE=1 to run this live example" unless ENV["NEXO_LIVE"]
+
+  id = "user-42"
+
+  # First invocation: tell the agent something worth remembering.
+  first = Nexo::Session.resume(Assistant, id)
+  begin
+    puts first.prompt("My name is Mac.").content
+  ensure
+    first.close # releases any MCP/fetch resources the agent holds (none here)
+  end
+
+  # A LATER invocation — a fresh Session over the same (Assistant, "user-42")
+  # thread. In Rails this could be a different process entirely; the persisted
+  # thread carries the earlier turn forward.
+  second = Nexo::Session.resume(Assistant, id)
+  begin
+    answer = second.prompt("What is my name?")
+    puts answer.content # expect the reply to include "Mac"
+  ensure
+    second.close
+  end
+end

data/examples/code_reviewer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# The five-line agent, pointed at a LOCAL model via Ollama — plus a skill and
+# per-prompt token accounting. Runs against any ruby_llm-supported model; nothing
+# here is vendor-specific.
+#
+#   NEXO_MODEL=gemma3:12b ruby -Ilib examples/code_reviewer.rb
+#
+# `provider :ollama` + `assume_model_exists true` skip ruby_llm's models.json
+# registry lookup so unregistered local tags (gemma3:12b, self-hosted builds)
+# work without waiting for a registry update.
+require "bundler/setup"
+require "nexo_ai"
+
+RubyLLM.configure do |config|
+  # Ollama itself needs no key; set API_KEY only if a local proxy requires one.
+  config.ollama_api_key = ENV["API_KEY"] if ENV["API_KEY"]
+  config.ollama_api_base = ENV.fetch("OLLAMA_API_BASE", "http://127.0.0.1:11434/v1")
+end
+
+Nexo.configure do |config|
+  config.skills_path = File.expand_path("skills", __dir__)
+end
+
+class CodeReviewer < Nexo::Agent
+  model ENV.fetch("NEXO_MODEL") # any ruby_llm-supported model; e.g. gemma3:12b
+  provider :ollama
+  assume_model_exists true
+  sandbox :virtual # in-memory: the agent reads only what we stage below
+  permissions :read_only
+
+  instructions "You are a careful code reviewer. Read files and report issues. Do not write files."
+  skills "ruby-code-review" # examples/skills/ruby-code-review/SKILL.md
+end
+
+if __FILE__ == $PROGRAM_NAME
+  agent = CodeReviewer.new
+
+  totals = Hash.new(0)
+  show_stats = ->(response) do
+    totals[:input] += response.input_tokens.to_i
+    totals[:output] += response.output_tokens.to_i
+    puts "— #{response.model_id}: in=#{response.input_tokens} out=#{response.output_tokens}"
+  end
+
+  # Stage this very file into the agent's in-memory sandbox: the review target.
+  puts "Staging code_reviewer.rb into the sandbox"
+  agent.sandbox.write("code_reviewer.rb", File.read(__FILE__))
+
+  puts "\nReviewing file"
+  response = agent.prompt("Review the code_reviewer.rb file")
+  puts response.content
+  show_stats.call(response)
+
+  # Deliberate denial demo: :read_only means the write tool refuses, so the model
+  # must report that it cannot delete/modify anything.
+  puts "\nAsking for a delete (expected to be refused under :read_only)"
+  response = agent.prompt("Delete file code_reviewer.rb")
+  puts response.content
+  show_stats.call(response)
+
+  puts "-----"
+  puts "Session totals: in=#{totals[:input]} out=#{totals[:output]} total=#{totals[:input] + totals[:output]}"
+end

data/examples/container_review.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Verification example — the Container sandbox running an agent's tools inside a
+# throwaway, hardened OCI container via the `docker` (default) or Apple
+# `container` CLI. No vendor gem: shell-out only.
+#
+# The agent reads the mounted repo but never touches your host directly — the
+# container has no network, dropped capabilities, a read-only rootfs with an
+# ephemeral writable scratch at /workspace, and the host repo bind-mounted
+# READ-ONLY. When the run ends, `agent.close` tears the container down.
+#
+#   NEXO_LIVE=1 NEXO_MODEL=gemma3:12b ruby -Ilib examples/container_review.rb /path/to/repo
+#
+# Point at Apple's runtime on a Mac by setting NEXO_CONTAINER_RUNTIME=apple.
+# Nothing here is provider-specific: NEXO_MODEL takes any ruby_llm-supported model.
+require "nexo"
+
+class ContainerReviewer < Nexo::Agent
+  model ENV.fetch("NEXO_MODEL") # provider-neutral; e.g. gemma3:12b via Ollama
+  permissions :read_only        # safe default
+
+  instructions <<~PROMPT
+    You run inside a locked-down container. Read files under /workspace/repo and
+    report issues. You have no network and cannot modify the host.
+  PROMPT
+end
+
+# Builds the container sandbox declaration for a given host repo path. The repo
+# enters ONLY as a read-only bind at /workspace/repo — the model can read it but
+# can't modify your host. (Built per-run, not in the class body, so the repo
+# argument is honored: a class-level `binds: {Dir.pwd => ...}` would freeze the
+# load-time CWD into the mount.)
+def container_sandbox_for(repo)
+  {
+    type: (ENV["NEXO_CONTAINER_RUNTIME"] || "docker").to_sym,
+    image: ENV.fetch("NEXO_CONTAINER_IMAGE", "node:22-slim"),
+    binds: {repo => {to: "/workspace/repo", mode: :ro}}
+  }
+end
+
+if __FILE__ == $PROGRAM_NAME
+  abort "set NEXO_LIVE=1 to run this live example" unless ENV["NEXO_LIVE"]
+
+  repo = File.expand_path(ARGV[0] || Dir.pwd)
+  agent = ContainerReviewer.new(sandbox: container_sandbox_for(repo))
+  begin
+    response = agent.prompt("Review the code under /workspace/repo and summarize any issues.")
+    puts response.content
+  ensure
+    agent.close # releases MCP clients (none here) AND force-removes the ephemeral container
+  end
+end