@blockrun/mcp 0.22.2 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/mcp",
-  "version": "0.22.2",
+  "version": "0.23.0",
   "mcpName": "io.github.BlockRunAI/blockrun-mcp",
   "description": "BlockRun MCP Server - Give your AI agent web search, deep research, prediction markets, crypto data, X/Twitter intelligence. Paid via x402 micropayments.",
   "type": "module",
@@ -11,6 +11,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "scripts": {
@@ -53,10 +54,12 @@
     "open": "^11.0.0",
     "qrcode": "^1.5.4",
     "rpc-websockets": "9.3.0",
-    "sharp": "^0.34.5",
     "viem": "^2.21.0",
     "zod": "^4.3.5"
   },
+  "optionalDependencies": {
+    "sharp": "^0.34.5"
+  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@types/qrcode": "^1.5.6",
@@ -65,6 +68,6 @@
     "typescript": "^5.0.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20.19"
   }
 }

package/skills/exa-research/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: exa-research
+description: Use when researching products, finding academic papers, discovering competitors, reading webpage content, or getting cited answers grounded in real web sources. Use over generic search when semantic relevance matters.
+triggers:
+  - "research"
+  - "web research"
+  - "find papers"
+  - "academic papers"
+  - "competitor discovery"
+  - "find similar sites"
+  - "exa search"
+  - "cited answer"
+  - "scrape webpage"
+  - "neural search"
+  - "semantic search"
+  - "look up sources"
+---
+
+# Exa Research
+
+Neural web search via BlockRun. Understands meaning, not keywords. Four distinct actions for different research modes.
+
+## How to Call from MCP
+
+As of v0.14.1 the `blockrun_exa` tool is path-based. Pass the endpoint name as `path` and the request as `body`:
+
+```ts
+blockrun_exa({ path: "search",       body: { query: "AI agent frameworks 2026", numResults: 10 } })
+blockrun_exa({ path: "answer",       body: { query: "What is speculative decoding?" } })
+blockrun_exa({ path: "contents",     body: { urls: ["https://example.com/a", "https://example.com/b"] } })
+blockrun_exa({ path: "find-similar", body: { url: "https://arxiv.org/abs/2401.12345", numResults: 5 } })
+```
+
+## Quick Decision Table
+
+| User wants... | Path | Body | Cost |
+|--------------|------|------|------|
+| Relevant URLs on a topic | `search` | `{ query, numResults?, category? }` | $0.01/call |
+| Cited answer to a question | `answer` | `{ query }` | $0.01/call |
+| Full text of URLs | `contents` | `{ urls: [...] }` | $0.002/URL |
+| Pages like a given URL | `find-similar` | `{ url, numResults? }` | $0.01/call |
+| Recent news | `search` + `category: "news"` | – | $0.01/call |
+| Academic papers | `search` + `category: "research paper"` | – | $0.01/call |
+| Company info | `search` + `category: "company"` | – | $0.01/call |
+
+Valid `category` values for `search`: `"news"`, `"research paper"`, `"company"`, `"tweet"`, `"github"`, `"pdf"`.
+
+## Python SDK Instructions
+
+### 1. Initialize (Python SDK)
+
+```python
+from blockrun_llm import setup_agent_wallet
+
+chain = open(os.path.expanduser("~/.blockrun/.chain")).read().strip() if os.path.exists(os.path.expanduser("~/.blockrun/.chain")) else "base"
+if chain == "solana":
+    from blockrun_llm import setup_agent_solana_wallet
+    client = setup_agent_solana_wallet()
+else:
+    from blockrun_llm import setup_agent_wallet
+    client = setup_agent_wallet()
+```
+
+### 2. Search — Find Relevant URLs
+
+```python
+# Basic search
+result = client._request_with_payment_raw("/v1/exa/search", {
+    "query": "AI agent frameworks 2025",
+    "numResults": 10,
+})
+for r in result.get("results", []):
+    print(f"{r['title']} — {r['url']}")
+
+# Filter by category
+result = client._request_with_payment_raw("/v1/exa/search", {
+    "query": "transformer architecture improvements",
+    "numResults": 10,
+    "category": "research paper",
+})
+
+# Restrict to specific domains
+result = client._request_with_payment_raw("/v1/exa/search", {
+    "query": "prediction market regulation",
+    "numResults": 10,
+    "includeDomains": ["reuters.com", "bloomberg.com", "wsj.com"],
+})
+```
+
+**Categories:** `"news"`, `"research paper"`, `"company"`, `"tweet"`, `"github"`, `"pdf"`
+
+### 3. Answer — Cited, Grounded Response
+
+Use when the user asks a factual question and needs reliable sources (not Claude's training data).
+
+```python
+result = client._request_with_payment_raw("/v1/exa/answer", {
+    "query": "What is the current market cap of Polymarket?",
+})
+print(result.get("answer", ""))
+for c in result.get("citations", []):
+    print(f"  [{c.get('title')}] {c.get('url')}")
+```
+
+### 4. Contents — Fetch URL Text
+
+Use when you have URLs and need their full text for LLM context (scraping without a browser).
+
+```python
+urls = [
+    "https://example.com/article-1",
+    "https://example.com/article-2",
+]
+result = client._request_with_payment_raw("/v1/exa/contents", {
+    "urls": urls,
+})
+for item in result.get("results", []):
+    print(f"=== {item['url']} ===")
+    print(item.get("text", "")[:500])
+```
+
+Up to 100 URLs per call. Returns Markdown-ready text.
+
+### 5. Similar — Find Related Pages
+
+Use to discover competitors, related research, or sites with similar content.
+
+```python
+result = client._request_with_payment_raw("/v1/exa/find-similar", {
+    "url": "https://polymarket.com",
+    "numResults": 10,
+})
+for r in result.get("results", []):
+    print(f"{r['title']} — {r['url']}")
+```
+
+## Common Research Workflows
+
+**Competitor discovery:**
+```python
+# 1. Find similar companies
+similar = client._request_with_payment_raw("/v1/exa/find-similar", {"url": "https://target-company.com", "numResults": 15})
+urls = [r["url"] for r in similar.get("results", [])]
+
+# 2. Fetch their about pages
+contents = client._request_with_payment_raw("/v1/exa/contents", {"urls": urls[:10]})
+```
+
+**Research synthesis:**
+```python
+# 1. Find papers
+papers = client._request_with_payment_raw("/v1/exa/search", {
+    "query": "your topic",
+    "category": "research paper",
+    "numResults": 20,
+})
+
+# 2. Get answer with citations
+answer = client._request_with_payment_raw("/v1/exa/answer", {
+    "query": "What are the key findings on your topic?",
+})
+```
+
+## When to Use Exa vs `client.search()`
+
+| Use `blockrun_exa` / `_request_with_payment_raw` | Use `client.search()` |
+|---------------------------------------------------|----------------------|
+| Finding specific URLs and fetching content | Getting a summarized answer with citations |
+| Semantic similarity search | Web + X/Twitter + news combined |
+| Academic paper discovery | Cheaper per call for simple lookups |
+| Domain-filtered research | Already returns a SearchResult object |
+
+## Requirements
+
+- BlockRun SDK: `pip install blockrun-llm`
+- USDC wallet funded (see `client.get_balance()`)
+- `_request_with_payment_raw` is the Python SDK entry point for Exa (no dedicated method yet)

package/skills/image-prompting/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: image-prompting
+description: Use when generating or editing images via `blockrun_image` — especially with GPT Image 2, Nano Banana, or Grok Imagine for posters, UI mockups, marketing assets, product shots, or anything with on-image text. Turns vague user requests ("make me a cool poster") into structured, text-accurate prompts that actually render what you asked for.
+triggers:
+  - "image prompt"
+  - "make a poster"
+  - "create poster"
+  - "ui mockup"
+  - "marketing asset"
+  - "product shot"
+  - "gpt image 2"
+  - "image with text"
+  - "typography poster"
+  - "social asset"
+  - "generate marketing image"
+  - "ai poster"
+---
+
+# Image Prompting
+
+Most image failures are prompt failures. This skill gives the MCP agent a repeatable structure for turning any user request into a prompt that renders clean typography, preserves layout on edits, and avoids AI slop. Defaults are tuned for **GPT Image 2** (best legible text), with fallbacks for Nano Banana, Grok Imagine, and CogView.
+
+## Quick Decision Table
+
+| User wants... | Model | Mode | Size | Cost |
+|---|---|---|---|---|
+| Poster / typography-heavy asset | `openai/gpt-image-2` | generate | `1536x1024` or `1024x1536` | ~$0.04 |
+| Clean product / UI mockup | `openai/gpt-image-2` | generate | `1024x1024` | ~$0.04 |
+| Photoreal / fashion / editorial | `openai/gpt-image-2` or `google/nano-banana-pro` | generate | `1024x1024`+ | $0.04–0.10 |
+| Artistic / stylized / fast | `google/nano-banana` | generate | `1024x1024` | ~$0.01 |
+| Edit an existing image (localized change) | `openai/gpt-image-2` | edit | match source | ~$0.04 |
+| Composite from multiple refs | `openai/gpt-image-2` | edit (multi-ref) | match target | ~$0.04 |
+
+**Valid GPT Image 2 sizes:** `1024x1024` (square), `1536x1024` (landscape ~3:2), `1024x1536` (portrait ~2:3).
+
+## The 5-Section Prompt Framework
+
+Write prompts as **five short blocks separated by blank lines.** This is the single biggest quality lever.
+
+```
+SCENE: where/when/background/environment, one or two lines.
+
+SUBJECT: the main focus (who/what), described concretely.
+
+DETAILS: materials, texture, lighting, camera angle, composition, mood,
+lens feel, depth of field, surface condition. Stack concrete nouns.
+
+USE CASE: editorial photo / product mockup / poster / UI screen / infographic / concept frame.
+(This single line tells the model what kind of image to produce.)
+
+CONSTRAINTS: what must not drift. "No extra text." "No duplicate elements."
+"Preserve face." "Legible typography." Repeat these on every edit.
+```
+
+> The fifth slot is where most mediocre prompts fail silently. Describe the idea without bounding it and the model gets inventive in directions you will regret.
+
+## Text & Typography Rules (the #1 differentiator for GPT Image 2)
+
+1. **Wrap literal text in quotes or ALL CAPS.** `Headline (EXACT TEXT): "Fresh and clean."`
+2. **Specify** font style, weight, size, color, placement, letter-spacing.
+3. **Treat text as layout, not decoration:** hero vs. sub vs. caption with hierarchy + spacing.
+4. **State:** `No extra words. No duplicate text. No watermarks.`
+5. **Spell difficult words letter-by-letter** if the model keeps breaking them.
+6. **Mark each distinct piece of copy** with its role: `HERO:`, `SUB:`, `BOTTOM-LEFT TAG:`, `TOP BANNER:`.
+
+## Anti-Slop Rules (visual facts > excitement)
+
+| Bad (vague / praise-loaded) | Good (concrete visual fact) |
+|---|---|
+| "stunning, epic, masterpiece" | "overcast daylight, brushed aluminum, 50mm feel" |
+| "minimalist brutalist luxury editorial" | "cream background, heavy black condensed sans-serif, asymmetric type block, one hero object, studio tabletop light" |
+| "it should contain a boarding pass feel" | "a boarding pass lies on the tray, barcode visible, creased corner" |
+| "beautiful lighting" | "incandescent work lamp spilling warm light onto wet concrete" |
+
+**Rules:**
+- **Visual facts over praise.** Replace adjectives like *gorgeous/stunning/incredible* with observable specifics.
+- **Style tags need targets.** Don't just name a style — describe the artifacts that style produces.
+- **Say the real thing.** If the image must contain a boarding pass, say "boarding pass."
+- **Name the lens.** 35mm, 50mm, medium format. Depth of field: shallow vs. deep.
+- **Name the light.** Source + quality + direction + color temperature.
+
+## Instructions
+
+### 1. Initialize
+
+```python
+import os
+from pathlib import Path
+
+chain_file = Path.home() / ".blockrun" / ".chain"
+chain = chain_file.read_text().strip() if chain_file.exists() else "base"
+
+if chain == "solana":
+    from blockrun_llm import setup_agent_solana_wallet, ImageClient
+    setup_agent_solana_wallet()
+else:
+    from blockrun_llm import setup_agent_wallet, ImageClient
+    setup_agent_wallet()
+
+image = ImageClient()
+```
+
+### 2. Generate from Scratch
+
+```python
+prompt = """
+SCENE: A realistic roadside billboard at sunset, empty two-lane highway,
+soft gradient sky from peach to lavender, a few utility poles.
+
+SUBJECT: A product billboard for a bottled water brand. Bottle on the right
+third of the frame, catching warm rim light.
+
+DETAILS: 35mm photo feel, shallow depth of field, matte-painted billboard,
+clean kerning, precise print finish.
+
+USE CASE: Product mockup for a marketing deck, landscape 3:2.
+
+CONSTRAINTS:
+- Headline (EXACT TEXT): "Fresh and clean."
+- Bold sans-serif, high contrast, centered vertically in the left half.
+- No extra words. No duplicate text. No watermark.
+"""
+
+result = image.generate(
+    prompt,
+    model="openai/gpt-image-2",
+    size="1536x1024",
+    n=1,
+)
+print(result.data[0].url)  # URL or data URL
+```
+
+### 3. Edit: Change / Preserve / Constraints
+
+**The golden pattern** for iterative editing — one small change per turn. Repeat the preserve list every turn.
+
+```python
+prompt = """
+CHANGE: Make the light warmer — shift the sunset toward a deeper orange.
+         Remove the extra chair on the left.
+
+PRESERVE: Keep the bottle position, label text, and billboard layout exactly
+          as in the source image. Keep the headline text verbatim.
+
+CONSTRAINTS: No extra text. No duplicate elements. Same aspect ratio.
+"""
+
+# `image` arg accepts a public URL OR a data URL (data:image/png;base64,...)
+result = image.edit(
+    prompt,
+    image="https://example.com/source.png",
+    model="openai/gpt-image-2",
+    size="1536x1024",
+)
+print(result.data[0].url)
+```
+
+**Why this works:** small atomic edits compound reliably. Giant rewrites ("redo this but nicer") drift everything.
+
+### 4. Multi-Reference Composition
+
+Pass multiple reference images (up to ~16) via the `edit` endpoint. Label each reference's role in the prompt so the model knows how to use it.
+
+```python
+prompt = """
+COMPOSITE: Combine the three reference images as follows.
+- REF 1 is the SUBJECT (the wristwatch): preserve exact dial, hands, and crown.
+- REF 2 is the ENVIRONMENT (marble tabletop + window light): use as background.
+- REF 3 is the STYLE REFERENCE: match its color grade and contrast.
+
+USE CASE: E-commerce hero shot, square.
+
+CONSTRAINTS: No extra objects. No text. Preserve watch proportions exactly.
+"""
+
+# SDK: pass primary via `image=`; additional refs via a multipart request
+# (check the MCP's `blockrun_image` tool for the multi-image payload shape)
+```
+
+## Worked Example: "make me a cool poster announcing 100 trillion tokens on blockrun.ai"
+
+This is the real prompt that produced the image below — a vague, one-line user ask turned into a structured prompt that rendered every copy line correctly on the first shot.
+
+![100 Trillion Tokens poster generated with openai/gpt-image-2](./example-100t-poster.jpg)
+
+**User asked for:** *"generate 1 cool poster showing we hit 100 Trillion Token LLM consumption on blockrun.ai"*
+
+**Clarifying questions worth asking before prompting:**
+
+- Audience → *social media flex for X/Twitter*
+- Aesthetic → *retro-futuristic synthwave*
+- Hero text → *"100 TRILLION TOKENS"*
+- Supporting copy → *"The world's largest pay-per-call LLM gateway" · "Served on blockrun.ai" · "Powered by x402 micropayments" · "Now with Seedance + GPT Image 2"*
+- Aspect ratio → *16:9 landscape for X timeline*
+
+**Final prompt passed to `openai/gpt-image-2` at `size="1536x1024"`:**
+
+```
+SCENE: A retro-futuristic synthwave scene, 80s vaporwave aesthetic, cinematic
+16:9 composition. Deep purple-to-magenta sunset sky with a giant glowing
+pink-and-orange setting sun cut by thin horizontal neon lines. Palm tree
+silhouettes on both sides. Faint city skyline in the distance. An infinite
+chrome grid floor vanishing at the horizon with pink and cyan perspective lines.
+
+SUBJECT: A milestone announcement poster with the hero text
+"100 TRILLION TOKENS" dominating the center of the frame.
+
+DETAILS: Hero text in huge glossy chrome letters with a pink-to-cyan gradient
+and neon rim light, bold condensed sans-serif, CRT glow, slight scanline
+texture across the letters. Faint CRT scanlines overlay the entire frame.
+Subtle film grain. Chromatic aberration on edges. High contrast, symmetrical,
+cinematic poster composition.
+
+USE CASE: Social media announcement poster for X/Twitter, 16:9 landscape.
+
+CONSTRAINTS:
+- HERO (EXACT TEXT, centered): "100 TRILLION TOKENS"
+- SUB under the hero (clean neon cyan, wide letter-spacing, EXACT TEXT):
+  "The world's largest pay-per-call LLM gateway"
+- TOP-CENTER BANNER inside a thin neon outline (EXACT TEXT):
+  "NOW WITH SEEDANCE + GPT IMAGE 2"
+- BOTTOM-LEFT TAG (monospace, magenta, EXACT TEXT):
+  "> Served on blockrun.ai"
+- BOTTOM-RIGHT TAG (monospace, magenta, EXACT TEXT):
+  "> Powered by x402 micropayments"
+- Legible crisp typography. No extra words. No duplicate text. No watermark.
+```
+
+**Why this worked:**
+
+1. **Every piece of copy got a role label** (HERO / SUB / BANNER / TAG) with position and style — no guessing.
+2. **Every text string was marked `(EXACT TEXT)`** and wrapped in quotes.
+3. **Concrete visual facts** (CRT scanlines, chrome gradient, palm silhouettes) replaced vague words like "cool" and "awesome."
+4. **`No duplicate text. No extra words.`** was in the CONSTRAINTS block — GPT Image 2 loves to duplicate headlines if you don't forbid it.
+5. **Aspect ratio** chosen from the valid GPT Image 2 set (`1536x1024`) rather than asking for "16:9" and hoping.
+
+## Common Workflows
+
+### Poster / social asset
+
+Use `1536x1024` for X/Twitter, `1024x1024` for IG grid, `1024x1536` for IG story.
+Put every copy element on its own labeled line in the CONSTRAINTS block. Always include
+`No duplicate text. No extra words.`
+
+### UI screen mockup
+
+State the device, status bar, app name, screen title, each visible element with position
+and state (checked, active, disabled), palette (hex-ish is fine: "deep navy accent"),
+typography scale, corner radius, spacing feel.
+
+### Product shot
+
+Surface + light source + lens + depth of field + one hero object. Name the material
+of everything in frame. Avoid "beautiful" — describe what you'd see.
+
+### Concept/brand exploration
+
+Generate 3–4 variants with the same 5-section skeleton but swap only the DETAILS
+block (palette, lens, material). Keep SCENE/SUBJECT/USE CASE/CONSTRAINTS identical
+so you're actually comparing one variable.
+
+## Prompt Template (copy-paste and fill in)
+
+```
+SCENE: <where/when/background>
+
+SUBJECT: <main focus, concrete nouns>
+
+DETAILS: <materials, texture, lighting (source + quality + color),
+         camera angle, lens feel, depth of field, composition, mood>
+
+USE CASE: <poster | UI screen | product shot | editorial photo | concept frame>
+
+CONSTRAINTS:
+- HERO (EXACT TEXT): "<verbatim copy>"
+- SUB: "<verbatim copy>"
+- <other copy with role labels>
+- <typography rules: font style, weight, spacing, hierarchy>
+- No extra words. No duplicate text. No watermark.
+- <anything that must not drift: face, layout, aspect ratio>
+```
+
+## Three Operating Modes (at a glance)
+
+| Mode | When | Endpoint | Pattern |
+|---|---|---|---|
+| Generate | From scratch | `/v1/images/generations` | 5-section framework |
+| Edit | One image, localized change | `/v1/images/image2image` | Change / Preserve / Constraints |
+| Combine | Multi-image composition | `/v1/images/image2image` (multi-ref) | Labeled refs (SUBJECT / ENV / STYLE) |
+
+## Notes & Gotchas
+
+- **GPT Image 2 is currently the best for legible on-image text.** For artistic prompts with no copy, Nano Banana is 4× cheaper and often prettier.
+- **Response shape:** `result.data[0].url` is either an HTTPS URL or a `data:image/...;base64,...` string. Save via `urllib.request.urlretrieve` for URLs or `base64.b64decode(item.b64_json)` for b64 payloads.
+- **Aspect ratio:** only the three sizes above are valid for GPT Image 2. If the user asks for 16:9, use `1536x1024` — it reads as landscape on X/Twitter without cropping.
+- **Iterative edits drift.** Repeat the PRESERVE list every turn, even when it feels redundant.
+- **If text keeps breaking:** shorten it, spell difficult words, and move it to a dedicated `CONSTRAINTS` line marked `(EXACT TEXT)`.
+- **Never use** words like *amazing, stunning, masterpiece, ultra-detailed, 8k, trending on artstation* — they waste tokens and pull toward generic AI-slop aesthetics.
+
+## Requirements
+
+- BlockRun SDK: `pip install blockrun-llm`
+- USDC wallet funded (`ImageClient().get_wallet_address()`; `setup_agent_wallet().get_balance()`)
+- For `edit` / multi-ref: source images must be reachable by a public URL or passed as a data URL
+
+## Reference
+
+BlockRun image models: `openai/gpt-image-2`, `openai/gpt-image-1`, `google/nano-banana`, `google/nano-banana-pro`, `zai/cogview-4`, `xai/grok-imagine-image`, `xai/grok-imagine-image-pro`

package/skills/modal/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: modal
+description: Use when the user needs to run isolated code remotely — a disposable container, optional GPU access (T4 → H100), or a safer place for untrusted / heavy code. Prefer local execution for normal repo work; use Modal sandboxes for isolation, hardware access, or one-shot heavy compute.
+triggers:
+  - "modal sandbox"
+  - "remote python"
+  - "sandbox execution"
+  - "isolated code run"
+  - "gpu sandbox"
+  - "h100"
+  - "a100"
+  - "remote container"
+  - "ephemeral container"
+  - "run untrusted code"
+---
+
+# Modal Sandboxes
+
+Disposable remote containers (with optional GPU) via Modal, paid per call in USDC. No Modal account, no GPU procurement — pay only for what runs.
+
+## How to Call from MCP
+
+```ts
+// 1. Create
+blockrun_modal({ path: "sandbox/create", body: {
+  image: "python:3.11",
+  gpu: "A100",
+  timeout: 600,
+  setup_commands: ["pip install torch transformers"]
+}})
+// returns { sandbox_id, ... }
+
+// 2. Exec
+blockrun_modal({ path: "sandbox/exec", body: {
+  sandbox_id: "sb_abc...",
+  command: ["python", "-c", "import torch; print(torch.cuda.get_device_name(0))"]
+}})
+
+// 3. Terminate
+blockrun_modal({ path: "sandbox/terminate", body: { sandbox_id: "sb_abc..." } })
+```
+
+## Endpoint Catalog
+
+| Path | Method | Body | Price |
+|---|---|---|---|
+| `sandbox/create` | POST | `{ image?, timeout?, cpu?, memory?, gpu?, setup_commands? }` | $0.01 |
+| `sandbox/exec` | POST | `{ sandbox_id, command: ["python","-c","..."], timeout? }` | $0.001 |
+| `sandbox/status` | POST | `{ sandbox_id }` | $0.001 |
+| `sandbox/terminate` | POST | `{ sandbox_id }` | $0.001 |
+
+## Field Reference
+
+| Field | Default | Notes |
+|---|---|---|
+| `image` | `python:3.11` | Any public Docker image. `nvidia/cuda:12-runtime` if you bring GPU code. |
+| `timeout` | 300 | Sandbox lifetime in seconds (idle eviction) |
+| `cpu` | 1 | CPU cores |
+| `memory` | 1024 | Memory in MB |
+| `gpu` | none | `T4` / `L4` / `A10G` / `A100` / `A100-80GB` / `H100` |
+| `setup_commands` | `[]` | Shell commands run once during sandbox provisioning |
+| `command` (exec) | required | Array form: `["python","-c","print(2+2)"]` |
+
+## Worked Examples
+
+### 1. Quick Python eval
+
+```ts
+const { structuredContent: sb } = await blockrun_modal({ path: "sandbox/create", body: {} })
+await blockrun_modal({ path: "sandbox/exec", body: {
+  sandbox_id: sb.sandbox_id,
+  command: ["python", "-c", "import numpy; print(numpy.__version__)"]
+}})
+await blockrun_modal({ path: "sandbox/terminate", body: { sandbox_id: sb.sandbox_id } })
+```
+**Cost: $0.012** ($0.01 + $0.001 + $0.001).
+
+### 2. GPU inference, A100, with deps pre-installed
+
+```ts
+blockrun_modal({ path: "sandbox/create", body: {
+  image: "pytorch/pytorch:2.4.0-cuda12.1-cudnn9-runtime",
+  gpu: "A100",
+  timeout: 1200,
+  memory: 16384,
+  setup_commands: ["pip install --quiet transformers accelerate"]
+}})
+```
+Then `sandbox/exec` with your inference command. Sandbox auto-evicts after 1200s idle.
+
+### 3. Test untrusted code Claude generated
+
+```ts
+blockrun_modal({ path: "sandbox/exec", body: {
+  sandbox_id,
+  command: ["bash", "-c", "<the generated script>"],
+  timeout: 60
+}})
+```
+Output is captured. No risk to your local machine.
+
+## When NOT to Use Modal
+
+- **Normal repo edits / dev work** — use local tools, Modal adds latency and cost
+- **Long-running services** — sandboxes are ephemeral, not server hosts
+- **Anything you'd run hundreds of times per minute** — payment overhead dominates at high QPS
+
+## Notes
+
+- `sandbox_id` is returned by `create` and required by every other endpoint
+- `exec` is sync — blocks until command finishes or hits its `timeout`
+- `terminate` is cheap; call it to free the sandbox even if `timeout` would expire shortly
+- The free-tier `nvidia/*` LLM models in `blockrun_chat` are different infrastructure — Modal is for *your* arbitrary code
+
+## Reference
+
+- Endpoints: `POST /v1/modal/sandbox/{create,exec,status,terminate}`
+- Upstream: [Modal](https://modal.com)