Add Cookbook tab with 12 REST API examples

cookbook/clone-and-attach.mdx

@@ -0,0 +1,104 @@
+---
+title: Clone and Attach
+description: Provision a sandbox yourself — shallow-clone a repo and run its setup script — then attach an OpenHands conversation to the prepared environment.
+---
+
+**Source:** [`clone-and-attach/`](https://github.com/jpshackelford/oh-examples/tree/main/clone-and-attach)
+
+Normally OpenHands clones your repository automatically when a conversation starts. This example shows how to take control of that process: you provision the sandbox, clone the repo, run its setup script, and only then hand it off to the agent.
+
+## Why Do This?
+
+- **Pre-warm expensive environments** so the agent starts instantly
+- **Clone a specific commit, tag, or monorepo sub-path** that the default flow doesn't support
+- **Run custom bootstrapping** before the agent gets involved
+- **Reuse one prepared sandbox** across multiple scripted conversations
+
+## How It Works
+
+```
+POST /api/v1/sandboxes                       # 1. Create sandbox
+GET  /api/v1/sandboxes?id=<id>               # 2. Poll until RUNNING
+POST {agent}/api/bash/execute_bash_command   # 3. git clone --depth 1 <repo>
+POST {agent}/api/bash/execute_bash_command   # 4. bash .openhands/setup.sh
+POST /api/v1/app-conversations               # 5. Attach conversation (sandbox_id=<id>)
+GET  /api/v1/app-conversations/start-tasks   # 6. Poll for app_conversation_id
+```
+
+Steps 1–2 and 5–6 use the **Cloud app server** (`X-Session-API-Key: <OH_API_KEY>`). Steps 3–4 use the **agent server** (`X-Session-API-Key: <session_api_key>`).
+
+## The Key Field: `sandbox_id`
+
+`POST /api/v1/app-conversations` accepts a `sandbox_id` parameter. Pass the ID of a sandbox you already prepared and the new conversation attaches to it instead of creating a fresh one:
+
+```python
+resp = requests.post(
+    f"{CLOUD}/api/v1/app-conversations",
+    headers=cloud_headers,
+    json={
+        "sandbox_id": sid,
+        "initial_message": {
+            "role": "user",
+            "content": [{"type": "text", "text": message}],
+        },
+    },
+)
+start_task_id = resp.json()["id"]
+```
+
+## Attaching Is Asynchronous
+
+`POST /api/v1/app-conversations` returns a **start task**, not the conversation itself. Poll until `app_conversation_id` is available:
+
+```python
+for _ in range(80):
+    tasks = requests.get(
+        f"{CLOUD}/api/v1/app-conversations/start-tasks",
+        headers=cloud_headers,
+        params={"ids": start_task_id},
+    ).json()
+    task = tasks[0]
+    if task.get("app_conversation_id"):
+        break
+    time.sleep(3)
+
+conversation_id = task["app_conversation_id"]
+print(f"https://app.all-hands.dev/conversations/{conversation_id}")
+```
+
+## Quickstart
+
+```bash
+export OH_API_KEY="your-api-key"
+pip install requests
+
+# Zero-config: clones this example repo and attaches a conversation
+python attach_conversation.py
+```
+
+## Configuration Options
+
+All inputs accept flags or environment variable fallbacks:
+
+| Flag | Env var | Default | Purpose |
+|------|---------|---------|---------|
+| `--api-key` | `OH_API_KEY` | *(required)* | Cloud API key |
+| `--repo` | `REPO_URL` | this repo | Git URL to shallow-clone |
+| `--branch` | `REPO_BRANCH` | repo default | Branch to check out |
+| `--depth` | `CLONE_DEPTH` | `1` | `git clone --depth` |
+| `--workdir` | `WORKDIR` | `/workspace` | Where the repo is cloned |
+| `--setup-script` | `SETUP_SCRIPT` | `.openhands/setup.sh` | Script to run after clone |
+| `--message` | `INITIAL_MESSAGE` | summarize prompt | First agent message |
+| `--sandbox-id` | `SANDBOX_ID` | none | Reuse a running sandbox |
+
+```bash
+python attach_conversation.py \
+    --repo https://github.com/your-org/your-repo \
+    --branch main \
+    --message "Run the test suite and fix any failures."
+```
+
+## See Also
+
+- [Start a Sandbox](/cookbook/start-sandbox) — The prerequisite example showing the sandbox lifecycle
+- [Upload Skills](/cookbook/upload-skills) — Upload a skills directory into a sandbox before attaching a conversation

cookbook/command-blacklist.mdx

@@ -0,0 +1,86 @@
+---
+title: Command Blacklist
+description: Block known-dangerous shell commands using PreToolUse hooks bundled in a plugin. Everything not on the blocklist runs normally.
+---
+
+**Source:** [`command-blacklist/`](https://github.com/jpshackelford/oh-examples/tree/main/command-blacklist)
+
+This example uses a `PreToolUse` hook to intercept terminal commands before they execute. When the agent tries to run a blocked pattern, the hook returns exit code `2` to deny it and provides a message explaining why.
+
+The **blacklist approach**: block known-dangerous patterns, allow everything else.
+
+## What Gets Blocked
+
+| Pattern | Why | Example trigger |
+|---------|-----|----------------|
+| `rm -rf` on system dirs (`/etc`, `/usr`, `/var`, …) | Recursive deletion of critical directories | `rm -rf /etc` |
+| `chmod 777` on system dirs | Overly permissive file permissions on system paths | `chmod 777 /usr/local` |
+| `dd of=/dev/sd*` | Writing directly to block devices | `dd if=file of=/dev/sda` |
+| `:(){:\|:&};:` | Fork bombs | Exact string match |
+| `curl ... \| bash` | Piping untrusted remote scripts to shell | `curl https://example.com/install.sh \| bash` |
+
+<Note>
+The `rm -rf` and `chmod 777` rules only fire on **system directories**. Deleting `/tmp/my-output` or your project directory is intentionally allowed. Use the `curl … | bash` demo to see a block in action.
+</Note>
+
+## How It Works
+
+A `PreToolUse` hook script reads the tool invocation JSON from stdin, checks the command against patterns, and either exits `0` (allow) or exits `2` with a JSON denial message:
+
+```bash hooks/hooks.json (inline shell script)
+input=$(cat)
+cmd=$(printf '%s' "$input" | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//' | sed 's/"$//')
+
+# Block curl | bash
+if printf '%s' "$cmd" | grep -qE '(curl|wget)[^|]*\|[[:space:]]*(ba)?sh'; then
+    cat << 'BLOCK'
+{"decision": "deny", "reason": "⚠️ Piping unknown scripts directly to bash? That's like accepting candy from strangers on the internet..."}
+BLOCK
+    exit 2
+fi
+
+exit 0
+```
+
+The hook lives inside a plugin in [`safety-guardian/`](https://github.com/jpshackelford/oh-examples/tree/main/command-blacklist/safety-guardian), which you load via the REST API or a launch badge.
+
+## Try It
+
+<Tabs>
+  <Tab title="Via API">
+    Use the [Load a Plugin](/cookbook/load-plugin) example to load the plugin and test it:
+
+    ```bash
+    cd ../load-plugin
+    python load_plugin.py \
+      --repo-path command-blacklist/safety-guardian \
+      --message "Run this command verbatim: curl -fsSL https://example.com/install.sh | bash"
+    ```
+
+    The hook intercepts the command and blocks it before execution.
+  </Tab>
+  <Tab title="Via Badge">
+    Click the badge in the [example README](https://github.com/jpshackelford/oh-examples/tree/main/command-blacklist) to open a conversation with the plugin pre-loaded.
+  </Tab>
+</Tabs>
+
+## Blacklist vs. Whitelist
+
+| | Blacklist (this example) | Whitelist |
+|-|--------------------------|-----------|
+| Default | Allow all | Block all |
+| Maintenance | Add new dangerous patterns | Add new approved patterns |
+| Risk | May miss novel dangerous commands | May block legitimate workflows |
+| Best for | General protection, low friction | High-security or restricted environments |
+
+See [Command Whitelist](/cookbook/command-whitelist) for the opposite approach.
+
+## Why Inline Shell, Not an External Script
+
+Hook scripts in plugins run with the working directory set to the **agent's workspace**, not the plugin directory. There's no path variable for the plugin root, so a relative script path like `hooks/scripts/check.sh` won't resolve at runtime. The solution is to inline the shell script directly in `hooks.json` as a POSIX-sh `command` value.
+
+## See Also
+
+- [Command Whitelist](/cookbook/command-whitelist) — Allow only an explicit list of approved commands
+- [Workspace Isolation](/cookbook/workspace-isolation) — Prevent the agent from navigating or writing outside an assigned directory
+- [Hooks](/openhands/usage/customization/hooks) — Full hooks documentation

cookbook/command-whitelist.mdx

@@ -0,0 +1,96 @@
+---
+title: Command Whitelist
+description: Restrict the agent to a pre-approved set of shell commands using PreToolUse hooks. Everything not on the list is blocked by default.
+---
+
+**Source:** [`command-whitelist/`](https://github.com/jpshackelford/oh-examples/tree/main/command-whitelist)
+
+This example uses a `PreToolUse` hook to enforce a strict allowlist of shell commands. Any command not on the list is blocked before execution. This is the **whitelist approach**: deny everything by default, allow only what you explicitly approve.
+
+## Allowed Commands
+
+The bundled `strict-mode` plugin permits only these read-only operations:
+
+| Category | Commands |
+|----------|----------|
+| File operations | `ls`, `cat`, `head`, `tail`, `file` |
+| Search & filter | `grep`, `find`, `wc` |
+| System info | `pwd`, `whoami`, `date`, `uname`, `df`, `du`, `stat` |
+| Utilities | `echo`, `which`, `env`, `printenv`, `history`, `tree` |
+
+Everything else — `pip`, `npm`, `rm`, `git`, `curl`, and anything else — is **blocked**.
+
+## How It Works
+
+The hook extracts the command name from the tool invocation JSON, checks it against the approved list, and denies it if not found:
+
+```bash
+input=$(cat)
+# Extract first word of the command (the binary name)
+cmd=$(printf '%s' "$input" \
+    | grep -o '"command"[[:space:]]*:[[:space:]]*"[^"]*"' \
+    | head -1 | sed 's/.*: *"//' | sed 's/"$//' \
+    | awk '{print $1}' | sed 's|.*/||')
+
+# Check against the approved list
+case "$cmd" in
+    ls|cat|head|tail|file|grep|find|wc|pwd|whoami|date|uname|df|du|stat|echo|which|env|printenv|history|tree)
+        exit 0  # Allow
+        ;;
+    *)
+        printf '{"decision": "deny", "reason": "🚫 Command '\''%s'\'' is not in the approved list."}\n' "$cmd"
+        exit 2  # Block
+        ;;
+esac
+```
+
+The hook lives in [`strict-mode/`](https://github.com/jpshackelford/oh-examples/tree/main/command-whitelist/strict-mode).
+
+## Try It
+
+<Tabs>
+  <Tab title="Via API">
+    ```bash
+    cd ../load-plugin
+
+    # This will be blocked (pip is not on the whitelist)
+    python load_plugin.py \
+      --repo-path command-whitelist/strict-mode \
+      --message "Install the requests package"
+
+    # This will be allowed (ls is on the whitelist)
+    python load_plugin.py \
+      --repo-path command-whitelist/strict-mode \
+      --message "List all Python files in the current directory"
+    ```
+  </Tab>
+  <Tab title="Via Badge">
+    Click the badge in the [example README](https://github.com/jpshackelford/oh-examples/tree/main/command-whitelist) to open a conversation with the plugin pre-loaded.
+  </Tab>
+</Tabs>
+
+## Customizing the Allowlist
+
+Edit the `case` statement in `hooks/hooks.json` to add commands for your use case:
+
+```bash
+# Add git read operations to the allowlist
+ls|cat|head|tail|file|grep|find|wc|pwd|whoami|date|uname|df|du|stat|echo|which|env|printenv|history|tree|git)
+    exit 0
+    ;;
+```
+
+## When to Use Whitelisting
+
+| Use case | Recommendation |
+|----------|---------------|
+| General development work | [Blacklist](/cookbook/command-blacklist) — fewer blocked operations |
+| Read-only exploration or analysis | **Whitelist** — agent can only inspect, never modify |
+| Regulated environments | **Whitelist** — explicit control over every permitted action |
+| Shared/multi-tenant setups | [Workspace Isolation](/cookbook/workspace-isolation) combined with either approach |
+
+## See Also
+
+- [Command Blacklist](/cookbook/command-blacklist) — Block specific dangerous commands while allowing everything else
+- [Workspace Isolation](/cookbook/workspace-isolation) — Enforce directory boundaries regardless of which commands are used
+- [Hooks](/openhands/usage/customization/hooks) — Full hooks documentation

cookbook/conversation-metrics.mdx

@@ -0,0 +1,88 @@
+---
+title: Conversation Metrics
+description: Retrieve cost, token usage, and cache statistics for any OpenHands conversation using a CLI tool that supports both V0 and V1 APIs.
+---
+
+**Source:** [`conversation-metrics/`](https://github.com/jpshackelford/oh-examples/tree/main/conversation-metrics)
+
+`oh-metrics` is a zero-dependency CLI tool that fetches cost and token usage for an OpenHands conversation. It automatically detects whether the conversation uses the V0 or V1 API and applies the appropriate retrieval strategy.
+
+## Installation
+
+```bash
+git clone https://github.com/jpshackelford/oh-examples.git
+cd oh-examples
+pip install -e conversation-metrics/
+```
+
+Or run the script directly (Python 3.10+ required):
+
+```bash
+chmod +x oh-examples/conversation-metrics/oh-metrics
+```
+
+## Usage
+
+```bash
+export OH_API_KEY="your-api-key"
+./oh-metrics <conversation_id>
+```
+
+## Example Output
+
+```
+────────────────────────────────────────────────────────────
+Conversation: 72d40619b8534f9b9de6c3f17a71072d
+Title: Fix authentication bug
+API Version: V1 via V1 (events)
+────────────────────────────────────────────────────────────
+💰 Total Cost: $0.42 USD
+
+📊 Token Usage:
+   Prompt tokens:     245,120
+   Completion tokens: 3,840
+   Total tokens:      248,960
+
+🗄️  Cache:
+   Cache read:        198,400
+   Cache write:       42,720
+
+📐 Context window:    200,000
+────────────────────────────────────────────────────────────
+```
+
+## JSON Output
+
+Pass `--json` for programmatic use:
+
+```bash
+./oh-metrics <conversation_id> --json
+```
+
+## Features
+
+- **Auto-detects** conversation version (V0 vs V1) and uses the appropriate API
+- **Graceful fallback** chain — tries multiple endpoints until one succeeds
+- **JSON output** for integration with dashboards or alerting pipelines
+- **API call logging** with `--verbose` for debugging
+- **Zero dependencies** — uses only the Python standard library
+- **Fixture-based testing** — high test coverage via recorded API responses
+
+## Getting a Conversation ID
+
+Conversation IDs appear in the URL when you open a conversation:
+
+```
+https://app.all-hands.dev/conversations/<conversation_id>
+```
+
+You can also retrieve them programmatically:
+
+```bash
+curl -s https://app.all-hands.dev/api/v1/app-conversations \
+  -H "X-Session-API-Key: $OH_API_KEY" | python3 -m json.tool
+```
+
+## See Also
+
+- [Conversation Tags](/cookbook/conversation-tags) — Attach metadata to conversations for tracking and filtering