Skip to main content
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 repository on GitHub.

​
Prerequisites

Most examples require an OpenHands API key: 
export OH_API_KEY="your-api-key"
Get your API key from app.all-hands.dev under Settings → API Keys.

​
Examples

​
Sandboxes

Start a Sandbox

Create a sandbox via the V1 API and run shell commands directly against the agent-server — no conversation needed.

Clone and Attach

Provision a sandbox yourself (clone a repo + run its setup script), then attach a conversation to that prepared environment.

​
Conversations

Conversation Metrics

CLI tool to retrieve cost and token usage for any conversation, with support for both V0 and V1 APIs.

Conversation Tags

Attach arbitrary key-value metadata to a conversation and read it back from your own tooling.

Per-Conversation Secrets

Inject secrets scoped to a single conversation — as bash environment variables or to authenticate an MCP server.

​
Plugins & Skills

Load a Plugin

Start a conversation with a plugin pre-loaded using a single REST API field.

Launch Plugin Badge

Build a no-code /launch link, HTML button, or README badge that opens a conversation with your plugin pre-loaded.

Upload Skills

Upload a local skills directory into a sandbox so every subsequent conversation inherits those skills.

Test MCP Config

Validate MCP server configurations against a live sandbox before wiring them into a conversation.

​
Hooks

Command Blacklist

Block known-dangerous shell commands with PreToolUse hooks while letting everything else through.

Command Whitelist

Restrict the agent to a pre-approved set of commands with PreToolUse hooks.

Workspace Isolation

Enforce directory boundaries with hooks — prevent agents from navigating or writing outside their assigned workspace.

​
API Overview

The OpenHands Cloud API has two server types that work together:
ServerBase URLAuth headerPurpose
Cloud app serverhttps://app.all-hands.devX-Session-API-Key: <OH_API_KEY>Manages sandboxes and conversations
Agent serverFrom sandbox.exposed_urlsX-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.
  • Cloud API Reference — Full API reference for the OpenHands Cloud API
  • Plugins — How plugins work and how to create them
  • Hooks — Full hooks reference for repository-based hooks
  • Skills — How to create and use skills