Skip to content

πŸ™Œ OpenHands: AI-Driven Development

Update docs (#11224)

mamoodi025ac7672fcd
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
index 66cac495b2..233dce8a24 100644
--- a/.github/workflows/stale.yml
+++ b/.github/workflows/stale.yml
@@ -19,4 +19,4 @@ jobs:
close-issue-message: 'This issue was automatically closed due to 50 days of inactivity. We do this to help keep the issues somewhat manageable and focus on active issues.'
close-pr-message: 'This PR was closed because it had no activity for 50 days. If you feel this was closed in error, and you would like to continue the PR, please resubmit or let us know.'
days-before-close: 10
- operations-per-run: 150
+ operations-per-run: 300
diff --git a/docs/docs.json b/docs/docs.json
index 1b2fd862b0..fd07e8c18b 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -3,18 +3,16 @@
"theme": "mint",
"name": "All Hands Docs",
"colors": {
- "primary": "#99873c",
- "light": "#ffe165",
- "dark": "#ffe165"
+ "primary": "#99873c"
},
"background": {
"color": {
- "light": "#f7f3ee",
- "dark": "#0B0D0E"
+ "light": "#f7f3ee"
}
},
"appearance": {
- "default": "light"
+ "default": "light",
+ "strict": true
},
"favicon": "/logo-square.png",
"navigation": {
@@ -215,8 +213,7 @@
"footer": {
"socials": {
"slack": "https://all-hands.dev/joinslack",
- "github": "https://github.com/All-Hands-AI/OpenHands",
- "discord": "https://discord.gg/ESHStjSjD4"
+ "github": "https://github.com/All-Hands-AI/OpenHands"
}
},
"contextual": {
diff --git a/docs/index.mdx b/docs/index.mdx
index 4fb2874a0f..536f49f246 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -4,7 +4,8 @@ description: OpenHands - Code Less, Make More
icon: book-open
mode: wide
---
-Use AI to tackle the toil in your backlog. Our agents have all the same tools as a human developer: they can modify code, run commands, browse the web, call APIs, and yes-even copy code snippets from StackOverflow.
+Use AI to tackle the toil in your backlog. Our agents have all the same tools as a human developer:
+they can modify code, run commands, browse the web, call APIs, and yes-even copy code snippets from StackOverflow.
<iframe
className="w-full aspect-video"
diff --git a/docs/usage/cloud/cloud-api.mdx b/docs/usage/cloud/cloud-api.mdx
index 656a173984..693b85050a 100644
--- a/docs/usage/cloud/cloud-api.mdx
+++ b/docs/usage/cloud/cloud-api.mdx
@@ -17,96 +17,87 @@ To use the OpenHands Cloud API, you'll need to generate an API key:
4. Give your key a descriptive name (Example: "Development" or "Production") and select `Create`.
5. Copy the generated API key and store it securely. It will only be shown once.
-## API Usage
+## API Usage Example
### Starting a New Conversation
-To start a new conversation with OpenHands to perform a task, you'll need to make a POST request to the conversation endpoint.
-
-#### Request Parameters
-
-| Parameter | Type | Required | Description |
-|--------------------|----------|----------|------------------------------------------------------------------------------------------------------|
-| `initial_user_msg` | string | Yes | The initial message to start the conversation. |
-| `repository` | string | No | Git repository name to provide context in the format `owner/repo`. You must have access to the repo. |
-
-#### Examples
-
+To start a new conversation with OpenHands to perform a task,
+[you'll need to make a POST request to the conversation endpoint](/api-reference/new-conversation).
+
+<Tabs>
+ <Tab title="cURL">
+ ```bash
+ curl -X POST "https://app.all-hands.dev/api/conversations" \
+ -H "Authorization: Bearer YOUR_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
+ "repository": "yourusername/your-repo"
+ }'
+ ```
+ </Tab>
+ <Tab title="Python (with requests)">
+ ```python
+ import requests
+
+ api_key = "YOUR_API_KEY"
+ url = "https://app.all-hands.dev/api/conversations"
+
+ headers = {
+ "Authorization": f"Bearer {api_key}",
+ "Content-Type": "application/json"
+ }
-<Accordion title="cURL">
- ```bash
- curl -X POST "https://app.all-hands.dev/api/conversations" \
- -H "Authorization: Bearer YOUR_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{
- "initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
- "repository": "yourusername/your-repo"
- }'
- ```
-</Accordion>
+ data = {
+ "initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
+ "repository": "yourusername/your-repo"
+ }
-<Accordion title="Python (with requests)">
- ```python
- import requests
+ response = requests.post(url, headers=headers, json=data)
+ conversation = response.json()
- api_key = "YOUR_API_KEY"
- url = "https://app.all-hands.dev/api/conversations"
+ print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation['conversation_id']}")
+ print(f"Status: {conversation['status']}")
+ ```
+ </Tab>
+ <Tab title="TypeScript/JavaScript (with fetch)">
+ ```typescript
+ const apiKey = "YOUR_API_KEY";
+ const url = "https://app.all-hands.dev/api/conversations";
- headers = {
- "Authorization": f"Bearer {api_key}",
+ const headers = {
+ "Authorization": `Bearer ${apiKey}`,
"Content-Type": "application/json"
- }
-
- data = {
- "initial_user_msg": "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
- "repository": "yourusername/your-repo"
- }
-
- response = requests.post(url, headers=headers, json=data)
- conversation = response.json()
-
- print(f"Conversation Link: https://app.all-hands.dev/conversations/{conversation['conversation_id']}")
- print(f"Status: {conversation['status']}")
- ```
-</Accordion>
-
-<Accordion title="TypeScript/JavaScript (with fetch)">
- ```typescript
- const apiKey = "YOUR_API_KEY";
- const url = "https://app.all-hands.dev/api/conversations";
-
- const headers = {
- "Authorization": `Bearer ${apiKey}`,
- "Content-Type": "application/json"
- };
-
- const data = {
- initial_user_msg: "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
- repository: "yourusername/your-repo"
- };
-
- async function startConversation() {
- try {
- const response = await fetch(url, {
- method: "POST",
- headers: headers,
- body: JSON.stringify(data)
- });
-
- const conversation = await response.json();
-
- console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversation.id}`);
- console.log(`Status: ${conversation.status}`);
-
- return conversation;
- } catch (error) {
- console.error("Error starting conversation:", error);
+ };
+
+ const data = {
+ initial_user_msg: "Check whether there is any incorrect information in the README.md file and send a PR to fix it if so.",
+ repository: "yourusername/your-repo"
+ };
+
+ async function startConversation() {
+ try {
+ const response = await fetch(url, {
+ method: "POST",
+ headers: headers,
+ body: JSON.stringify(data)
+ });
+
+ const conversation = await response.json();
+
+ console.log(`Conversation Link: https://app.all-hands.dev/conversations/${conversation.id}`);
+ console.log(`Status: ${conversation.status}`);
+
+ return conversation;
+ } catch (error) {
+ console.error("Error starting conversation:", error);
+ }
}
- }
- startConversation();
- ```
-</Accordion>
+ startConversation();
+ ```
+ </Tab>
+</Tabs>
#### Response
@@ -125,42 +116,6 @@ You may receive an `AuthenticationError` if:
- You provided the wrong repository name.
- You don't have access to the repository.
-
-### Retrieving Conversation Status
-
-You can check the status of a conversation by making a GET request to the conversation endpoint.
-
-#### Endpoint
-
-```
-GET https://app.all-hands.dev/api/conversations/{conversation_id}
-```
-
-#### Example
-
-<Accordion title="cURL">
- ```bash
- curl -X GET "https://app.all-hands.dev/api/conversations/{conversation_id}" \
- -H "Authorization: Bearer YOUR_API_KEY"
- ```
-</Accordion>
-
-#### Response
-
-The response is formatted as follows:
-
-```json
-{
- "conversation_id":"abc1234",
- "title":"Update README.md",
- "created_at":"2025-04-29T15:13:51.370706Z",
- "last_updated_at":"2025-04-29T15:13:57.199210Z",
- "status":"RUNNING",
- "selected_repository":"yourusername/your-repo",
- "trigger":"gui"
-}
-```
-
## Rate Limits
If you have too many conversations running at once, older conversations will be paused to limit the number of concurrent conversations.
diff --git a/docs/usage/cloud/pro-subscription.mdx b/docs/usage/cloud/pro-subscription.mdx
index 1c75e1652c..65dfe64b91 100644
--- a/docs/usage/cloud/pro-subscription.mdx
+++ b/docs/usage/cloud/pro-subscription.mdx
@@ -1,8 +1,10 @@
---
title: "Pro Subscription"
-description: "Learn about OpenHands Cloud Pro Subscription features and pricing"
+description: "Learn about OpenHands Cloud Pro Subscription features and pricing."
---
+## Overview
+
The OpenHands Pro Subscription unlocks additional features and better pricing when you run OpenHands conversations in
OpenHands Cloud.
@@ -11,13 +13,13 @@ OpenHands Cloud.
All users start on the Pay-as-you-go plan and have access to these base features when they sign up:
* **Run multiple OpenHands conversations on OpenHands Cloud runtimes.**
-* **API keys to the OpenHands LLM provider for use in OpenHands CLI or when running OpenHands on your own**
+* **API keys to the OpenHands LLM provider for use in OpenHands CLI or when running OpenHands on your own.**
* **$20 in initial OpenHands Cloud credits to get started.**
* **Support for GitHub, GitLab, Bitbucket, Slack, and more.**
## What you get with a Pro Subscription
-The $20/month Pro Subscription covers the cost of runtime compute in OpenHands Cloud, plus enables the following
+The $20/month Pro subscription covers the cost of runtime compute in OpenHands Cloud, plus enables the following
features:
* **Bring Your Own LLM Keys:** Bring your own API keys from OpenAI, Anthropic, Mistral, and other providers.
diff --git a/docs/usage/faqs.mdx b/docs/usage/faqs.mdx
index 08bcb81c91..0888994d42 100644
--- a/docs/usage/faqs.mdx
+++ b/docs/usage/faqs.mdx
@@ -90,7 +90,6 @@ If you would like to set things up more systematically, you can:
others have encountered the same problem.
2. **Join our community**: Get help from other users and developers:
- [Slack community](https://dub.sh/openhands)
- - [Discord server](https://discord.gg/ESHStjSjD4)
3. **Check our troubleshooting guide**: Common issues and solutions are documented in
[Troubleshooting](/usage/troubleshooting/troubleshooting).
4. **Report bugs**: If you've found a bug, please [create an issue](https://github.com/All-Hands-AI/OpenHands/issues/new)
diff --git a/docs/usage/installation.mdx b/docs/usage/installation.mdx
index 5ade8323e0..3f755f6f13 100644
--- a/docs/usage/installation.mdx
+++ b/docs/usage/installation.mdx
@@ -4,16 +4,17 @@ description: Running OpenHands Cloud or running on your own.
icon: rocket
---
-## OpenHands Cloud
+<Tabs>
+ <Tab title="OpenHands Cloud">
+ The easiest way to get started with OpenHands is on OpenHands Cloud, which comes with $20 in free credits for new users.
-The easiest way to get started with OpenHands is on OpenHands Cloud, which comes with $20 in free credits for new users.
+ To get started with OpenHands Cloud, visit [app.all-hands.dev](https://app.all-hands.dev).
-To get started with OpenHands Cloud, visit [app.all-hands.dev](https://app.all-hands.dev).
+ For more information see [getting started with OpenHands Cloud.](/usage/cloud/openhands-cloud)
+ </Tab>
+ <Tab title="Running OpenHands on Your Own">
+ Run OpenHands on your local system and bring your own LLM and API key.
-For more information see [getting started with OpenHands Cloud.](/usage/cloud/openhands-cloud)
-
-## Running OpenHands on Your Own
-
-Run OpenHands on your local system and bring your own LLM and API key.
-
-For more information see [running OpenHands on your own.](/usage/local-setup)
+ For more information see [running OpenHands on your own.](/usage/local-setup)
+ </Tab>
+</Tabs>
diff --git a/docs/usage/llms/local-llms.mdx b/docs/usage/llms/local-llms.mdx
index a87d49aa20..97a5cc2e17 100644
--- a/docs/usage/llms/local-llms.mdx
+++ b/docs/usage/llms/local-llms.mdx
@@ -119,7 +119,7 @@ When started for the first time, OpenHands will prompt you to set up the LLM pro
That's it! You can now start using OpenHands with the local LLM server.
-If you encounter any issues, let us know on [Slack](https://dub.sh/openhands) or [Discord](https://discord.gg/ESHStjSjD4).
+If you encounter any issues, let us know on [Slack](https://dub.sh/openhands).
## Advanced: Alternative LLM Backends
diff --git a/docs/usage/settings/mcp-settings.mdx b/docs/usage/settings/mcp-settings.mdx
index 840c20f9f4..a556867714 100644
--- a/docs/usage/settings/mcp-settings.mdx
+++ b/docs/usage/settings/mcp-settings.mdx
@@ -41,71 +41,71 @@ MCP configuration can be defined in:
### Configuration Options
-#### SSE Servers
-
-SSE servers are configured using either a string URL or an object with the following properties:
-
-- `url` (required)
- - Type: `str`
- - Description: The URL of the SSE server.
-
-- `api_key` (optional)
- - Type: `str`
- - Description: API key for authentication.
-
-#### SHTTP Servers
-
-SHTTP (Streamable HTTP) servers are configured using either a string URL or an object with the following properties:
-
-- `url` (required)
- - Type: `str`
- - Description: The URL of the SHTTP server.
-
-- `api_key` (optional)
- - Type: `str`
- - Description: API key for authentication.
-
-- `timeout` (optional)
- - Type: `int`
- - Default: `60`
- - Range: `1-3600` seconds (1 hour maximum)
- - Description: Timeout in seconds for tool execution. This prevents tool calls from hanging indefinitely.
- - **Use Cases:**
- - **Short timeout (1-30s)**: For lightweight operations like status checks or simple queries.
- - **Medium timeout (30-300s)**: For standard processing tasks like data analysis or API calls.
- - **Long timeout (300-3600s)**: For heavy operations like file processing, complex calculations, or batch operations.
- <Note>
- This timeout only applies to individual tool calls, not server connection establishment.
- </Note>
-
-#### Stdio Servers
-
-<Note>
- While stdio servers are supported, [we recommend using MCP proxies](/usage/settings/mcp-settings#configuration-examples) for
- better reliability and performance.
-</Note>
-
-Stdio servers are configured using an object with the following properties:
-
-- `name` (required)
- - Type: `str`
- - Description: A unique name for the server.
-
-- `command` (required)
- - Type: `str`
- - Description: The command to run the server.
-
-- `args` (optional)
- - Type: `list of str`
- - Default: `[]`
- - Description: Command-line arguments to pass to the server.
-
-- `env` (optional)
- - Type: `dict of str to str`
- - Default: `{}`
- - Description: Environment variables to set for the server process.
-
-##### When to Use Direct Stdio
+<Tabs>
+ <Tab title="SSE Servers">
+ SSE servers are configured using either a string URL or an object with the following properties:
+
+ - `url` (required)
+ - Type: `str`
+ - Description: The URL of the SSE server.
+
+ - `api_key` (optional)
+ - Type: `str`
+ - Description: API key for authentication.
+ </Tab>
+ <Tab title="SHTTP Servers">
+ SHTTP (Streamable HTTP) servers are configured using either a string URL or an object with the following properties:
+
+ - `url` (required)
+ - Type: `str`
+ - Description: The URL of the SHTTP server.
+
+ - `api_key` (optional)
+ - Type: `str`
+ - Description: API key for authentication.
+
+ - `timeout` (optional)
+ - Type: `int`
+ - Default: `60`
+ - Range: `1-3600` seconds (1 hour maximum)
+ - Description: Timeout in seconds for tool execution. This prevents tool calls from hanging indefinitely.
+ - **Use Cases:**
+ - **Short timeout (1-30s)**: For lightweight operations like status checks or simple queries.
+ - **Medium timeout (30-300s)**: For standard processing tasks like data analysis or API calls.
+ - **Long timeout (300-3600s)**: For heavy operations like file processing, complex calculations, or batch operations.
+ <Note>
+ This timeout only applies to individual tool calls, not server connection establishment.
+ </Note>
+ </Tab>
+ <Tab title="Stdio Servers">
+ <Note>
+ While stdio servers are supported, [we recommend using MCP proxies](/usage/settings/mcp-settings#configuration-examples) for
+ better reliability and performance.
+ </Note>
+
+ Stdio servers are configured using an object with the following properties:
+
+ - `name` (required)
+ - Type: `str`
+ - Description: A unique name for the server.
+
+ - `command` (required)
+ - Type: `str`
+ - Description: The command to run the server.
+
+ - `args` (optional)
+ - Type: `list of str`
+ - Default: `[]`
+ - Description: Command-line arguments to pass to the server.
+
+ - `env` (optional)
+ - Type: `dict of str to str`
+ - Default: `{}`
+ - Description: Environment variables to set for the server process.
+ </Tab>
+</Tabs>
+
+#### When to Use Direct Stdio
Direct stdio connections may still be appropriate in these scenarios:
- **Development and testing**: Quick prototyping of MCP servers.
@@ -114,76 +114,78 @@ Direct stdio connections may still be appropriate in these scenarios:
### Configuration Examples
-#### Recommended: Using Proxy Servers (SSE/HTTP)
-
-For stdio-based MCP servers, we recommend using MCP proxy tools like
-[`supergateway`](https://github.com/supercorp-ai/supergateway) instead of direct stdio connections.
-[SuperGateway](https://github.com/supercorp-ai/supergateway) is a popular MCP proxy that converts stdio MCP servers to
-HTTP/SSE endpoints.
-
-Start the proxy servers separately:
-```bash
-# Terminal 1: Filesystem server proxy
-supergateway --stdio "npx @modelcontextprotocol/server-filesystem /" --port 8080
-
-# Terminal 2: Fetch server proxy
-supergateway --stdio "uvx mcp-server-fetch" --port 8081
-```
-
-Then configure OpenHands to use the HTTP endpoint:
-
-```toml
-[mcp]
-# SSE Servers - Recommended approach using proxy tools
-sse_servers = [
- # Basic SSE server with just a URL
- "http://example.com:8080/mcp",
-
- # SuperGateway proxy for fetch server
- "http://localhost:8081/sse",
-
- # External MCP service with authentication
- {url="https://api.example.com/mcp/sse", api_key="your-api-key"}
-]
-
-# SHTTP Servers - Modern streamable HTTP transport (recommended)
-shttp_servers = [
- # Basic SHTTP server with default 60s timeout
- "https://api.example.com/mcp/shttp",
-
- # Server with custom timeout for heavy operations
- {
- url = "https://files.example.com/mcp/shttp",
- api_key = "your-api-key",
- timeout = 1800 # 30 minutes for large file processing
- }
-]
-```
-
-#### Alternative: Direct Stdio Servers (Not Recommended for Production)
-
-```toml
-[mcp]
-# Direct stdio servers - use only for development/testing
-stdio_servers = [
- # Basic stdio server
- {name="fetch", command="uvx", args=["mcp-server-fetch"]},
-
- # Stdio server with environment variables
- {
- name="filesystem",
- command="npx",
- args=["@modelcontextprotocol/server-filesystem", "/"],
- env={
- "DEBUG": "true"
+<Tabs>
+ <Tab title="Proxy Servers (SSE/HTTP) - Recommended">
+ For stdio-based MCP servers, we recommend using MCP proxy tools like
+ [`supergateway`](https://github.com/supercorp-ai/supergateway) instead of direct stdio connections.
+ [SuperGateway](https://github.com/supercorp-ai/supergateway) is a popular MCP proxy that converts stdio MCP servers to
+ HTTP/SSE endpoints.
+
+ Start the proxy servers separately:
+ ```bash
+ # Terminal 1: Filesystem server proxy
+ supergateway --stdio "npx @modelcontextprotocol/server-filesystem /" --port 8080
+
+ # Terminal 2: Fetch server proxy
+ supergateway --stdio "uvx mcp-server-fetch" --port 8081
+ ```
+
+ Then configure OpenHands to use the HTTP endpoint:
+
+ ```toml
+ [mcp]
+ # SSE Servers - Recommended approach using proxy tools
+ sse_servers = [
+ # Basic SSE server with just a URL
+ "http://example.com:8080/mcp",
+
+ # SuperGateway proxy for fetch server
+ "http://localhost:8081/sse",
+
+ # External MCP service with authentication
+ {url="https://api.example.com/mcp/sse", api_key="your-api-key"}
+ ]
+
+ # SHTTP Servers - Modern streamable HTTP transport (recommended)
+ shttp_servers = [
+ # Basic SHTTP server with default 60s timeout
+ "https://api.example.com/mcp/shttp",
+
+ # Server with custom timeout for heavy operations
+ {
+ url = "https://files.example.com/mcp/shttp",
+ api_key = "your-api-key",
+ timeout = 1800 # 30 minutes for large file processing
}
- }
-]
-```
-
-For production use, we recommend using proxy tools like SuperGateway.
+ ]
+ ```
+ </Tab>
+ <Tab title="Direct Stdio Servers">
+ <Note>
+ This setup is not Recommended for production.
+ </Note>
+ ```toml
+ [mcp]
+ # Direct stdio servers - use only for development/testing
+ stdio_servers = [
+ # Basic stdio server
+ {name="fetch", command="uvx", args=["mcp-server-fetch"]},
+
+ # Stdio server with environment variables
+ {
+ name="filesystem",
+ command="npx",
+ args=["@modelcontextprotocol/server-filesystem", "/"],
+ env={
+ "DEBUG": "true"
+ }
+ }
+ ]
+ ```
-### Other Proxy Tools
+ For production use, we recommend using proxy tools like SuperGateway.
+ </Tab>
+</Tabs>
Other options include: