> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-add-cookbook-tab.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cookbook

> Practical, runnable examples for working with the OpenHands REST API.

The Cookbook is a collection of standalone Python examples that show how to use the OpenHands Cloud API. Each example is self-contained, runnable with a single script, and focused on one clear task.

All examples live in the [jpshackelford/oh-examples](https://github.com/jpshackelford/oh-examples) repository on GitHub.

## Prerequisites

Most examples require an OpenHands API key:

```bash theme={null}
export OH_API_KEY="your-api-key"
```

Get your API key from [app.all-hands.dev](https://app.all-hands.dev) under **Settings → API Keys**.

## Examples

### Sandboxes

<CardGroup cols={2}>
  <Card title="Start a Sandbox" icon="box" href="/cookbook/start-sandbox">
    Create a sandbox via the V1 API and run shell commands directly against the agent-server — no conversation needed.
  </Card>

  <Card title="Clone and Attach" icon="code-branch" href="/cookbook/clone-and-attach">
    Provision a sandbox yourself (clone a repo + run its setup script), then attach a conversation to that prepared environment.
  </Card>
</CardGroup>

### Conversations

<CardGroup cols={2}>
  <Card title="Conversation Metrics" icon="chart-bar" href="/cookbook/conversation-metrics">
    CLI tool to retrieve cost and token usage for any conversation, with support for both V0 and V1 APIs.
  </Card>

  <Card title="Conversation Tags" icon="tag" href="/cookbook/conversation-tags">
    Attach arbitrary key-value metadata to a conversation and read it back from your own tooling.
  </Card>

  <Card title="Per-Conversation Secrets" icon="lock" href="/cookbook/per-conversation-secrets">
    Inject secrets scoped to a single conversation — as bash environment variables or to authenticate an MCP server.
  </Card>
</CardGroup>

### Plugins & Skills

<CardGroup cols={2}>
  <Card title="Load a Plugin" icon="plug" href="/cookbook/load-plugin">
    Start a conversation with a plugin pre-loaded using a single REST API field.
  </Card>

  <Card title="Launch Plugin Badge" icon="badge-check" href="/cookbook/launch-plugin-badge">
    Build a no-code `/launch` link, HTML button, or README badge that opens a conversation with your plugin pre-loaded.
  </Card>

  <Card title="Upload Skills" icon="graduation-cap" href="/cookbook/upload-skills">
    Upload a local skills directory into a sandbox so every subsequent conversation inherits those skills.
  </Card>

  <Card title="Test MCP Config" icon="server" href="/cookbook/test-mcp-config">
    Validate MCP server configurations against a live sandbox before wiring them into a conversation.
  </Card>
</CardGroup>

### Hooks

<CardGroup cols={2}>
  <Card title="Command Blacklist" icon="ban" href="/cookbook/command-blacklist">
    Block known-dangerous shell commands with PreToolUse hooks while letting everything else through.
  </Card>

  <Card title="Command Whitelist" icon="shield-check" href="/cookbook/command-whitelist">
    Restrict the agent to a pre-approved set of commands with PreToolUse hooks.
  </Card>

  <Card title="Workspace Isolation" icon="lock-keyhole" href="/cookbook/workspace-isolation">
    Enforce directory boundaries with hooks — prevent agents from navigating or writing outside their assigned workspace.
  </Card>
</CardGroup>

## API Overview

The OpenHands Cloud API has two server types that work together:

| Server               | Base URL                    | Auth header                            | Purpose                                                                  |
| -------------------- | --------------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
| **Cloud app server** | `https://app.all-hands.dev` | `X-Session-API-Key: <OH_API_KEY>`      | Manages sandboxes and conversations                                      |
| **Agent server**     | From `sandbox.exposed_urls` | `X-Session-API-Key: <session_api_key>` | Runs inside each sandbox; executes commands and holds conversation state |

Most examples start by calling the Cloud app server to create a sandbox or conversation, then switch to the agent server to interact with the runtime directly.

## Related Resources

* [Cloud API Reference](/openhands/usage/cloud/cloud-api) — Full API reference for the OpenHands Cloud API
* [Plugins](/overview/plugins) — How plugins work and how to create them
* [Hooks](/openhands/usage/customization/hooks) — Full hooks reference for repository-based hooks
* [Skills](/overview/skills) — How to create and use skills