> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Admin Console Configuration
> Configure an OpenHands Enterprise VM deployment from the Replicated Admin Console.
Use the Replicated Admin Console to configure an OpenHands Enterprise deployment installed with Replicated Embedded Cluster.
The available options depend on your OpenHands Enterprise release. This page follows the current release. If a field is not present in your Admin Console, check `Version history` for an available update.
## Open the Configuration Screen
1. Open `https://:30000`.
2. Log in with the Admin Console password created during installation.
3. Select `Config`.
For initial installation instructions, see [Quick Start](/enterprise/quick-start).
Configuration pages contain credentials and other sensitive values. Do not include populated configuration screens in tickets, screenshots, or support messages. Use a support bundle when requested by OpenHands Support.
## Apply a Configuration Change
1. Update the required fields.
2. Select `Save config`.
3. Review the pending configuration change.
4. Deploy the new sequence.
5. On `Dashboard`, wait for the application status to return to `Ready`.
Some changes restart one or more OpenHands components. Make changes during a maintenance window when required by your operating policies.
## Domain Configuration
### Recommended: Derive Hostnames From One Domain
Use the default `Derive hostnames from domain (recommended)` mode unless your organization requires a custom hostname for each service.
1. Leave `Hostname Configuration Mode` set to `Derive hostnames from domain (recommended)`.
2. Enter your `Base Domain`, such as `openhands.example.com`.
3. Create DNS records and TLS coverage for the derived hostnames.
For a base domain of `openhands.example.com`, OpenHands uses:
| Service | Derived Hostname |
| --------------------- | ------------------------------------- |
| Admin Console | `openhands.example.com:30000` |
| OpenHands application | `app.openhands.example.com` |
| Analytics | `analytics.app.openhands.example.com` |
| Authentication | `auth.app.openhands.example.com` |
| LLM proxy | `llm-proxy.openhands.example.com` |
| Runtime API | `runtime-api.openhands.example.com` |
| Sandboxes | `*.runtime.openhands.example.com` |
The derived mode keeps DNS, certificates, OAuth callbacks, and webhook URLs consistent with the standard OpenHands deployment. It is the recommended path for most installations.
Select `Enter all hostnames manually` only when your DNS or network requirements do not allow the derived layout.
| 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.
### 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
| Field | Description |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TLS Certificate` | Required PEM-encoded server certificate. Include intermediate certificates when needed. |
| `TLS Private Key` | Required PEM-encoded private key matching the server certificate. |
| `Additional Trusted CA Certificates` | Optional PEM bundle added to the cluster trust store. Use this for private certificate authorities and concatenate multiple certificates into one file. |
A private CA must also be trusted by external systems that call OpenHands, including OAuth and webhook providers. Otherwise, sign-in callbacks and integration webhooks may fail TLS validation.
## LLM Configuration
Select the administrator-managed LLM provider. The Admin Console shows only the fields required by the selected provider.
| Provider | Fields |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `Anthropic (Claude)` | API key and one or more Anthropic model IDs |
| `OpenAI (GPT)` | API key |
| `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 |
| `Custom/Local LLM` | Base URL, optional API key, and full LiteLLM model strings |
### Provider Notes
* For Azure, deployment names must exist at the configured endpoint and API version.
* For AWS Bedrock, use an EC2 instance profile where possible. Pods must be able to reach the instance metadata service, and the role needs model invocation permissions.
* For custom OpenAI-compatible endpoints, prefix model names with `openai/`.
* Model lists accept one model per line.
### Bring Your Own Key
Enable `Allow users to configure their own LLM providers (BYOK)` to let users add provider credentials and custom models in their OpenHands settings. Leave it disabled to restrict users to administrator-managed models.
## LiteLLM Admin Console
`LiteLLM Admin Password` sets the password for the LiteLLM UI at `https:///ui`. The username is `admin`.
Changing this password restarts LiteLLM. Models added in LiteLLM appear in the OpenHands model selector after a short delay. Leave the LiteLLM `Team` field blank to make a model available to all users, and do not reuse a model name already configured in the Replicated LLM section.
## Default OpenHands Organization
| Field | Description |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `Enable Default OpenHands Organization` | Lets the first user who signs in create and own the default organization. |
| `Automatically Add Signed-In Users` | Adds authenticated users to the default organization as members. |
| `Hide Personal Workspaces` | Shows the default organization as the only workspace. Existing personal data is hidden, not deleted. |
These settings are additive. Disabling them does not delete organizations, remove members, or demote users.
## Authentication and Integrations
The following groups appear independently and reveal additional required fields when enabled.
### Bitbucket Data Center Authentication
Configure the server domain, OAuth application credentials, and bot identity used for repository operations. See [Bitbucket Data Center](/enterprise/integrations/bitbucket-data-center).
### 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
Enable the GitHub App used for sign-in and repository access, then provide:
* `GitHub App Client ID`
* `GitHub App Client Secret`
* `GitHub App ID`
* `GitHub App Slug`
* `GitHub App Webhook Secret`
* `GitHub App Private Key`
Use a GitHub App, not a GitHub OAuth App.
### 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
Provide the Slack client ID, client secret, and signing secret. After deployment, complete the OpenHands-side installation and account-linking flow. See [Slack](/enterprise/integrations/slack).
## SMTP Email Delivery
Enable SMTP to send budget alerts and administrator notifications.
| 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. |
| `Use SMTP STARTTLS` | Upgrades a plain connection with STARTTLS. Enabled by default. |
| `SMTP Username` | Optional authentication username. |
| `SMTP Password` | Optional authentication password. |
Match the SSL and STARTTLS options to the behavior required by your mail server.
## Database Configuration
Choose the bundled PostgreSQL database or an external PostgreSQL service.
For an external database, configure:
* Host and port
* 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.
Do not switch an existing deployment from embedded to external PostgreSQL without a migration and rollback plan. Changing connection settings does not migrate existing data.
## Sandbox Configuration
| Field | Description |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `Sandbox Isolation` | Selects the sandbox isolation mechanism supported by the deployment. |
| `Sandbox Routing Mode` | Uses subdomains or another supported routing mode for sandbox traffic. |
| `Idle Time (seconds)` | Pauses idle conversations after the configured period, releasing CPU and memory. |
| `Deletion Time (seconds)` | Permanently deletes paused conversations and their storage after the configured period. |
| `Storage Size` | Persistent storage allocated to each sandbox. |
| `Ephemeral Storage Size` | Ephemeral-storage reservation for each sandbox. This affects node scheduling capacity. |
| `Memory Request` | Memory reserved for each sandbox. |
| `Memory Limit` | Maximum memory available to each sandbox. |
| `CPU Request` | CPU reserved for each sandbox. |
| `CPU Limit` | Maximum CPU available to each sandbox. |
| `Warm Runtime Count` | Number of ready sandboxes kept for faster conversation startup. Set to `0` for cold starts only. |
| `Additional Host Path Mounts` | Host paths mounted into every sandbox, one per line as `host_path:container_path[:ro\|rw]`. |
| `Enable /dev/kvm passthrough (QEMU/KVM)` | Makes host KVM acceleration available inside sandboxes. The node must expose `/dev/kvm`. |
Resource requests are scheduling reservations. Multiply per-sandbox requests by the expected concurrent sandbox count and leave capacity for the platform services.
### Custom Sandbox Image
Enable `Use a Custom Sandbox Image` to configure an image repository, tag, and optional private-registry credentials. See [Custom Sandbox Images](/enterprise/custom-sandbox-image).
## Proxy Configuration
Enable the HTTP proxy when outbound traffic must pass through a corporate proxy.
| Field | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `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.
## Troubleshooting
`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.
## Experimental
`Enable Plugin Directory` deploys the experimental plugin marketplace at `/plugins`. When enabled, configure a marketplace source beginning with `github://`, `https://`, or `http://`.
See [Plugin Marketplace](/enterprise/plugin-marketplace) for setup and limitations.
## Analytics Configuration
Enable analytics to deploy the bundled Laminar observability services. Optionally provide a Laminar project API key; an ingest-only key is recommended.
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
| Field | Description |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `OpenHands Resolver Label` | Label and `@mention` that trigger supported issue and pull-request integrations. |
| `Enable Forwarding Client Headers Through LiteLLM to LLM Providers` | Forwards selected client headers. It does not forward `Authorization` or arbitrary non-`x-*` gateway headers. |
| `Enable Custom LLM Extra HTTP Headers (JSON)` | Adds static headers to requests sent through a custom LLM gateway. |
| `Custom LLM Extra HTTP Headers (JSON)` | JSON object containing static string header values. Treat these values as secrets when they contain credentials. |
| `Login Session Idle Timeout (seconds)` | Maximum inactivity period before a user must sign in again. |
| `Login Session Max Duration (seconds)` | Maximum total login-session lifetime, regardless of activity. |
| `Enable OEM User Creation Flow` | Lets OEM deployments provision organizations and users through the supported OEM flow. |
Change advanced options only when the corresponding integration or deployment requirement is understood.
## 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.
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.
## Related Guides
Install an OpenHands Enterprise VM deployment.
Prepare and configure an external database.
Build and deploy a custom agent-server image.
Configure Laminar observability.