Each example in the Nexo repo 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`](https://github.com/maquina-app/nexo/blob/main/examples/artifact_from_template.rb) | Staging input files into a run's sandbox + rendering a named artifact from a trusted ERB template |
| [`approval_workflow.rb`](https://github.com/maquina-app/nexo/blob/main/examples/approval_workflow.rb) | Durable human-in-the-loop: `checkpoint` + `suspend!` + `resume` |

---

## Live — agents

| Example | Shows | Extra requirements |
|---|---|---|
| [`code_reviewer.rb`](https://github.com/maquina-app/nexo/blob/main/examples/code_reviewer.rb) | The minimal agent against a local Ollama model, with a skill and token accounting | Ollama running locally |
| [`chat_session.rb`](https://github.com/maquina-app/nexo/blob/main/examples/chat_session.rb) | A continuing, addressable `Nexo::Session` that remembers prior turns | — |
| [`container_review.rb`](https://github.com/maquina-app/nexo/blob/main/examples/container_review.rb) | Agent tools running inside a locked-down OCI container | `docker` (or Apple `container`) |
| [`news_summary.rb`](https://github.com/maquina-app/nexo/blob/main/examples/news_summary.rb) | Read-only web fetch scoped by `fetch_allow` | — |
| [`news_search.rb`](https://github.com/maquina-app/nexo/blob/main/examples/news_search.rb) | Host-injected `search_backend` + fetch | a search backend you inject |

---

## Live — MCP

| Example | Shows | Extra requirements |
|---|---|---|
| [`mcp_filesystem.rb`](https://github.com/maquina-app/nexo/blob/main/examples/mcp_filesystem.rb) | The MCP seam + permission gate with the official filesystem server — no credentials needed; **start here for MCP** | `npx` |
| [`inbox_digest.rb`](https://github.com/maquina-app/nexo/blob/main/examples/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`](https://github.com/maquina-app/nexo/blob/main/examples/inbox_digest_http.rb) | The same digest over a hosted HTTP MCP server with a host-supplied OAuth bearer token | a hosted Gmail MCP server |
| [`inbox_digest_task.rb`](https://github.com/maquina-app/nexo/blob/main/examples/inbox_digest_task.rb) | The digest as a Workflow **Task**: `agent` macro + `run_agent` + a named artifact | same as `inbox_digest.rb` |

---

## Live — workflows

| Example | Shows | Extra requirements |
|---|---|---|
| [`approval_agent.rb`](https://github.com/maquina-app/nexo/blob/main/examples/approval_agent.rb) | The `:approve` permission mode bridged to a durable suspend/resume | — |

---

## Skills used by the examples

The `skills/` directory holds the `SKILL.md` packages the examples reference — `email_triage`, `news_summary`, and `ruby-code-review`. The examples point `Nexo.config.skills_path` there; in a Rails host the default is `app/skills`.

| Skill | Used by |
|---|---|
| [`email_triage`](https://github.com/maquina-app/nexo/blob/main/examples/skills/email_triage/SKILL.md) | `inbox_digest.rb`, `inbox_digest_http.rb`, `inbox_digest_task.rb` |
| [`news_summary`](https://github.com/maquina-app/nexo/blob/main/examples/skills/news_summary/SKILL.md) | `news_summary.rb`, `news_search.rb` |
| [`ruby-code-review`](https://github.com/maquina-app/nexo/blob/main/examples/skills/ruby-code-review/SKILL.md) | `code_reviewer.rb` |

---

## Rails walkthrough

A host-side Rails walkthrough covers `run_later`, live progress, run helpers, and artifact access:

> [View `examples/rails_usage.md` on GitHub →](https://github.com/maquina-app/nexo/blob/main/examples/rails_usage.md)


---

## Next steps

<div class="not-prose mt-8 grid grid-cols-1 gap-4 sm:grid-cols-2">
  <a href="../getting-started/" class="group relative rounded-2xl border border-zinc-200 p-6 hover:border-[#50B1FD]/50 dark:border-zinc-800 dark:hover:border-[#50B1FD]/50 transition">
    <h3 class="font-sora font-semibold text-zinc-900 dark:text-white group-hover:text-[#50B1FD] transition">
      Getting started
    </h3>
    <p class="mt-2 text-sm text-zinc-600 dark:text-zinc-400">
      Install Nexo and build your first agent in five lines.
    </p>
  </a>

  <a href="https://github.com/maquina-app/nexo" target="_blank" rel="noopener" class="group relative rounded-2xl border border-zinc-200 p-6 hover:border-[#50B1FD]/50 dark:border-zinc-800 dark:hover:border-[#50B1FD]/50 transition">
    <h3 class="font-sora font-semibold text-zinc-900 dark:text-white group-hover:text-[#50B1FD] transition">
      GitHub Repository
    </h3>
    <p class="mt-2 text-sm text-zinc-600 dark:text-zinc-400">
      Source code, issues, and the full guide set in the repo.
    </p>
  </a>
</div>