> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-codex-admin-console-reference-options.mintlify.site/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.
This reference uses the Replicated 0.70 configuration as its baseline. Available options and defaults depend on your installed release. Some fields appear only after you enable their parent feature or select a provider. Check your installed release and its release notes before using a setting described here. A field documented here may not yet be available in an older release.
## Open the Configuration Screen
1. Open `https://admin.: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: 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` |
| Analytics | `analytics.openhands.example.com` |
| Authentication | `auth.openhands.example.com` |
| LLM proxy | `llm-proxy.openhands.example.com` |
| Runtime API | `runtime-api.openhands.example.com` |
| Sandboxes | `-runtime.openhands.example.com` |
Installations created before the Simple layout run in `Legacy` mode, which nests some hostnames deeper (`auth.app.`, `*.runtime.`). Keep existing installs on Legacy; their certificates and OAuth callbacks were issued for those hostnames.
Select `Manual` only when your DNS or network requirements do not allow the Simple 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.
## Keycloak Administration
Use `Keycloak Admin Password` to manage the existing Keycloak `admin` account password. Set it in the Admin Console, save, and deploy, then sign in at `https:///admin/` to manage users and identity-provider account links. Leave the field blank to keep the current password. Manage the password through Replicated so later deployments retain the intended value.
## Authentication Security
`Prevent Duplicate Base Emails` (on by default) rejects sign-ins when another user has the same email after removing a plus-address suffix. For example, `name+test@example.com` matches `name@example.com`. Check for an existing account when investigating a rejected sign-in involving an email alias.
## 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).
### Jira Cloud Integration
Enable `Enable Jira Cloud Integration`, then save and deploy. An organization administrator finishes setup under `Settings → Integrations → Jira` in OpenHands and registers the webhook in Jira Cloud. See [Jira Cloud](/enterprise/integrations/jira-cloud) for service-account credentials, email matching, and webhook setup.
### 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.
### Enterprise SSO (SAML) Authentication
Enable `Enable Enterprise SSO Authentication`, provide the `SAML Metadata URL`, and optionally set the `Identity Provider Display Name`. See [SAML SSO](/enterprise/integrations/saml-sso) for identity-provider requirements and sign-in verification.
### 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, administrator notifications, and Keycloak account emails for email verification, account linking, and password resets.
| 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. |
| `Runtime API Admin Password` | Password for Runtime API admin endpoints, including warm runtime configuration. Set it here and deploy before using those endpoints. Changing it restarts Runtime API. See [Multiple Images and Warm Pools](/enterprise/custom-sandbox-images/multiple-images-warm-pools). |
| `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`. |
| `Run sandboxes on dedicated nodes` | Confines sandboxes to machines added with the `sandbox` role, and keeps the application off those machines. Requires at least one `sandbox` machine already joined. See [Scaling the Cluster](/enterprise/vm-install/scaling). |
`Idle Time` and `Deletion Time` control when idle and paused conversations are
reclaimed. A single running session is additionally capped at 12 hours
regardless of these values; this maximum is not currently configurable. See
[Conversations and Sandboxes](/enterprise/conversations-and-sandboxes) for the
full conversation lifecycle.
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.
See [Troubleshooting](/enterprise/troubleshooting) to generate a
support bundle, inspect component logs, and open a support ticket.
## Upgrade Checks
Budget policy checks run before and after upgrades. These options control whether findings block the upgrade or are recorded while it proceeds.
| Field | Description |
| - | - |
| `Pre-upgrade Budget Preflight` | Read-only check for missing budget baselines, missing gateway members, cap drift, or a failed last sync. The default, `Acknowledge`, records findings; `Strict` blocks the upgrade when problems are found. |
| `Post-upgrade Budget Reconciliation Gate` | Reconciles organization budget policies and verifies them by readback. The default, `Strict`, marks the upgrade failed until reconciliation succeeds. `Acknowledge` records findings and lets the release proceed. |
`Acknowledge` does not establish that budget policy is healthy. If a strict check fails, collect the reported findings and use [Troubleshooting](/enterprise/troubleshooting) before changing the gate mode.
## 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.
When analytics is enabled, `ClickHouse Diagnostic Log Retention` controls retention of ClickHouse system diagnostic tables such as `trace_log`, `query_log`, and `text_log`. These tables can grow quickly on busy installations. This setting controls diagnostic logs, not Laminar conversation-trace retention.
## 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.
### Conversation Archive Delay
`Conversation Archive Delay (seconds)` appears when automations are enabled. It sets the delay after a run finishes before its conversation is archived and its sandbox deleted. The default is `0`, which archives as soon as the run finishes. During the delay the sandbox is paused, and opening the conversation resumes it.
An archive delay longer than sandbox `Deletion Time` does not preserve the sandbox longer: paused sandboxes are deleted at that age regardless. See [Automations](/enterprise/automations) for setup and run ownership.
## Agent Canvas
`Enable Agent Canvas` deploys the conversation UI at `/canvas` on the application hostname and locks it to this installation's OpenHands backend.
## 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.
Collect diagnostics and inspect the deployment.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.