AGENTS

OpenHands Docs Repository (Mintlify)

This repo hosts the unified documentation site for the OpenHands ecosystem:

• OpenHands Agent SDK (SDK + REST API)
• OpenHands CLI
• OpenHands Web/App (GUI + Cloud + REST API)

The site is built with Mintlify and deployed automatically by Mintlify on pushes to main.

Quick orientation

Key files/directories

• docs.json — Mintlify site configuration (nav tabs, redirects, OpenAPI integration)
• overview/ — high-level docs (intro, quickstart, community, skills overview)
• openhands/usage/ — product docs for Web/Cloud/CLI/etc.
• sdk/ — Agent SDK docs (guides, architecture, API reference pages)
• openapi/ — OpenAPI specs consumed by Mintlify
  • openapi/V0_openapi.json — OpenHands V0 REST API schema (legacy)
  • openapi/openhands-cloud.json — OpenHands Cloud REST API schema (served by app.all-hands.dev; surfaced as a collapsible REST API group under the Cloud tab → Integrations)
  • openapi/agent-sdk.json — Agent SDK agent-server schema (synced from software-agent-sdk)
• scripts/ — automation for generating SDK API reference docs
• .github/workflows/ — CI workflows (broken link checks, sync jobs)
• .github/scripts/ — helper scripts used by CI
• .agents/skills/ — prompt extensions for agents editing this repo (legacy: .openhands/skills/; formerly microagents)
• tests/ — pytest checks for docs consistency (notably LLM pricing docs)

Cross-Repository Boundaries

This repository owns the unified documentation site and documentation-specific tooling. The documented source repositories have distinct responsibilities:

• OpenHands/OpenHands owns Agent Canvas UI and local-stack orchestration.
• OpenHands/software-agent-sdk owns the Python SDK, Agent Server, agent/tool behavior, conversations, workspaces, events, and canonical API.
• OpenHands/typescript-client owns the browser-compatible typed Agent Server client.
• OpenHands/automation owns scheduling, webhooks, run history, dispatch, and sandbox lifecycle orchestration.
• OpenHands/extensions owns reusable skills, plugins, automations, and integrations.

Documentation should describe these boundaries accurately. If a documentation PR is opened in the wrong source repository, explicitly recommend closing and moving it to the repository that owns the change. PRs must follow this repository’s applicable code-review guidance.

llms.txt / llms-full.txt (V1-only)

Mintlify auto-generates /llms.txt and /llms-full.txt, but this repo overrides them by committing llms.txt and llms-full.txt at the repo root.

We do this so LLMs get V1-only context while legacy V0 pages remain available for humans.

• Generator script: scripts/generate-llms-files.py
• Sync workflow: .github/workflows/check-llms-files.yml runs weekly (and on demand) to open a PR when the files drift.
• Regenerate (recommended):
  make llms
  
  Or directly:
  python3 scripts/generate-llms-files.py
  
• Local verify (optional):
  make llms-check
  
• Exclusions: openhands/usage/v0/ and any V0*-prefixed page files.

Local development

Preview the site

Mintlify uses the mint CLI.

npm install -g mintlify@latest
mint dev

Useful checks:

mint broken-links

Python tooling (sync/generation scripts)

This repo includes Python scripts that generate or validate parts of the docs.

This repo isn’t a Python package (no pyproject.toml), so for one-off runs we prefer uv to create an ephemeral environment:

# Generate SDK API reference docs
uv run --with sphinx --with sphinx-markdown-builder --with myst-parser \
  python scripts/generate-api-docs.py

# Run pytest-based checks (only this repo's tests)
uv run --with pytest --with requests pytest -q tests/

(You can still use pip install ... if you prefer a long-lived local environment.)

Cross-repo sync automation (important)

A lot of SDK documentation is derived from or kept in sync with OpenHands/software-agent-sdk.

