OpenHands · ak684 · Aug 24, 2026 · Aug 24, 2026
diff --git a/docs.json b/docs.json
@@ -524,7 +524,8 @@
               "enterprise/quick-start",
               "enterprise/custom-sandbox-image",
               "enterprise/docker-in-sandbox",
-              "enterprise/external-postgres"
+              "enterprise/external-postgres",
+              "enterprise/troubleshooting"
             ]
           },
           {

diff --git a/enterprise/k8s-install/installation.mdx b/enterprise/k8s-install/installation.mdx
@@ -29,7 +29,7 @@
  `app.openhands.example.com` (application), `auth.openhands.example.com`
  (login), `runtime-api.openhands.example.com`, and
  `<id>-runtime.openhands.example.com` for the per-session sandboxes. Every
  hostname sits one label under the base domain, so a single **wildcard**
  record `*.openhands.example.com` pointing at your cluster's ingress covers
  all of them; see [DNS and TLS](/enterprise/k8s-install/dns-and-tls).
 - A **wildcard TLS certificate** for `*.openhands.example.com`, which you provide.
@@ -47,12 +47,12 @@
  --password <your-license-id>
 ```

 ## Step 2: Create the namespaces and secrets

 We recommend running agent sandboxes in a namespace separate from the
 application. Sandboxes run agent-authored code, so a dedicated namespace keeps
 them isolated from the application, database, and secrets. Create both
 namespaces now:

 ```bash
 kubectl create namespace openhands
@@ -60,7 +60,7 @@
 ```

 The chart references several Kubernetes secrets that you create ahead of
 installation, all in the `openhands` namespace:

 ```bash
 kubectl -n openhands create secret generic jwt-secret \
@@ -144,7 +144,7 @@
  data.
 </Warning>

 The example below uses Traefik, the chart's default ingress class; set
 `ingress.class` and the annotations to match your controller.

 ```yaml
@@ -256,7 +256,7 @@
 ```

 <Tip>
  The `preflight` and `support-bundle` CLIs are both part of
  [Troubleshoot](https://troubleshoot.sh/docs/#installation). Install them with:

  ```bash
@@ -265,7 +265,7 @@
  ```
 </Tip>

 Then confirm the application is reachable at your configured hostname and log in.

 ## Next Steps

@@ -290,6 +290,9 @@
 
 ## Troubleshooting
 
+For a guided diagnostic workflow and a map of OHE components, see
+[Troubleshooting](/enterprise/troubleshooting).
+
 ### Generate a support bundle
 
 If something isn't working, generate a support bundle with the
@@ -298,7 +301,7 @@
 resource states, and health checks from the installation:
 
 ```bash
-support-bundle --load-cluster-specs --namespace openhands
+kubectl support-bundle --load-cluster-specs --namespace openhands
 ```
 
 ### Send it to us
@@ -307,7 +310,7 @@
 authenticates with the license embedded in the bundle:
 
 ```bash
-support-bundle upload support-bundle-<timestamp>.tar.gz
+kubectl support-bundle upload support-bundle-<timestamp>.tar.gz
 ```
 
 ### Common issues

diff --git a/enterprise/quick-start.mdx b/enterprise/quick-start.mdx
@@ -36,7 +36,7 @@
 You will need a VM to host OpenHands Enterprise. Choose one of the options below to provision your infrastructure.

 <Note>
  The requirements below are the trial baseline, which comfortably supports about 15 concurrent sandboxes. For a larger rollout, pick your VM from the [Sizing Guide](/enterprise/sizing-guide) before provisioning.
 </Note>

 <Tabs>
@@ -209,7 +209,7 @@
 done
 ```

 Expected: each hostname resolves to your VM's public IP address through the
 wildcard record.

 ### Outbound connectivity checks
@@ -239,7 +239,7 @@
 done
 ```

 Any HTTP response code other than `000` is acceptable for reachability checks
 (for example `200`, `301`, `302`, `401`, `403`, `405`).

 If any check fails, stop and resolve before continuing:
@@ -250,10 +250,10 @@

 | Requirement | Why It Exists |
 |------------|----------------|
 | `443/TCP` inbound | Primary HTTPS entrypoint for users and service hostnames |
 | `30000/TCP` inbound | Replicated/KOTS Admin Console for install and configuration |
 | `80/TCP` inbound | HTTP entrypoint used for ingress/redirect behavior |
 | `*.<domain>` DNS + cert SAN | Application services and sandboxes are addressed by hostnames under the base domain |
 | `replicated.app`, `proxy.replicated.com` | Replicated control-plane/license/install paths |
 | `images.r9...`, `charts.r9...`, `updates.r9...`, `install.r9...` | Vendor distribution image/chart/update/install endpoints |
 | `traefik.github.io` | Embedded cluster ingress chart repository |
@@ -286,7 +286,9 @@
 3. **Extract the installation assets** -- run the `tar` command shown (this includes your license file)
 4. **Install** -- run the install command shown
 
-If the install command fails after preflight checks pass, run `sudo ./openhands support-bundle` and share the resulting bundle with support.
+If the install command fails after preflight checks pass, see
+[Troubleshooting](/enterprise/troubleshooting) to generate a support
+bundle and open a support ticket.
 
 <Warning>
   **We recommend providing your TLS certificates during installation.** If you used the
@@ -304,7 +306,7 @@

  For trials and production deployments, use a publicly trusted TLS certificate whenever possible.
  Private CA certificates may work for users after manual trust setup, but external integrations
  such as GitHub, GitLab, Slack, Jira, and Bitbucket must also trust the certificate chain. If they
  do not, webhook or OAuth callbacks can fail TLS verification and repeatedly retry.
 </Warning>

@@ -324,7 +326,7 @@
 ### 5. Upload TLS certificate (if not provided with the install command)

 If you did not provide certificates with the `install` command, select **"Upload your own"**,
 enter `admin.<your-base-domain>` under **Hostname**, upload your private key and SSL certificate, then click **Continue**.

 If you upload a private CA certificate, make sure any external webhook or OAuth provider that
 calls OpenHands also trusts that CA.
@@ -352,7 +354,7 @@

 ### Domain Configuration

 - Keep the Hostname Configuration Mode set to **"Simple (default)"**
 - Enter your base domain (e.g., `openhands.example.com`)

 ### Certificate Configuration
@@ -393,7 +395,7 @@

 ### Additional Integrations

 If your team uses Jira Data Center or Bitbucket Data Center, follow these guides
 to configure Admin Console values before deployment and complete webhook setup
 inside OpenHands after deployment.

@@ -402,7 +404,7 @@
    Configure Bitbucket Data Center login, repository access, bot identity, and pull request webhooks.
  </Card>
  <Card title="Jira Data Center" icon="building" href="/enterprise/integrations/jira-data-center">
    Configure Jira issue triggers, OAuth account linking, service account credentials, and Jira webhooks.
  </Card>
 </CardGroup>

@@ -443,8 +445,8 @@
   <Card title="Prompting Best Practices" icon="lightbulb" href="/openhands/usage/tips/prompting-best-practices">
     Get the most out of your AI coding agents with effective prompting techniques.
   </Card>
-  <Card title="Contact Support" icon="headset" href="https://openhands.dev/contact">
-    Reach out to the OpenHands team for deployment assistance or questions.
+  <Card title="Troubleshooting" icon="life-ring" href="/enterprise/troubleshooting">
+    Collect diagnostics, inspect workloads, and contact OpenHands Support.
   </Card>
   <Card title="OpenHands Documentation" icon="book" href="/overview/introduction">
     Explore the full OpenHands documentation for usage guides and features.

diff --git a/enterprise/troubleshooting.mdx b/enterprise/troubleshooting.mdx
@@ -0,0 +1,207 @@
+---
+title: Troubleshooting
+description: Collect diagnostics and inspect OpenHands Enterprise (OHE) workloads.
+icon: life-ring
+---
+
+OpenHands Enterprise Replicated VM installations run in a Replicated Embedded
+Cluster which is a Kubernetes cluster based on k0s. Once you have access to the
+VM, you can use standard Kubernetes commands to inspect OHE. For Helm
+deployments, use your existing Kubernetes access to run the same commands.
+
+Most OHE workloads run in the `openhands` namespace. The Replicated Admin
+Console runs in `kotsadm`, and ingress runs in `traefik`.
+
+## Start With a Support Bundle
+
+A support bundle is the fastest way to give OpenHands Support a snapshot of the
+installation. You do not need to investigate the problem yourself before opening
+a support ticket.
+
+### Use the Admin Console
+
+For a Replicated VM installation:
+
+1. Open `https://admin.<your-base-domain>:30000`.
+2. Select `Troubleshoot`.
+3. Select `Analyze` and wait for it to finish.
+4. Select `Download bundle`.
+
+If `Send bundle to vendor` is available, you can upload the bundle for us to
+inspect directly. Sending a support bundle does not automatically create a
+support ticket, so be sure to still open a support ticket and mention the
+support bundle upload.
+
+### Use the Command Line
+
+On a Replicated VM, use the command line when the Admin Console is unavailable.
+For a Helm installation, run the Kubernetes command from a workstation with
+`kubectl` access.
+
+<Tabs>
+  <Tab title="Replicated (VM/embedded cluster)">
+    Connect to the VM and run:
+
+    ```bash
+    sudo /var/lib/embedded-cluster/bin/openhands support-bundle
+    ```
+
+    If the installation did not complete, run the original installer from the
+    directory where you extracted it:
+
+    ```bash
+    sudo ./openhands support-bundle
+    ```
+  </Tab>
+  <Tab title="Kubernetes (Helm)">
+    For OHE installed with Helm in an existing Kubernetes cluster, run this
+    command from a workstation with `kubectl` access:
+
+    ```bash
+    kubectl support-bundle --load-cluster-specs --namespace openhands
+    ```
+
+    See the [Kubernetes installation guide](/enterprise/k8s-install/installation#step-5-validate-the-installation)
+    if the `support-bundle` CLI is not installed.
+  </Tab>
+</Tabs>
+
+The bundle includes cluster health, Kubernetes resource state, application logs,
+and OHE service checks.
+
+### Open a Support Ticket
+
+Open the OpenHands Support Portal provided during Enterprise onboarding. Please
+attach the generated archive. If you used `Send bundle to vendor`, mention the
+upload in the ticket. Include:
+
+- When the problem occurred, including the time zone.
+- The affected user or conversation ID, when applicable.
+- The expected and actual behavior.
+- Any recent upgrade or configuration change.
+- Steps that reproduce the problem.
+
+If you cannot access the Support Portal, please contact your OpenHands
+representative for more assistance.
+
+## Inspect the Deployment
+
+This workflow is for practitioners who are already familiar with `kubectl`.
+
+<Warning>
+  Keep your investigation read-only. Do not change Kubernetes resources unless
+  directed by OpenHands Support. Ad hoc `kubectl` changes can be overwritten
+  during a deployment or upgrade and may leave the installation in an
+  inconsistent state.
+</Warning>
+
+### Get a Kubernetes Session
+
+<Tabs>
+  <Tab title="Replicated (VM/embedded cluster)">
+    Connect to a controller VM. On a single-node installation, this is the OHE
+    VM. Then run:
+
+    ```bash
+    sudo /var/lib/embedded-cluster/bin/openhands shell
+    ```
+
+    This opens a shell with `kubectl` configured for the embedded cluster. Run
+    `exit` when finished.
+  </Tab>
+  <Tab title="Kubernetes (Helm)">
+    Use your existing Kubernetes access and confirm the current context:
+
+    ```bash
+    kubectl config current-context
+    kubectl get pods -n openhands
+    ```
+  </Tab>
+</Tabs>
+
+### Check Overall Status
+
+Record the time, then inspect the cluster and recent events:
+
+```bash
+date -u
+kubectl get nodes -o wide
+kubectl get pods -n openhands -o wide
+kubectl get deployments,statefulsets -n openhands
+kubectl get events -n openhands --sort-by=.metadata.creationTimestamp
+```
+
+Start with the `STATUS`, `READY`, and `RESTARTS` columns:
+
+- `Pending` usually points to scheduling, storage, or capacity problems.
+- `Init:` means an init container has not completed. Check that container's logs.
+- `CrashLoopBackOff` means a container repeatedly exits. Check previous logs.
+- A pod that is not ready or keeps restarting usually has a failed dependency,
+  health check, or resource limit.
+
+If the Kubernetes Metrics API is available, check current resource usage:
+
+```bash
+kubectl top pods -n openhands
+```
+
+### Inspect a Pod and Its Logs
+
+```bash
+kubectl describe pod -n openhands <pod-name>
+
+kubectl logs -n openhands <pod-name> \
+  --all-containers=true --since=30m --timestamps
+
+kubectl logs -n openhands <pod-name> \
+  --all-containers=true --previous --timestamps
+
+kubectl logs -n openhands <pod-name> -c <container-name> \
+  --since=10m --timestamps --follow
+```
+
+Use `--previous` after a container restarts. Use `-c` to select a specific
+container, including an init container such as `migrate-db`.
+
+### Choose the Right Component
+
+Pod names may include a release prefix and generated suffix. Match the
+recognizable component name to the table below.
+
+| Component | Investigate when |
+|---|---|
+| `openhands` | Web application, API, conversations, and general application errors. |
+| `openhands-integrations` | Integration events and background integration work. |
+| `runtime-api` | Sandbox creation, startup, pause, and cleanup. |
+| `runtime-...` | A particular conversation's sandbox. |
+| `litellm` | Model-provider requests and authentication. |
+| `keycloak` | Login, SSO, and authentication. |
+| `kotsadm` namespace | Replicated Admin Console problems. |
+
+### Temporarily Enable Debug Logging
+
+On a Replicated VM, `Log Level` defaults to `INFO`. Use `DEBUG` only during a
+short investigation:
+
+1. In the Admin Console, select `Config`.
+2. Under `Troubleshooting`, set `Log Level` to `DEBUG`.
+3. Save and deploy, then reproduce the problem.
+4. Collect the logs or a support bundle.
+5. Return `Log Level` to `INFO`, then save and deploy again.
+
+## Related Guides
+
+<CardGroup cols={2}>
+  <Card title="Quick Start" icon="rocket" href="/enterprise/quick-start">
+    Install an OpenHands Enterprise VM deployment.
+  </Card>
+  <Card title="Admin Console Configuration" icon="sliders" href="/enterprise/vm-install/admin-console-configuration">
+    Configure a Replicated VM installation.
+  </Card>
+  <Card title="Kubernetes Installation" icon="dharmachakra" href="/enterprise/k8s-install/installation">
+    Install OHE into an existing Kubernetes cluster.
+  </Card>
+  <Card title="Resource Limits" icon="gauge-high" href="/enterprise/k8s-install/resource-limits">
+    Diagnose and tune CPU, memory, replicas, and storage.
+  </Card>
+</CardGroup>
diff --git a/enterprise/vm-install/admin-console-configuration.mdx b/enterprise/vm-install/admin-console-configuration.mdx
@@ -36,14 +36,14 @@

 ### Recommended: Simple

 Use the default `Simple` mode unless your organization requires a custom hostname for each service.

 1. Leave `Hostname Configuration Mode` set to `Simple (default)`.
 2. Enter your `Base Domain`, such as `openhands.example.com`.

 Every hostname sits one subdomain under the base domain, so a single wildcard DNS record and TLS certificate for `*.openhands.example.com` cover all of them:

 | Service | Hostname |
 |---|---|
 | Admin Console | `admin.openhands.example.com:30000` |
 | OpenHands application | `app.openhands.example.com` |
@@ -54,7 +54,7 @@
 | Sandboxes | `<id>-runtime.openhands.example.com` |

 <Note>
  Installations created before the Simple layout run in `Legacy` mode, which nests some hostnames deeper (`auth.app.<base>`, `*.runtime.<base>`). Keep existing installs on Legacy; their certificates and OAuth callbacks were issued for those hostnames.
 </Note>

 <Accordion title="Customize every hostname">
@@ -62,19 +62,19 @@

  | Field | Description |
  |---|---|
  | `Application Hostname` | Hostname for the OpenHands application. |
  | `Analytics Hostname` | Hostname for the analytics service. |
  | `Authentication Hostname` | Hostname for Keycloak. |
  | `LLM Proxy Hostname` | Hostname for the bundled LiteLLM proxy. |
  | `Runtime API Hostname` | Hostname for the Runtime API. |
  | `Runtime Base Hostname` | Base hostname used to create sandbox routes. |

  You must create DNS records, issue certificates, and configure external OAuth and webhook callbacks for the complete custom hostname set.
 </Accordion>

 ### Additional CORS Origins

 `Additional Permitted CORS Origins` is optional in either hostname mode. Enter a comma-separated list of browser origins, including the scheme and host with no path or trailing slash. The OpenHands application origin is always allowed automatically.

 ## Certificate Configuration

@@ -99,7 +99,7 @@
 | `Google` | Google AI Studio API key, or Vertex AI project, location, service-account file, and model IDs |
 | `DeepSeek` | API key |
 | `Mistral AI` | API key |
 | `Azure` | Authentication method, endpoint, API version, deployment names, and either an API key or Microsoft Entra service-principal credentials |
 | `Groq` | API key |
 | `OpenRouter` | API key |
 | `AWS Bedrock` | Authentication method, AWS Region, model IDs, and optionally an access-key pair |
@@ -142,11 +142,11 @@

 ### Azure DevOps Authentication

 Configure the Microsoft Entra tenant, Azure DevOps organization, client ID, and client secret. See [Azure DevOps](/enterprise/integrations/azure-devops).

 ### Jira Data Center Integration

 Configure the Jira base URL, account-linking method, and either OAuth or service-account credentials. See [Jira Data Center](/enterprise/integrations/jira-data-center).

 ### GitHub Authentication

@@ -163,7 +163,7 @@

 ### GitLab Authentication

 Provide the GitLab host and OAuth client credentials. Leave the host at `gitlab.com` for GitLab SaaS, or enter the hostname of your self-managed GitLab instance.

 ### Slack

@@ -175,7 +175,7 @@

 | Field | Description |
 |---|---|
 | `SMTP Host` | SMTP server hostname. |
 | `SMTP Port` | SMTP server port. The default is `587`. |
 | `SMTP From Email` | Sender address for OpenHands notifications. |
 | `Use SMTP SSL` | Uses implicit TLS/SMTPS. |
@@ -195,7 +195,7 @@
 - SSL mode
 - Username and password
 - Whether OpenHands should create databases automatically
 - Database names for OpenHands, Keycloak, LiteLLM, Runtime API, and Automations

 See [External PostgreSQL](/enterprise/external-postgres) for version, encoding, privilege, and database requirements.

@@ -243,7 +243,7 @@
 |---|---|
 | `HTTP_PROXY` | Proxy URL for HTTP traffic. |
 | `HTTPS_PROXY` | Proxy URL for HTTPS traffic. |
 | `NO_PROXY` | Additional comma-separated hosts that bypass the proxy. OpenHands adds internal services and configured deployment hostnames automatically. |
 | `SSL Verification` | Verifies outbound TLS certificates. Keep enabled unless a trusted proxy configuration requires otherwise. |

 Prefer adding the proxy CA under `Additional Trusted CA Certificates` instead of disabling TLS verification.
@@ -252,6 +252,9 @@
 
 `Log Level` defaults to `INFO`. Use `DEBUG` only while investigating a problem because it produces significantly more log output. Return to `INFO` after collecting the necessary diagnostics.
 
+See [Troubleshooting](/enterprise/troubleshooting) to generate a
+support bundle, inspect component logs, and open a support ticket.
+
 ## Experimental
 
 `Enable Plugin Directory` deploys the experimental plugin marketplace at `/plugins`. When enabled, configure a marketplace source beginning with `github://`, `https://`, or `http://`.
@@ -264,11 +267,11 @@

 See [Analytics](/enterprise/analytics) for the complete setup and verification flow.

 ## Automations

 `Enable Automations` deploys the Automations UI and backend.

 If you use external PostgreSQL, create and grant access to the Automations database before enabling this option.

 ## Advanced Options

@@ -286,10 +289,10 @@

 ## Installer-Managed Secrets

 Replicated generates internal PostgreSQL, Redis, JWT, Keycloak, LiteLLM, sandbox, plugin-directory, and Automations secrets during installation. These values are intentionally hidden from the configuration screen.

 <Warning>
  Do not rotate installer-managed secrets manually unless OpenHands Support provides a component-specific procedure. In particular, changing the LiteLLM salt key makes provider credentials already stored by LiteLLM undecryptable.
 </Warning>

 ## Related Guides
@@ -307,4 +310,7 @@
   <Card title="Analytics" icon="chart-line" href="/enterprise/analytics">
     Configure Laminar observability.
   </Card>
+  <Card title="Troubleshooting" icon="life-ring" href="/enterprise/troubleshooting">
+    Collect diagnostics and inspect the deployment.
+  </Card>
 </CardGroup>