diff --git a/README.md b/README.md
index 770a927b..1ffaace3 100644
--- a/README.md
+++ b/README.md
@@ -4,9 +4,10 @@ This repository aggregates documentation from multiple All Hands AI repositories
## Structure
-- `docs.json` - Mintlify configuration file that references docs in these repos
-- `.github/workflows/` - GitHub Actions for automatic `docs` updates
-- `docs/` Folders synced from other repos, e.g., `openhands/`, `agent-sdk/`
+- `docs.json` - Mintlify configuration file that references docs in these repos.
+- `openhands/` - Main OpenHands docs.
+- `sdk/` - Agent SDK docs.
+- `success-stories/` - Success stories docs.
## Adding New Documentation Sources
@@ -14,8 +15,6 @@ To add documentation from a new repository:
1. Add workflow [like this](https://github.com/All-Hands-AI/agent-sdk/blob/main/.github/workflows/deploy-docs.yml) to the new repo.
2. Update `docs.json` to include navigation for the new content (e.g., `new-repo/docs/`)
-3. Commit the changes and manually trigger the [update-docs workflow](.github/workflows/update-docs.yml)
-
## Local Development
diff --git a/docs.json b/docs.json
index a0236462..dbca50b5 100644
--- a/docs.json
+++ b/docs.json
@@ -22,15 +22,16 @@
{
"tab": "Docs",
"pages": [
- "index",
- "openhands/usage/installation",
- "openhands/usage/getting-started",
+ "openhands/usage/introduction",
+ "openhands/usage/quick-start",
+ "openhands/usage/start-building",
"openhands/usage/key-features",
"openhands/usage/faqs",
{
"group": "OpenHands Cloud",
"pages": [
"openhands/usage/cloud/openhands-cloud",
+ "openhands/usage/cloud/pro-subscription",
{
"group": "Integrations",
"pages": [
@@ -56,11 +57,11 @@
{
"group": "Run OpenHands on Your Own",
"pages": [
- "openhands/usage/local-setup",
- "openhands/usage/how-to/gui-mode",
- "openhands/usage/how-to/cli-mode",
- "openhands/usage/how-to/headless-mode",
- "openhands/usage/how-to/github-action",
+ "openhands/usage/run-openhands/local-setup",
+ "openhands/usage/run-openhands/gui-mode",
+ "openhands/usage/run-openhands/cli-mode",
+ "openhands/usage/run-openhands/headless-mode",
+ "openhands/usage/run-openhands/github-action",
{
"group": "Advanced Configuration",
"pages": [
@@ -107,10 +108,9 @@
}
]
},
- "openhands/usage/configuration-options",
- "openhands/usage/how-to/custom-sandbox-guide",
- "openhands/usage/search-engine-setup",
- "openhands/usage/mcp"
+ "openhands/usage/advanced/configuration-options",
+ "openhands/usage/advanced/custom-sandbox-guide",
+ "openhands/usage/advanced/search-engine-setup"
]
}
]
@@ -118,16 +118,22 @@
{
"group": "Customizations & Settings",
"pages": [
- "openhands/usage/common-settings",
- "openhands/usage/prompting/repository",
+ {
+ "group": "OpenHands Settings",
+ "pages": [
+ "openhands/usage/settings/secrets-settings",
+ "openhands/usage/settings/mcp-settings"
+ ]
+ },
+ "openhands/usage/customization/repository",
{
"group": "Microagents",
"pages": [
- "openhands/usage/prompting/microagents-overview",
- "openhands/usage/prompting/microagents-repo",
- "openhands/usage/prompting/microagents-keyword",
- "openhands/usage/prompting/microagents-org",
- "openhands/usage/prompting/microagents-public"
+ "openhands/usage/microagents/microagents-overview",
+ "openhands/usage/microagents/microagents-repo",
+ "openhands/usage/microagents/microagents-keyword",
+ "openhands/usage/microagents/microagents-org",
+ "openhands/usage/microagents/microagents-public"
]
}
]
@@ -135,20 +141,20 @@
{
"group": "Tips and Tricks",
"pages": [
- "openhands/usage/prompting/prompting-best-practices"
+ "openhands/usage/tips/prompting-best-practices"
]
},
{
"group": "Troubleshooting & Feedback",
"pages": [
"openhands/usage/troubleshooting/troubleshooting",
- "openhands/usage/feedback"
+ "openhands/usage/troubleshooting/feedback"
]
},
{
"group": "OpenHands Developers",
"pages": [
- "openhands/usage/how-to/development-overview",
+ "openhands/usage/developers/development-overview",
{
"group": "Architecture",
"pages": [
@@ -156,9 +162,9 @@
"openhands/usage/architecture/runtime"
]
},
- "openhands/usage/how-to/debugging",
- "openhands/usage/how-to/evaluation-harness",
- "openhands/usage/how-to/websocket-connection"
+ "openhands/usage/developers/debugging",
+ "openhands/usage/developers/evaluation-harness",
+ "openhands/usage/developers/websocket-connection"
]
}
]
@@ -172,7 +178,7 @@
{
"tab": "Success Stories",
"pages": [
- "openhands/success-stories/index"
+ "success-stories/index"
]
},
{
@@ -215,8 +221,7 @@
"footer": {
"socials": {
"slack": "https://dub.sh/openhands",
- "github": "https://github.com/All-Hands-AI/OpenHands",
- "discord": "https://discord.gg/ESHStjSjD4"
+ "github": "https://github.com/All-Hands-AI/OpenHands"
}
},
"contextual": {
@@ -230,6 +235,29 @@
"redirects": [
{ "source": "/modules/:slug*", "destination": "/:slug*"},
{ "source": "/success-stories/:slug*", "destination": "/openhands/success-stories/:slug*" },
- { "source": "/usage/:slug*", "destination": "/openhands/usage/:slug*"}
+ { "source": "/usage/:slug*", "destination": "/openhands/usage/:slug*"},
+ { "source": "/openhands/usage/configuration-options", "destination": "/openhands/usage/advanced/configuration-options" },
+ { "source": "/openhands/usage/how-to/custom-sandbox-guide", "destination": "/openhands/usage/advanced/custom-sandbox-guide" },
+ { "source": "/openhands/usage/search-engine-setup", "destination": "/openhands/usage/advanced/search-engine-setup" },
+ { "source": "/openhands/usage/prompting/repository", "destination": "/openhands/usage/customization/repository" },
+ { "source": "/openhands/usage/how-to/debugging", "destination": "/openhands/usage/developers/debugging" },
+ { "source": "/openhands/usage/how-to/development-overview", "destination": "/openhands/usage/developers/development-overview" },
+ { "source": "/openhands/usage/how-to/evaluation-harness", "destination": "/openhands/usage/developers/evaluation-harness" },
+ { "source": "/openhands/usage/how-to/websocket-connection", "destination": "/openhands/usage/developers/websocket-connection" },
+ { "source": "/openhands", "destination": "/openhands/usage/introduction" },
+ { "source": "/openhands/usage/prompting/microagents-keyword", "destination": "/openhands/usage/microagents/microagents-keyword" },
+ { "source": "/openhands/usage/prompting/microagents-org", "destination": "/openhands/usage/microagents/microagents-org" },
+ { "source": "/openhands/usage/prompting/microagents-overview", "destination": "/openhands/usage/microagents/microagents-overview" },
+ { "source": "/openhands/usage/prompting/microagents-public", "destination": "/openhands/usage/microagents/microagents-public" },
+ { "source": "/openhands/usage/prompting/microagents-repo", "destination": "/openhands/usage/microagents/microagents-repo" },
+ { "source": "/openhands/usage/installation", "destination": "/openhands/usage/quick-start" },
+ { "source": "/openhands/usage/how-to/cli-mode", "destination": "/openhands/usage/run-openhands/cli-mode" },
+ { "source": "/openhands/usage/how-to/github-action", "destination": "/openhands/usage/run-openhands/github-action" },
+ { "source": "/openhands/usage/how-to/gui-mode", "destination": "/openhands/usage/run-openhands/gui-mode" },
+ { "source": "/openhands/usage/how-to/headless-mode", "destination": "/openhands/usage/run-openhands/headless-mode" },
+ { "source": "/openhands/usage/local-setup", "destination": "/openhands/usage/run-openhands/local-setup" },
+ { "source": "/openhands/usage/getting-started", "destination": "/openhands/usage/start-building" },
+ { "source": "/openhands/usage/prompting/prompting-best-practices", "destination": "/openhands/usage/tips/prompting-best-practices" },
+ { "source": "/openhands/usage/feedback", "destination": "/openhands/usage/troubleshooting/feedback" }
]
}
diff --git a/openhands/usage/configuration-options.mdx b/openhands/usage/advanced/configuration-options.mdx
similarity index 98%
rename from openhands/usage/configuration-options.mdx
rename to openhands/usage/advanced/configuration-options.mdx
index fc3fcdb5..6fb41e51 100644
--- a/openhands/usage/configuration-options.mdx
+++ b/openhands/usage/advanced/configuration-options.mdx
@@ -10,7 +10,7 @@ description: This page outlines all available configuration options for OpenHand
**Looking for Environment Variables?** All configuration options can also be set using environment variables.
- See the [Environment Variables Reference](./environment-variables) for a complete list with examples.
+ See the [Environment Variables Reference](/openhands/usage/environment-variables) for a complete list with examples.
## Location of the `config.toml` File
@@ -157,7 +157,7 @@ All LLM configuration options can be set as environment variables by prefixing w
- `base_url` → `LLM_BASE_URL`
-For development setups, you can also define custom named LLM configurations. See [Custom LLM Configurations](./llms/custom-llm-configs) for details.
+For development setups, you can also define custom named LLM configurations. See [Custom LLM Configurations](/openhands/usage/llms/custom-llm-configs) for details.
**AWS Credentials**
diff --git a/openhands/usage/how-to/custom-sandbox-guide.mdx b/openhands/usage/advanced/custom-sandbox-guide.mdx
similarity index 96%
rename from openhands/usage/how-to/custom-sandbox-guide.mdx
rename to openhands/usage/advanced/custom-sandbox-guide.mdx
index b2380adc..62481621 100644
--- a/openhands/usage/how-to/custom-sandbox-guide.mdx
+++ b/openhands/usage/advanced/custom-sandbox-guide.mdx
@@ -47,7 +47,7 @@ This will produce a new image called `custom-image`, which will be available in
## Using the Docker Command
-When running OpenHands using [the docker command](/usage/local-setup#start-the-app), replace
+When running OpenHands using [the docker command](/usage/run-openhands/local-setup#start-the-app), replace
`-e SANDBOX_RUNTIME_CONTAINER_IMAGE=...` with `-e SANDBOX_BASE_CONTAINER_IMAGE=`:
```commandline
diff --git a/openhands/usage/search-engine-setup.mdx b/openhands/usage/advanced/search-engine-setup.mdx
similarity index 100%
rename from openhands/usage/search-engine-setup.mdx
rename to openhands/usage/advanced/search-engine-setup.mdx
diff --git a/openhands/usage/cloud/bitbucket-installation.mdx b/openhands/usage/cloud/bitbucket-installation.mdx
index 7f6e1559..eeca4753 100644
--- a/openhands/usage/cloud/bitbucket-installation.mdx
+++ b/openhands/usage/cloud/bitbucket-installation.mdx
@@ -6,7 +6,7 @@ description: This guide walks you through the process of installing OpenHands Cl
## Prerequisites
-- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a Bitbucket account](/usage/cloud/openhands-cloud).
+- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a Bitbucket account](/openhands/usage/cloud/openhands-cloud).
## Adding Bitbucket Repository Access
@@ -17,7 +17,7 @@ Upon signing into OpenHands Cloud with a Bitbucket account, OpenHands will have
After signing in with a Bitbucket account, use the `Open Repository` section to select the appropriate repository and
branch you'd like OpenHands to work on. Then click on `Launch` to start the conversation!
-
+
## IP Whitelisting
@@ -45,5 +45,5 @@ OpenHands to access your repositories:
## Next Steps
-- [Learn about the Cloud UI](/usage/cloud/cloud-ui).
-- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.
+- [Learn about the Cloud UI](/openhands/usage/cloud/cloud-ui).
+- [Use the Cloud API](/openhands/usage/cloud/cloud-api) to programmatically interact with OpenHands.
diff --git a/openhands/usage/cloud/cloud-ui.mdx b/openhands/usage/cloud/cloud-ui.mdx
index 4288f749..256110ec 100644
--- a/openhands/usage/cloud/cloud-ui.mdx
+++ b/openhands/usage/cloud/cloud-ui.mdx
@@ -8,9 +8,9 @@ description: The Cloud UI provides a web interface for interacting with OpenHand
The landing page is where you can:
-- [Select a GitHub repo](/usage/cloud/github-installation#working-with-github-repos-in-openhands-cloud),
- [a GitLab repo](/usage/cloud/gitlab-installation#working-with-gitlab-repos-in-openhands-cloud) or
- [a Bitbucket repo](/usage/cloud/bitbucket-installation#working-with-bitbucket-repos-in-openhands-cloud) to start working on.
+- [Select a GitHub repo](/openhands/usage/cloud/github-installation#working-with-github-repos-in-openhands-cloud),
+ [a GitLab repo](/openhands/usage/cloud/gitlab-installation#working-with-gitlab-repos-in-openhands-cloud) or
+ [a Bitbucket repo](/openhands/usage/cloud/bitbucket-installation#working-with-bitbucket-repos-in-openhands-cloud) to start working on.
- Launch an empty conversation using `New Conversation`.
- See `Suggested Tasks` for repositories that OpenHands has access to.
- See your `Recent Conversations`.
@@ -22,33 +22,33 @@ Settings are divided across tabs, with each tab focusing on a specific area of c
- `User`
- Change your email address.
- `Integrations`
- - [Configure GitHub repository access](/usage/cloud/github-installation#modifying-repository-access) for OpenHands.
- - [Install the OpenHands Slack app](/usage/cloud/slack-installation).
+ - [Configure GitHub repository access](/openhands/usage/cloud/github-installation#modifying-repository-access) for OpenHands.
+ - [Install the OpenHands Slack app](/openhands/usage/cloud/slack-installation).
- `Application`
- Set your preferred language, notifications and other preferences.
- Toggle task suggestions on GitHub.
- Toggle Solvability Analysis.
- Set a maximum budget per conversation.
- Configure the username and email that OpenHands uses for commits.
-- `LLM` (Available for [Pro subscription users](/usage/cloud/pro-subscription))
+- `LLM` (Available for [Pro subscription users](/openhands/usage/cloud/pro-subscription))
- Choose to use another LLM or use different models from the OpenHands provider.
- `Billing`
- Add credits for using the OpenHands provider.
- Cancel your `Pro subscription`.
- `Secrets`
- - [Manage secrets](/usage/settings/secrets-settings).
+ - [Manage secrets](/openhands/usage/settings/secrets-settings).
- `API Keys`
- - [Create API keys to work with OpenHands programmatically](/usage/cloud/cloud-api).
+ - [Create API keys to work with OpenHands programmatically](/openhands/usage/cloud/cloud-api).
- `MCP`
- - [Setup an MCP server](/usage/settings/mcp-settings)
+ - [Setup an MCP server](/openhands/usage/settings/mcp-settings)
## Key Features
-For an overview of the key features available inside a conversation, please refer to the [Key Features](/usage/key-features)
+For an overview of the key features available inside a conversation, please refer to the [Key Features](/openhands/usage/key-features)
section of the documentation.
## Next Steps
-- [Install GitHub Integration](/usage/cloud/github-installation) to use OpenHands with your GitHub repositories.
-- [Install GitLab Integration](/usage/cloud/gitlab-installation) to use OpenHands with your GitLab repositories.
-- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.
+- [Install GitHub Integration](/openhands/usage/cloud/github-installation) to use OpenHands with your GitHub repositories.
+- [Install GitLab Integration](/openhands/usage/cloud/gitlab-installation) to use OpenHands with your GitLab repositories.
+- [Use the Cloud API](/openhands/usage/cloud/cloud-api) to programmatically interact with OpenHands.
diff --git a/openhands/usage/cloud/github-installation.mdx b/openhands/usage/cloud/github-installation.mdx
index 68636ead..ce4a5de9 100644
--- a/openhands/usage/cloud/github-installation.mdx
+++ b/openhands/usage/cloud/github-installation.mdx
@@ -6,7 +6,7 @@ description: This guide walks you through the process of installing OpenHands Cl
## Prerequisites
-- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a GitHub account](/usage/cloud/openhands-cloud).
+- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a GitHub account](/openhands/usage/cloud/openhands-cloud).
## Adding GitHub Repository Access
@@ -43,12 +43,12 @@ Once you've granted GitHub repository access, you can start working with your Gi
`Open Repository` section to select the appropriate repository and branch you'd like OpenHands to work on. Then click
on `Launch` to start the conversation!
-
+
## Working on GitHub Issues and Pull Requests Using Openhands
To allow OpenHands to work directly from GitHub directly, you must
-[give OpenHands access to your repository](/usage/cloud/github-installation#modifying-repository-access). Once access is
+[give OpenHands access to your repository](/openhands/usage/cloud/github-installation#modifying-repository-access). Once access is
given, you can use OpenHands by labeling the issue or by tagging `@openhands`.
### Working with Issues
@@ -75,5 +75,5 @@ permissions to access both repositories.
## Next Steps
-- [Learn about the Cloud UI](/usage/cloud/cloud-ui).
-- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.
+- [Learn about the Cloud UI](/openhands/usage/cloud/cloud-ui).
+- [Use the Cloud API](/openhands/usage/cloud/cloud-api) to programmatically interact with OpenHands.
diff --git a/openhands/usage/cloud/gitlab-installation.mdx b/openhands/usage/cloud/gitlab-installation.mdx
index 621d05ef..f1807dcf 100644
--- a/openhands/usage/cloud/gitlab-installation.mdx
+++ b/openhands/usage/cloud/gitlab-installation.mdx
@@ -6,7 +6,7 @@ description: This guide walks you through the process of installing OpenHands Cl
## Prerequisites
-- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a GitLab account](/usage/cloud/openhands-cloud).
+- Signed in to [OpenHands Cloud](https://app.all-hands.dev) with [a GitLab account](/openhands/usage/cloud/openhands-cloud).
## Adding GitLab Repository Access
@@ -17,12 +17,12 @@ Upon signing into OpenHands Cloud with a GitLab account, OpenHands will have acc
After signing in with a Gitlab account, use the `Open Repository` section to select the appropriate repository and
branch you'd like OpenHands to work on. Then click on `Launch` to start the conversation!
-
+
## Using Tokens with Reduced Scopes
OpenHands requests an API-scoped token during OAuth authentication. By default, this token is provided to the agent.
-To restrict the agent's permissions, [you can define a custom secret](/usage/settings/secrets-settings) `GITLAB_TOKEN`,
+To restrict the agent's permissions, [you can define a custom secret](/openhands/usage/settings/secrets-settings) `GITLAB_TOKEN`,
which will override the default token assigned to the agent. While the high-permission API token is still requested
and used for other components of the application (e.g. opening merge requests), the agent will not have access to it.
diff --git a/openhands/usage/cloud/openhands-cloud.mdx b/openhands/usage/cloud/openhands-cloud.mdx
index 6c0e3634..d64fc2fa 100644
--- a/openhands/usage/cloud/openhands-cloud.mdx
+++ b/openhands/usage/cloud/openhands-cloud.mdx
@@ -20,8 +20,8 @@ You'll be prompted to connect with your GitHub, GitLab or Bitbucket account:
Once you've connected your account, you can:
-- [Install GitHub Integration](/usage/cloud/github-installation) to use OpenHands with your GitHub repositories.
-- [Install GitLab Integration](/usage/cloud/gitlab-installation) to use OpenHands with your GitLab repositories.
-- [Install Bitbucket Integration](/usage/cloud/bitbucket-installation) to use OpenHands with your Bitbucket repositories.
-- [Learn about the Cloud UI](/usage/cloud/cloud-ui).
-- [Use the Cloud API](/usage/cloud/cloud-api) to programmatically interact with OpenHands.
+- [Install GitHub Integration](/openhands/usage/cloud/github-installation) to use OpenHands with your GitHub repositories.
+- [Install GitLab Integration](/openhands/usage/cloud/gitlab-installation) to use OpenHands with your GitLab repositories.
+- [Install Bitbucket Integration](/openhands/usage/cloud/bitbucket-installation) to use OpenHands with your Bitbucket repositories.
+- [Learn about the Cloud UI](/openhands/usage/cloud/cloud-ui).
+- [Use the Cloud API](/openhands/usage/cloud/cloud-api) to programmatically interact with OpenHands.
diff --git a/openhands/usage/cloud/pro-subscription.mdx b/openhands/usage/cloud/pro-subscription.mdx
index 65dfe64b..2c4876a6 100644
--- a/openhands/usage/cloud/pro-subscription.mdx
+++ b/openhands/usage/cloud/pro-subscription.mdx
@@ -37,7 +37,7 @@ Here are the key differences between Pay-as-you-go and Pro subscriptions:
| Monthly price | None \- no commitment | $20/month |
| Can I bring my own LLM key? | No | ✅ Yes |
| Do I pay for LLM usage? | ✅ Yes | ✅ Yes |
-| Can I select from different LLMs without bringing my own LLM key? | No \- defaults to Claude Sonnet 4 | ✅ Yes \- via OpenHands LLM provider
[*See models and pricing*](https://docs.all-hands.dev/usage/llms/openhands-llms#pricing) |
+| Can I select from different LLMs without bringing my own LLM key? | No \- defaults to Claude Sonnet 4 | ✅ Yes \- via OpenHands LLM provider
[*See models and pricing*](/openhands/usage/llms/openhands-llms#pricing) |
| How much am I charged for LLM usage? | **Marked up pricing** \- 2x Claude Sonnet 4 API prices. *This markup helps cover the cost of runtime compute.* | **No markup** \- 1x API prices. *The $20 monthly subscription covers the cost of runtime compute.* |
@@ -45,6 +45,6 @@ Here are the key differences between Pay-as-you-go and Pro subscriptions:
The following applies to **both** the Pay-as-you-go and Pro subscription:
| | Pay-as-you-go or Pro Subscription |
| :---- | :---- |
-| Do I have access to multiple models via the OpenHands LLM provider? | ✅ Yes
[*See models and pricing*](https://docs.all-hands.dev/usage/llms/openhands-llms#pricing) |
+| Do I have access to multiple models via the OpenHands LLM provider? | ✅ Yes
[*See models and pricing*](/openhands/usage/llms/openhands-llms#pricing) |
| Can I generate and refresh OpenHands LLM API keys? | ✅ Yes |
-| How much am I charged for LLM usage when I use the OpenHands LLM provider in other AI coding tools? | **No markup** \- pay 1x API prices
[*See models and pricing*](https://docs.all-hands.dev/usage/llms/openhands-llms#pricing)
*Usage is deducted from your OpenHands Cloud credit balance.*
*The OpenHands LLM provider is available to all OpenHands Cloud users, and LLM usage is billed at-cost (zero markup). Use these models with OpenHands CLI, running OpenHands on your own, or even other AI coding agents\! [Learn more.](https://www.all-hands.dev/blog/access-state-of-the-art-llm-models-at-cost-via-openhands-gui-and-cli)* |
+| How much am I charged for LLM usage when I use the OpenHands LLM provider in other AI coding tools? | **No markup** \- pay 1x API prices
[*See models and pricing*](/openhands/usage/llms/openhands-llms#pricing)
*Usage is deducted from your OpenHands Cloud credit balance.*
*The OpenHands LLM provider is available to all OpenHands Cloud users, and LLM usage is billed at-cost (zero markup). Use these models with OpenHands CLI, running OpenHands on your own, or even other AI coding agents\! [Learn more.](https://www.all-hands.dev/blog/access-state-of-the-art-llm-models-at-cost-via-openhands-gui-and-cli)* |
diff --git a/openhands/usage/cloud/project-management/jira-dc-integration.mdx b/openhands/usage/cloud/project-management/jira-dc-integration.mdx
index 1488bbf7..c7ce4c06 100644
--- a/openhands/usage/cloud/project-management/jira-dc-integration.mdx
+++ b/openhands/usage/cloud/project-management/jira-dc-integration.mdx
@@ -109,18 +109,18 @@ Here the workspace name is **jira.all-hands.dev**.
-
+
-
+
-
+
-
+
diff --git a/openhands/usage/cloud/project-management/jira-integration.mdx b/openhands/usage/cloud/project-management/jira-integration.mdx
index 68c3b524..6cdd567d 100644
--- a/openhands/usage/cloud/project-management/jira-integration.mdx
+++ b/openhands/usage/cloud/project-management/jira-integration.mdx
@@ -113,18 +113,18 @@ Here the workspace name is **all-hands**.
-
+
-
+
-
+
-
+
diff --git a/openhands/usage/cloud/project-management/linear-integration.mdx b/openhands/usage/cloud/project-management/linear-integration.mdx
index c01da4ae..4887df50 100644
--- a/openhands/usage/cloud/project-management/linear-integration.mdx
+++ b/openhands/usage/cloud/project-management/linear-integration.mdx
@@ -113,18 +113,18 @@ Here the workspace name is **allhands**.
-
+
-
+
-
+
-
+
diff --git a/openhands/usage/cloud/slack-installation.mdx b/openhands/usage/cloud/slack-installation.mdx
index 50e6d651..8ed86325 100644
--- a/openhands/usage/cloud/slack-installation.mdx
+++ b/openhands/usage/cloud/slack-installation.mdx
@@ -68,13 +68,13 @@ You must be the user who started the conversation.
Conversation is started by mentioning `@openhands`.
-
+
### See agent response and send follow up messages
Initial request is followed up by mentioning `@openhands` in a thread reply.
-
+
## Pro tip
@@ -86,4 +86,4 @@ You can mention a repo name when starting a new conversation in the following fo
The repo match is case insensitive. If a repo name match is made, it will kick off the conversation.
If the repo name partially matches against multiple repos, you'll be asked to select a repo from the filtered list.
-
+
diff --git a/openhands/usage/prompting/repository.mdx b/openhands/usage/customization/repository.mdx
similarity index 91%
rename from openhands/usage/prompting/repository.mdx
rename to openhands/usage/customization/repository.mdx
index 0bb64ee4..60a0ce7f 100644
--- a/openhands/usage/prompting/repository.mdx
+++ b/openhands/usage/customization/repository.mdx
@@ -6,7 +6,7 @@ description: You can customize how OpenHands interacts with your repository by c
## Microagents
Microagents allow you to extend OpenHands prompts with information specific to your project and define how OpenHands
-should function. See [Microagents Overview](../prompting/microagents-overview) for more information.
+should function. See [Microagents Overview](/openhands/usage/microagents/microagents-overview) for more information.
## Setup Script
diff --git a/openhands/usage/how-to/debugging.mdx b/openhands/usage/developers/debugging.mdx
similarity index 100%
rename from openhands/usage/how-to/debugging.mdx
rename to openhands/usage/developers/debugging.mdx
diff --git a/openhands/usage/how-to/development-overview.mdx b/openhands/usage/developers/development-overview.mdx
similarity index 100%
rename from openhands/usage/how-to/development-overview.mdx
rename to openhands/usage/developers/development-overview.mdx
diff --git a/openhands/usage/how-to/evaluation-harness.mdx b/openhands/usage/developers/evaluation-harness.mdx
similarity index 100%
rename from openhands/usage/how-to/evaluation-harness.mdx
rename to openhands/usage/developers/evaluation-harness.mdx
diff --git a/openhands/usage/how-to/websocket-connection.mdx b/openhands/usage/developers/websocket-connection.mdx
similarity index 100%
rename from openhands/usage/how-to/websocket-connection.mdx
rename to openhands/usage/developers/websocket-connection.mdx
diff --git a/openhands/usage/faqs.mdx b/openhands/usage/faqs.mdx
index 0888994d..85b9f75b 100644
--- a/openhands/usage/faqs.mdx
+++ b/openhands/usage/faqs.mdx
@@ -8,12 +8,12 @@ icon: question
### I'm new to OpenHands. Where should I start?
-1. **Quick start**: Use [OpenHands Cloud](/usage/cloud/openhands-cloud) to get started quickly with
- [GitHub](/usage/cloud/github-installation), [GitLab](/usage/cloud/gitlab-installation),
- and [Slack](/usage/cloud/slack-installation) integrations.
-2. **Run on your own**: If you prefer to run it on your own hardware, follow our [Getting Started guide](/usage/local-setup).
-3. **First steps**: Read over the [start building guidelines](/usage/getting-started) and
- [prompting best practices](/usage/prompting/prompting-best-practices) to learn the basics.
+1. **Quick start**: Use [OpenHands Cloud](/openhands/usage/cloud/openhands-cloud) to get started quickly with
+ [GitHub](/openhands/usage/cloud/github-installation), [GitLab](/openhands/usage/cloud/gitlab-installation),
+ and [Slack](/openhands/usage/cloud/slack-installation) integrations.
+2. **Run on your own**: If you prefer to run it on your own hardware, follow our [Getting Started guide](/openhands/usage/run-openhands/local-setup).
+3. **First steps**: Read over the [start building guidelines](/openhands/usage/start-building) and
+ [prompting best practices](/openhands/usage/tips/prompting-best-practices) to learn the basics.
### Can I use OpenHands for production workloads?
@@ -38,7 +38,7 @@ input on our product roadmap.
(called a "sandbox") that is separate from your host system. However, the safety depends on your configuration:
**What's protected:**
-- Your host system files and programs (unless you mount them using [this feature](/usage/runtimes/docker#connecting-to-your-filesystem))
+- Your host system files and programs (unless you mount them using [this feature](/openhands/usage/runtimes/docker#connecting-to-your-filesystem))
- Host system resources
- Other containers and processes
@@ -48,9 +48,9 @@ input on our product roadmap.
- Mounted files and directories can be modified or deleted.
- Network requests can be made to external services.
-For detailed security information, see our [Runtime Architecture](/usage/architecture/runtime),
-[Security Configuration](/usage/configuration-options#security-configuration),
-and [Hardened Docker Installation](/usage/runtimes/docker#hardened-docker-installation) documentation.
+For detailed security information, see our [Runtime Architecture](/openhands/usage/architecture/runtime),
+[Security Configuration](/openhands/usage/advanced/configuration-options#security-configuration),
+and [Hardened Docker Installation](/openhands/usage/runtimes/docker#hardened-docker-installation) documentation.
## File Storage and Access
@@ -63,7 +63,7 @@ Your files are stored in different locations depending on how you've configured
- These files are temporary and will be lost when the container is removed.
- The agent works in the `/workspace` directory inside the runtime container.
-**When you mount your local filesystem (following [this](/usage/runtimes/docker#connecting-to-your-filesystem)):**
+**When you mount your local filesystem (following [this](/openhands/usage/runtimes/docker#connecting-to-your-filesystem)):**
- Your local files are mounted into the container's `/workspace` directory.
- Changes made by the agent are reflected in your local filesystem.
- Files persist after the container is stopped.
@@ -80,9 +80,9 @@ OpenHands comes with a basic runtime environment that includes Python and Node.j
It also has the ability to install any tools it needs, so usually it's sufficient to ask it to set up its environment.
If you would like to set things up more systematically, you can:
-- **Use setup.sh**: Add a [setup.sh file](/usage/prompting/repository#setup-script) file to
+- **Use setup.sh**: Add a [setup.sh file](/openhands/usage/customization/repository#setup-script) file to
your repository, which will be run every time the agent starts.
-- **Use a custom sandbox**: Use a [custom docker image](/usage/how-to/custom-sandbox-guide) to initialize the sandbox.
+- **Use a custom sandbox**: Use a [custom docker image](/openhands/usage/advanced/custom-sandbox-guide) to initialize the sandbox.
### Something's not working. Where can I get help?
@@ -91,6 +91,6 @@ If you would like to set things up more systematically, you can:
2. **Join our community**: Get help from other users and developers:
- [Slack community](https://dub.sh/openhands)
3. **Check our troubleshooting guide**: Common issues and solutions are documented in
- [Troubleshooting](/usage/troubleshooting/troubleshooting).
+ [Troubleshooting](/openhands/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)
and fill in as much detail as possible.
diff --git a/openhands/index.mdx b/openhands/usage/introduction.mdx
similarity index 100%
rename from openhands/index.mdx
rename to openhands/usage/introduction.mdx
diff --git a/openhands/usage/key-features.mdx b/openhands/usage/key-features.mdx
index 488a3930..e0bcb8ee 100644
--- a/openhands/usage/key-features.mdx
+++ b/openhands/usage/key-features.mdx
@@ -3,7 +3,7 @@ title: Key Features
icon: bars
---
-
+
### Chat Panel
- Displays the conversation between the user and OpenHands.
diff --git a/openhands/usage/llms/azure-llms.mdx b/openhands/usage/llms/azure-llms.mdx
index d1dbb310..e5740128 100644
--- a/openhands/usage/llms/azure-llms.mdx
+++ b/openhands/usage/llms/azure-llms.mdx
@@ -6,7 +6,7 @@ description: OpenHands uses LiteLLM to make calls to Azure's chat models. You ca
## Azure OpenAI Configuration
When running OpenHands, you'll need to set the following environment variable using `-e` in the
-[docker run command](../installation#running-openhands):
+docker run command:
```
LLM_API_VERSION="" # e.g. "2023-05-15"
@@ -35,7 +35,7 @@ You will need your ChatGPT deployment name which can be found on the deployments
### Azure OpenAI Configuration
When running OpenHands, set the following environment variable using `-e` in the
-[docker run command](../installation#running-openhands):
+docker run command:
```
LLM_API_VERSION="" # e.g. "2024-02-15-preview"
diff --git a/openhands/usage/llms/custom-llm-configs.mdx b/openhands/usage/llms/custom-llm-configs.mdx
index 2a7af468..297d3612 100644
--- a/openhands/usage/llms/custom-llm-configs.mdx
+++ b/openhands/usage/llms/custom-llm-configs.mdx
@@ -57,7 +57,7 @@ Each named LLM configuration supports all the same options as the default LLM co
- Token limits (`max_input_tokens`, `max_output_tokens`)
- And all other LLM configuration options
-For a complete list of available options, see the LLM Configuration section in the [Configuration Options](../configuration-options) documentation.
+For a complete list of available options, see the LLM Configuration section in the [Configuration Options](/openhands/usage/advanced/configuration-options) documentation.
## Use Cases
diff --git a/openhands/usage/llms/google-llms.mdx b/openhands/usage/llms/google-llms.mdx
index d71c3151..6b789888 100644
--- a/openhands/usage/llms/google-llms.mdx
+++ b/openhands/usage/llms/google-llms.mdx
@@ -15,7 +15,7 @@ If the model is not in the list, enable `Advanced` options, and enter it in `Cus
## VertexAI - Google Cloud Platform Configs
To use Vertex AI through Google Cloud Platform when running OpenHands, you'll need to set the following environment
-variables using `-e` in the [docker run command](../installation#running-openhands):
+variables using `-e` in the docker run command:
```
GOOGLE_APPLICATION_CREDENTIALS=""
diff --git a/openhands/usage/llms/llms.mdx b/openhands/usage/llms/llms.mdx
index 19357a65..7989b528 100644
--- a/openhands/usage/llms/llms.mdx
+++ b/openhands/usage/llms/llms.mdx
@@ -74,15 +74,15 @@ using `-e`:
We have a few guides for running OpenHands with specific model providers:
-- [Azure](/usage/llms/azure-llms)
-- [Google](/usage/llms/google-llms)
-- [Groq](/usage/llms/groq)
-- [Local LLMs with SGLang or vLLM](/usage/llms/local-llms)
-- [LiteLLM Proxy](/usage/llms/litellm-proxy)
-- [Moonshot AI](/usage/llms/moonshot)
-- [OpenAI](/usage/llms/openai-llms)
-- [OpenHands](/usage/llms/openhands-llms)
-- [OpenRouter](/usage/llms/openrouter)
+- [Azure](/openhands/usage/llms/azure-llms)
+- [Google](/openhands/usage/llms/google-llms)
+- [Groq](/openhands/usage/llms/groq)
+- [Local LLMs with SGLang or vLLM](/openhands/usage/llms/local-llms)
+- [LiteLLM Proxy](/openhands/usage/llms/litellm-proxy)
+- [Moonshot AI](/openhands/usage/llms/moonshot)
+- [OpenAI](/openhands/usage/llms/openai-llms)
+- [OpenHands](/openhands/usage/llms/openhands-llms)
+- [OpenRouter](/openhands/usage/llms/openrouter)
## Model Customization
@@ -92,7 +92,7 @@ LLM providers have specific settings that can be customized to optimize their pe
- **Native Tool Calling**: Toggle native function/tool calling capabilities.
For detailed information about model customization, see
-[LLM Configuration Options](/usage/configuration-options#llm-configuration).
+[LLM Configuration Options](/openhands/usage/advanced/configuration-options#llm-configuration).
### API retries and rate limits
diff --git a/openhands/usage/llms/local-llms.mdx b/openhands/usage/llms/local-llms.mdx
index 97a5cc2e..7404158d 100644
--- a/openhands/usage/llms/local-llms.mdx
+++ b/openhands/usage/llms/local-llms.mdx
@@ -65,7 +65,7 @@ Download and install the LM Studio desktop app from [lmstudio.ai](https://lmstud
### 5. Start OpenHands
-1. Check [the installation guide](/usage/local-setup) and ensure all prerequisites are met before running OpenHands, then run:
+1. Check [the installation guide](/openhands/usage/run-openhands/local-setup) and ensure all prerequisites are met before running OpenHands, then run:
```bash
docker pull docker.all-hands.dev/all-hands-ai/runtime:0.58-nikolaik
@@ -200,7 +200,7 @@ vllm serve mistralai/Devstral-Small-2505 \
#### Using Docker
-Run OpenHands using [the official docker run command](../installation#start-the-app).
+Run OpenHands using [the official docker run command](/openhands/usage/run-openhands/local-setup).
#### Using Development Mode
diff --git a/openhands/usage/llms/openhands-llms.mdx b/openhands/usage/llms/openhands-llms.mdx
index ce151374..895f7192 100644
--- a/openhands/usage/llms/openhands-llms.mdx
+++ b/openhands/usage/llms/openhands-llms.mdx
@@ -5,11 +5,11 @@ description: OpenHands LLM provider with access to state-of-the-art (SOTA) agent
## Obtain Your OpenHands LLM API Key
-1. [Log in to OpenHands Cloud](/usage/cloud/openhands-cloud).
+1. [Log in to OpenHands Cloud](/openhands/usage/cloud/openhands-cloud).
2. Go to the Settings page and navigate to the `API Keys` tab.
3. Copy your `LLM API Key`.
-
+
## Configuration
@@ -20,13 +20,13 @@ When running OpenHands, you'll need to set the following in the OpenHands UI thr
## Using OpenHands LLM Provider in the CLI
-1. [Run OpenHands CLI](/usage/how-to/cli-mode).
+1. [Run OpenHands CLI](/openhands/usage/run-openhands/cli-mode).
2. To select OpenHands as the LLM provider:
- If this is your first time running the CLI, choose `openhands` and then select the model that you would like to use.
- If you have previously run the CLI, run the `/settings` command and select to modify the `Basic` settings. Then
choose `openhands` and finally the model.
-
+
## Pricing
diff --git a/openhands/usage/prompting/microagents-keyword.mdx b/openhands/usage/microagents/microagents-keyword.mdx
similarity index 100%
rename from openhands/usage/prompting/microagents-keyword.mdx
rename to openhands/usage/microagents/microagents-keyword.mdx
diff --git a/openhands/usage/prompting/microagents-org.mdx b/openhands/usage/microagents/microagents-org.mdx
similarity index 92%
rename from openhands/usage/prompting/microagents-org.mdx
rename to openhands/usage/microagents/microagents-org.mdx
index 8a439b77..a851dbfb 100644
--- a/openhands/usage/prompting/microagents-org.mdx
+++ b/openhands/usage/microagents/microagents-org.mdx
@@ -5,7 +5,7 @@ description: Organizations and users can define microagents that apply to all re
## Usage
-These microagents can be [any type of microagent](./microagents-overview#microagent-types) and will be loaded
+These microagents can be [any type of microagent](/openhands/usage/microagents/microagents-overview#microagent-types) and will be loaded
accordingly. However, they are applied to all repositories belonging to the organization or user.
Add a `.openhands` repository under the organization or user and create a `microagents` directory and place the
diff --git a/openhands/usage/prompting/microagents-overview.mdx b/openhands/usage/microagents/microagents-overview.mdx
similarity index 81%
rename from openhands/usage/prompting/microagents-overview.mdx
rename to openhands/usage/microagents/microagents-overview.mdx
index abc13c2b..1a9d5bc3 100644
--- a/openhands/usage/prompting/microagents-overview.mdx
+++ b/openhands/usage/microagents/microagents-overview.mdx
@@ -7,11 +7,11 @@ description: Microagents are specialized prompts that enhance OpenHands with dom
Currently OpenHands supports the following types of microagents:
-- [General Microagents](./microagents-repo): General guidelines for OpenHands about the repository.
-- [Keyword-Triggered Microagents](./microagents-keyword): Guidelines activated by specific keywords in prompts.
+- [General Microagents](/openhands/usage/microagents/microagents-repo): General guidelines for OpenHands about the repository.
+- [Keyword-Triggered Microagents](/openhands/usage/microagents/microagents-keyword): Guidelines activated by specific keywords in prompts.
To customize OpenHands' behavior, create a .openhands/microagents/ directory in the root of your repository and
-add `.md` files inside. For repository-specific guidelines, you can ask OpenHands to analyze your repository and create a comprehensive `repo.md` file (see [General Microagents](./microagents-repo) for details).
+add `.md` files inside. For repository-specific guidelines, you can ask OpenHands to analyze your repository and create a comprehensive `repo.md` file (see [General Microagents](/openhands/usage/microagents/microagents-repo) for details).
Loaded microagents take up space in the context window.
diff --git a/openhands/usage/prompting/microagents-public.mdx b/openhands/usage/microagents/microagents-public.mdx
similarity index 88%
rename from openhands/usage/prompting/microagents-public.mdx
rename to openhands/usage/microagents/microagents-public.mdx
index c1e2ca7a..b67098b2 100644
--- a/openhands/usage/prompting/microagents-public.mdx
+++ b/openhands/usage/microagents/microagents-public.mdx
@@ -1,6 +1,6 @@
---
title: Global Microagents
-description: Global microagents are [keyword-triggered microagents](./microagents-keyword) that apply to all OpenHands users. A list of the current global microagents can be found [in the OpenHands repository](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents).
+description: Global microagents are [keyword-triggered microagents](/openhands/usage/microagents/microagents-keyword) that apply to all OpenHands users. A list of the current global microagents can be found [in the OpenHands repository](https://github.com/All-Hands-AI/OpenHands/tree/main/microagents).
---
## Contributing a Global Microagent
diff --git a/openhands/usage/prompting/microagents-repo.mdx b/openhands/usage/microagents/microagents-repo.mdx
similarity index 100%
rename from openhands/usage/prompting/microagents-repo.mdx
rename to openhands/usage/microagents/microagents-repo.mdx
diff --git a/openhands/usage/installation.mdx b/openhands/usage/quick-start.mdx
similarity index 79%
rename from openhands/usage/installation.mdx
rename to openhands/usage/quick-start.mdx
index 3f755f6f..196ae5a3 100644
--- a/openhands/usage/installation.mdx
+++ b/openhands/usage/quick-start.mdx
@@ -10,11 +10,11 @@ icon: rocket
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)
+ For more information see [getting started with OpenHands Cloud.](/openhands/usage/cloud/openhands-cloud)
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.](/openhands/usage/run-openhands/local-setup)
diff --git a/openhands/usage/how-to/cli-mode.mdx b/openhands/usage/run-openhands/cli-mode.mdx
similarity index 92%
rename from openhands/usage/how-to/cli-mode.mdx
rename to openhands/usage/run-openhands/cli-mode.mdx
index 6ad9e89a..8c235ab4 100644
--- a/openhands/usage/how-to/cli-mode.mdx
+++ b/openhands/usage/run-openhands/cli-mode.mdx
@@ -4,7 +4,7 @@ description: The Command-Line Interface (CLI) provides a powerful interface that
directly from your terminal.
---
-This mode is different from the [headless mode](/usage/how-to/headless-mode), which is non-interactive and better
+This mode is different from the [headless mode](/openhands/usage/run-openhands/headless-mode), which is non-interactive and better
for scripting.