1) Syncing code blocks from software-agent-sdk/examples/*

Script: .github/scripts/sync_code_blocks.py

• Scans all .mdx files for code blocks that include a file reference (Python and YAML supported).
• Replaces the block content with the content from the referenced file in a checked-out agent-sdk/ folder.

Expected code block format (examples):

```python icon="python" expandable examples/01_standalone_sdk/02_custom_tools.py
# content is auto-synced
```

```yaml icon="yaml" expandable examples/03_github_workflows/02_pr_review/workflow.yml
# content is auto-synced
```

Local run:

git clone https://github.com/OpenHands/software-agent-sdk.git agent-sdk
python .github/scripts/sync_code_blocks.py
rm -rf agent-sdk

CI: .github/workflows/sync-docs-code-blocks.yml

2) Generating SDK API reference pages

Script: scripts/generate-api-docs.py

• Uses Sphinx + sphinx-markdown-builder to generate Mintlify-friendly .mdx pages under sdk/api-reference/.

Local run:

uv run --with sphinx --with sphinx-markdown-builder --with myst-parser \
  python scripts/generate-api-docs.py

CI: also run by .github/workflows/sync-docs-code-blocks.yml

3) Syncing agent-sdk OpenAPI schema

Workflow: .github/workflows/sync-agent-sdk-openapi.yml

• Checks out OpenHands/software-agent-sdk
• Runs the agent-server OpenAPI generator
• Updates openapi/agent-sdk.json via an automated PR

4) Cookbook tab generated from OpenHands/enterprise-cookbook

Every page under cookbook/ and the Cookbook tab in docs.json are generated from example READMEs in OpenHands/enterprise-cookbook by its tools/docs-render converter. Do not edit them here; change the example’s README.md or example.yaml in that repository.

• Each enterprise-cookbook PR gets a draft cookbook-preview/pr-<N> PR here for its Mintlify preview. These are never merged and close with the source PR.
• Merged changes arrive in a single cookbook-sync PR, opened by openhands-release-bot and refreshed nightly.
• .github/workflows/cookbook-generated.yml fails PRs from any other branch that touch cookbook/, and sync_code_blocks.py skips cookbook/ because its code-block paths are relative to each example.

Docs writing conventions

• Most pages are .mdx with frontmatter:
  ---
  title: ...
  description: ...
  ---
  
• Follow the style rules in openhands/DOC_STYLE_GUIDE.md.
• Use Mintlify components (<Note>, <Warning>, <Tabs>, etc.) where appropriate.
• When linking internally, prefer absolute doc paths (e.g. /overview/quickstart).
• When documenting prompt/context behavior, avoid ambiguous transport phrasing like “sent with each request” unless discussing the actual API transport. Prefer precise wording such as “included in the initial system prompt” and “remains part of the conversation/LLM context for subsequent turns.”
• Cloud integration docs live under openhands/usage/cloud/, and pages surfaced in Documentation → Integrations → Cloud API must also be added to the Cloud API group in docs.json.

Mintlify tab ownership

When the same page path appears under multiple top-level tabs in docs.json, Mintlify resolves the page to one tab/sidebar (effectively the first matching tab). If you want a page to show a distinct left navigation for a new tab, that page should live exclusively under that tab rather than being duplicated across tabs.

SDK guide file naming

SDK guide files under sdk/guides/ use a category prefix to group related pages:

Prefix	Category	Examples
llm-	LLM features (model configuration, providers, streaming, presets)	llm-reasoning.mdx, llm-gpt5-preset.mdx
agent-	Agent features (customization, browser, settings)	agent-custom.mdx, agent-settings.mdx
convo-	Conversation features (async, persistence, pause/resume)	convo-async.mdx, convo-persistence.mdx

When adding a new SDK guide, always use the appropriate prefix so that related files sort together and the sidebar grouping in docs.json stays consistent.

LLM API Key Options

The SDK documentation maintains three ways for users to obtain LLM access:

1. Direct Provider - Bring your own API key from providers like Anthropic, OpenAI, etc.
2. OpenHands Cloud - Use OpenHands Cloud API keys (recommended for verified models)
3. Third-party Subscription Login - Authenticate with existing subscriptions (e.g., ChatGPT Plus/Pro via LLM.subscription_login())

When documenting LLM setup or examples, ensure all three options are mentioned where appropriate:

• sdk/getting-started.mdx - Main getting started page with AccordionGroup
• sdk/shared-snippets/how-to-run-example.mdx - Shared snippet for running examples
• sdk/guides/llm-subscriptions.mdx - Dedicated guide for subscription login

Documentation ownership patterns

• Keep sdk/guides/observability.mdx as the canonical tracing and OTEL reference for OpenHands SDK users, including Laminar links and generic backend configuration.
• Keep enterprise/analytics.mdx focused on OpenHands Enterprise deployment and admin-console setup, and link back to the SDK observability guide instead of duplicating OTEL reference material.

Validation

LLM pricing table validation

There are two layers of protection for openhands/usage/llms/openhands-llms.mdx:

• CI workflow: .github/workflows/validate-llm-pricing.yml runs .github/scripts/validate_llm_pricing.py
• Local tests: pytest -q (see tests/test_pricing_documentation.py)

Run locally:

uv run --with pytest --with requests pytest -q tests/

OpenHands/extensions — No Release Tags

OpenHands/extensions does not publish versioned release tags (no v1, v2, etc.). All GitHub Action references to plugins in that repo must use @main:

uses: OpenHands/extensions/plugins/qa-changes@main
uses: OpenHands/extensions/plugins/pr-review@main

Do not suggest pinning to @v1 or any other tag — they don’t exist and the workflow will fail.

Related repos (source-of-truth)

• OpenHands Agent SDK: https://github.com/OpenHands/software-agent-sdk
• OpenHands CLI: https://github.com/OpenHands/OpenHands-CLI
• OpenHands (Web/App): https://github.com/OpenHands/OpenHands
• OpenHands Extensions: https://github.com/OpenHands/extensions (plugins, skills, actions — no release tags)

When updating SDK features or examples, expect to update this repo too (especially under sdk/).