> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-codex-google-llm-gateway-guide.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Enterprise Cookbook

> Runnable examples for building on the OpenHands API with OpenHands Cloud or OpenHands Enterprise.

Standalone, runnable examples for teams building on the OpenHands API with OpenHands Cloud or
OpenHands Enterprise. Each page is generated from an example in
[OpenHands/enterprise-cookbook](https://github.com/OpenHands/enterprise-cookbook), where you
will find the full source.

## Sandbox lifecycle

Create, attach to, and tear down sandboxes.

<CardGroup cols={2}>
  <Card title="Archive Sandbox" icon="box-archive" href="/cookbook/archive-sandbox">
    Delete conversations to release their Persistent Volume Claims (PVCs) and free storage resources.
  </Card>

  <Card title="Clone and Attach" icon="code-branch" href="/cookbook/clone-and-attach">
    Clone a repository and run its setup script in a sandbox, then attach a conversation to the prepared environment.
  </Card>

  <Card title="Start Sandbox" icon="play" href="/cookbook/start-sandbox">
    Start a sandbox without a conversation and run commands via the agent-server REST API.
  </Card>
</CardGroup>

## Conversation monitoring & reacting

Observe conversations and react to their state.

<CardGroup cols={2}>
  <Card title="Conversation Metrics" icon="chart-line" href="/cookbook/conversation-metrics">
    Retrieve cost and token usage metrics for conversations via CLI tool.
  </Card>

  <Card title="Conversation Tags" icon="tags" href="/cookbook/conversation-tags">
    Attach key-value metadata to a conversation with tags and read it back from AppConversation.tags.
  </Card>

  <Card title="Finish Callback" icon="bell" href="/cookbook/finish-callback">
    Notify an external URL when a conversation finishes using a Stop hook.
  </Card>

  <Card title="React to State WebSocket" icon="bolt" href="/cookbook/react-to-state-websocket">
    React to conversation execution\_status changes over WebSocket instead of polling.
  </Card>

  <Card title="Server Info Idle" icon="clock" href="/cookbook/server-info-idle">
    Poll the idle\_time endpoint to detect when a workspace has gone quiet.
  </Card>

  <Card title="Watch Terminal State" icon="terminal" href="/cookbook/watch-terminal-state">
    Detect confirmed terminal execution\_status over WebSocket with proper event handling.
  </Card>
</CardGroup>

## Secrets & authentication

Inject credentials and manage identity.

<CardGroup cols={2}>
  <Card title="GPG Commit Signing" icon="file-signature" href="/cookbook/gpg-commit-signing">
    Configure GPG commit signing on every conversation with a SessionStart hook that imports a key from a custom secret.
  </Card>

  <Card title="Per-Conversation Secrets" icon="user-secret" href="/cookbook/per-conversation-secrets">
    Inject per-conversation secrets via REST API as bash env vars and to template an MCP server config bundled in a plugin.
  </Card>

  <Card title="Service Account GitHub PAT" icon="id-card" href="/cookbook/service-account-github-pat">
    Use one OpenHands account as a service account, overriding the managed GITHUB\_TOKEN with each user's PAT per conversation.
  </Card>
</CardGroup>

## Plugins, skills & MCP

Extend conversations with plugins, skills, and MCP servers.

<CardGroup cols={2}>
  <Card title="Launch Plugin Badge" icon="rocket" href="/cookbook/launch-plugin-badge">
    Build a no-code /launch link, HTML button, or README badge that loads a plugin.
  </Card>

  <Card title="Load Plugin" icon="plug" href="/cookbook/load-plugin">
    Start a conversation with a plugin pre-loaded via the REST API.
  </Card>

  <Card title="Test MCP Config" icon="vial" href="/cookbook/test-mcp-config">
    Validate MCP server configs against a sandbox agent-server via POST /api/mcp/test.
  </Card>

  <Card title="Upload Skills" icon="upload" href="/cookbook/upload-skills">
    Upload a local agent-skills directory into a sandbox, then start a conversation that uses them.
  </Card>
</CardGroup>

## Custom agents & tools

Configure the agent and add custom tools.

<CardGroup cols={2}>
  <Card title="Custom Agent No Browser" icon="sliders" href="/cookbook/custom-agent-no-browser">
    Configure agent tools via the agent-server API to exclude the browser tool.
  </Card>

  <Card title="Custom Pip Tool Agent" icon="box" href="/cookbook/custom-agent-with-pip-tool">
    Load a custom tool from a published pip package via pip install --target and tool\_module\_qualnames.
  </Card>

  <Card title="Custom Agent With Tool" icon="wrench" href="/cookbook/custom-agent-with-tool">
    Add custom server-side tools via source file upload and tool\_module\_qualnames.
  </Card>

  <Card title="Custom System Prompt" icon="message" href="/cookbook/custom-system-prompt">
    Override the default OpenHands system prompt with a custom one for specialized agents.
  </Card>

  <Card title="Disabled Skills" icon="ban" href="/cookbook/disabled-skills">
    Persist an account-level deny-list of skills so every conversation starts with them disabled.
  </Card>
</CardGroup>

## Guardrails

Constrain what the agent can do with hooks.

<CardGroup cols={2}>
  <Card title="Command Blacklist" icon="shield-halved" href="/cookbook/command-blacklist">
    Block known-dangerous shell commands with a PreToolUse hook bundled in a plugin. Everything not on the blocklist runs normally.
  </Card>

  <Card title="Command Whitelist" icon="user-shield" href="/cookbook/command-whitelist">
    Allow only approved shell commands with PreToolUse hooks (whitelist approach for strict security).
  </Card>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.