Add organization key concepts and a Configuring Organizations page

docs.json

@@ -571,6 +571,7 @@
                 "icon": "building",
                 "pages": [
                   "openhands/usage/cloud/organizations/overview",
+                  "openhands/usage/cloud/organizations/configuring-organizations",
                   "openhands/usage/cloud/organizations/managing-members",
                   "openhands/usage/cloud/organizations/roles-permissions",
                   "openhands/usage/cloud/organizations/settings",

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 |
@@ -127,11 +127,13 @@
 | 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. |
+| `Automatically Add Signed-In Users` | Adds authenticated users to the default organization as members. Checked by default once the default organization is enabled. |
+| `Hide Personal Workspaces` | Shows the default organization as the only workspace. Existing personal data is hidden, not deleted. Checked by default once the default organization is enabled. |
 
 These settings are additive. Disabling them does not delete organizations, remove members, or demote users.
 
+For what each setting does and how to move an existing installation to organizations, see [Configuring Organizations](/openhands/usage/cloud/organizations/configuring-organizations).
+
 ## Authentication and Integrations
 
 The following groups appear independently and reveal additional required fields when enabled.
@@ -142,11 +144,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 +165,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 +177,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 +197,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.
 
@@ -244,7 +246,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.
@@ -268,11 +270,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
 
@@ -284,16 +286,16 @@
 | `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. |
+| `Enable OEM User Creation Flow` | Lets OEM deployments provision organizations and users through the supported OEM flow. See [User Provisioning](/openhands/usage/cloud/organizations/configuring-organizations#user-provisioning). |
 
 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.
 
 <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

openhands/usage/cloud/organizations/configuring-organizations.mdx

@@ -0,0 +1,164 @@
+---
+title: Configuring Organizations
+description: Settings that control the default organization, personal workspaces, and user provisioning, and how to move an existing installation to organizations.
+---
+
+<Note>
+  These settings apply to self-hosted OpenHands Enterprise, not to OpenHands Cloud (SaaS). For the concepts
+  behind them, see the [Organizations Overview](/openhands/usage/cloud/organizations/overview#key-concepts).
+</Note>
+
+## Settings and Defaults
+
+Out of the box, none of these settings are on. Every user has only a personal workspace, and an installation
+that predates these settings keeps working that way until you change them.
+
+A VM install and a Kubernetes install are configured differently but set the same underlying values. The Admin
+Console applies its options to the Helm chart's `env` values when you deploy.
+
+<Tabs>
+  <Tab title="VM Install">
+    Set these in the Admin Console. The default organization options are under **Default OpenHands Organization**
+    and the provisioning option is under **Advanced Options**. Save the config and deploy the new version for a
+    change to take effect. See [Admin Console Configuration](/enterprise/vm-install/admin-console-configuration).
+
+    | Setting | Admin Console option | Default |
+    |---|---|---|
+    | Default organization | `Enable Default OpenHands Organization` | Unchecked |
+    | Add users automatically | `Automatically Add Signed-In Users` | Checked, once the default organization is enabled |
+    | Hide personal workspaces | `Hide Personal Workspaces` | Checked, once the default organization is enabled |
+    | User provisioning | `Enable OEM User Creation Flow` | Unchecked |
+
+    The default organization is named `Enterprise Org`. The name cannot be changed from the Admin Console, but the
+    owner can rename the organization in the app.
+
+    <Warning>
+      Checking `Enable Default OpenHands Organization` reveals `Automatically Add Signed-In Users` and
+      `Hide Personal Workspaces`, both already checked. If you save without changing them, every user is added to
+      the default organization and their personal workspace is hidden. To roll out gradually, uncheck
+      `Hide Personal Workspaces` before you deploy.
+    </Warning>
+  </Tab>
+  <Tab title="Kubernetes Install">
+    Set these in the Helm `values.yaml`. Each one is off unless you set it.
+
+    | Setting | Helm value | Default |
+    |---|---|---|
+    | Default organization | `env.OPENHANDS_DEFAULT_ORG_ENABLED` | Off |
+    | Add users automatically | `env.OPENHANDS_DEFAULT_ORG_AUTO_ADD_USERS` | Off |
+    | Hide personal workspaces | `env.HIDE_PERSONAL_WORKSPACES` and `env.OH_WEB_CLIENT_FEATURE_FLAGS_HIDE_PERSONAL_WORKSPACES` | Off |
+    | Default organization name | `env.OPENHANDS_DEFAULT_ORG_NAME` | `Enterprise Org` |
+    | User provisioning | `userProvisioning.enabled` | Off |
+
+    ```yaml
+    env:
+      OPENHANDS_DEFAULT_ORG_ENABLED: "true"
+      OPENHANDS_DEFAULT_ORG_AUTO_ADD_USERS: "true"
+      OPENHANDS_DEFAULT_ORG_NAME: "Acme Engineering"   # optional
+      # Optional. Set both to hide personal workspaces.
+      HIDE_PERSONAL_WORKSPACES: "true"
+      OH_WEB_CLIENT_FEATURE_FLAGS_HIDE_PERSONAL_WORKSPACES: "true"
+
+    userProvisioning:
+      enabled: true
+    ```
+
+    Hide personal workspaces only together with the default organization and automatic membership, because users
+    need a workspace to land in. The Admin Console enforces this. Helm does not.
+  </Tab>
+</Tabs>
+
+## Default Organization
+
+Turning on `Enable Default OpenHands Organization` makes OpenHands set up the default organization the next time
+a user signs in:
+
+- **No team organization exists.** The first user to sign in creates it, named `Enterprise Org` unless you set a
+  name on a Kubernetes install, and becomes its owner.
+- **Exactly one team organization exists.** It is adopted as the default organization. No duplicate is created.
+- **Two or more team organizations exist.** Nothing is created or adopted, because OpenHands cannot tell which one
+  is meant to be the default.
+
+The default organization is tracked by a flag, not by its name, so the owner can rename it in the app.
+
+### Automatically Add Signed-In Users
+
+With `Automatically Add Signed-In Users` on, every user who signs in is added to the default organization as a
+`Member`. The first time a user is added, the default organization becomes their current organization. After
+that, a user who switches back to their personal workspace stays there, unless personal workspaces are hidden.
+
+With it off, users join the default organization by invitation only.
+
+### Hide Personal Workspaces
+
+`Hide Personal Workspaces` is available only when the default organization and automatic membership are both on.
+Turning either one off also turns hiding off.
+
+When it is on:
+
+- **The personal workspace disappears from the organization selector** for users who belong to at least one team
+  organization. A user whose only workspace is personal still sees it, so no one is left with nothing.
+- **Users parked on a personal workspace are moved** to the default organization when they next sign in, if they
+  are a member of it.
+- **Nothing is deleted.** Conversations, secrets, API keys, and automations in a personal workspace are hidden,
+  not removed. Turning the setting off shows them again.
+- **Personal workspaces are still created** for new users. Hiding changes what users see, not what exists.
+
+### Turning Settings Off
+
+These settings are additive. Turning them off does not delete organizations, remove members, or demote users.
+Users stay in the default organization, and hidden personal workspaces reappear.
+
+## User Provisioning
+
+`Enable OEM User Creation Flow` and `userProvisioning.enabled` both set `USER_PROVISIONING_ENABLED=true` on the
+app server. This registers `POST /api/organizations/provision-user`, which lets a super admin, or an organization
+owner or admin for their own organization, create a user with a password and an API key. While the setting is
+off, that endpoint returns `404`. Creating organizations and managing super admins are always available to
+super admins.
+
+On OpenHands Enterprise 1.62.0 or later, turning this setting on also lets any signed-in user list the super
+admins.
+
+<Warning>
+  User provisioning creates accounts with passwords and API keys. Turn it on only when you need to create users
+  without any user input, and turn it off again when you no longer do.
+</Warning>
+
+For a worked example, see [Provision Users](/cookbook/provision-users).
+
+## Moving an Existing Installation to Organizations
+
+An installation that predates organizations has only personal workspaces. You can move to team organizations
+without interrupting anyone, because nothing in these steps deletes or hides data until you choose to hide
+personal workspaces.
+
+<Steps>
+  <Step title="Find a Super Admin">
+    Only a super admin can create organizations. Use the
+    [Super Admins and Organizations](/cookbook/org-admin) example to find yours and grant the role to more people.
+  </Step>
+  <Step title="Create a Team Organization">
+    A super admin creates the organization, then invites its first owner. An invited user who already has an
+    account is added at their next sign-in. If they were working in their personal workspace, they land in the new
+    organization and keep the personal one.
+  </Step>
+  <Step title="Choose One Shared Organization or Several">
+    - **One shared organization for everyone.** Turn on `Enable Default OpenHands Organization` and
+      `Automatically Add Signed-In Users`. The team organization you created is adopted as the default
+      organization, and users are added to it as they sign in. On a VM install, uncheck
+      `Hide Personal Workspaces` before you deploy, because it is checked by default.
+    - **Several team organizations.** Leave the default organization off and invite people to the organization
+      they belong to. With two or more team organizations, the default organization is not set up.
+  </Step>
+  <Step title="Hide Personal Workspaces Last">
+    Once users are in the default organization, turn on `Hide Personal Workspaces` if you want it to be the only
+    workspace users see. You can turn it off again at any time to bring personal workspaces back.
+  </Step>
+</Steps>
+
+## Next Steps
+
+- [Managing Members](/openhands/usage/cloud/organizations/managing-members) - Invite users and manage roles.
+- [Roles and Permissions](/openhands/usage/cloud/organizations/roles-permissions) - Understand the permission levels.
+- [Admin Console Configuration](/enterprise/vm-install/admin-console-configuration) - Every Admin Console option on a VM install.

openhands/usage/cloud/organizations/overview.mdx

@@ -24,6 +24,56 @@
 - **Default LLM Configuration** - Define the default model provider and LLM that all members can use.
 - **Git Organization Claiming** - Claim specific Git organizations to route OpenHands resolver requests to your organization.
 
+## Key Concepts
+
+### Personal Workspaces and Team Organizations
+
+Every user has a **personal workspace**, created automatically the first time they sign in. It is a private
+organization for one person. Conversations, secrets, API keys, and automations created while it is the current
+organization belong to it.
+
+A **team organization** is one you create on purpose to share resources. It has members with
+[roles](/openhands/usage/cloud/organizations/roles-permissions), a default LLM configuration, shared credits,
+and optional Git organization claims. A user can belong to their personal workspace and any number of team
+organizations at the same time.
+
+### Current Organization
+
+Each user has one **current organization**. It decides where new conversations are created and which settings
+apply. Switch between organizations from the organization selector in the app. The selector is hidden when
+there is only one organization to choose from.
+
+OpenHands remembers each user's last selection. Requests that do not name an organization use it, for example
+API calls made with an API key that is not tied to an organization.
+
+### Super Admins
+
+<Note>
+  Super admins apply to OpenHands Enterprise.
+</Note>
+
+A **super admin** is an instance-level role, separate from the organization roles `Owner`, `Admin`, and `Member`.
+A super admin can create organizations, invite or provision users into them, grant or revoke the super admin
+role, and set organization quotas. A super admin does not get organization-level permissions in organizations
+it is not a member of, and is not added as a member of the organizations it creates.
+
+On OpenHands Enterprise, only super admins can create organizations. To find your super admin or add more, see
+the [Super Admins and Organizations](/cookbook/org-admin) cookbook example.
+
+### Default Organization
+
+<Note>
+  The default organization applies to OpenHands Enterprise.
+</Note>
+
+A **default organization** is an optional team organization that an administrator turns on for the whole
+installation. It can add every user who signs in to the same organization as a member, and can hide personal
+workspaces so it is the only workspace users see.
+
+Existing data is never deleted when you turn these settings on or off. See
+[Configuring Organizations](/openhands/usage/cloud/organizations/configuring-organizations) for the settings,
+what each one does, and how to move an existing installation to organizations.
+
 ## Conversation Visibility
 
 By default, conversations remain **private to individual members** of an organization. Each user's conversations
@@ -34,7 +84,7 @@
 To start using Organizations:
 
 1. Subscribe to an OpenHands Cloud plan or OpenHands Enterprise.
-2. Create a new organization from the OpenHands Cloud dashboard.
+2. Create a new organization. In OpenHands Cloud, use the dashboard. In OpenHands Enterprise, a [super admin](#super-admins) creates it. See [Configuring Organizations](/openhands/usage/cloud/organizations/configuring-organizations).
 3. [Invite team members](/openhands/usage/cloud/organizations/managing-members) to join your organization.
 4. Configure your organization's [LLM settings](/openhands/usage/cloud/organizations/settings) and shared resources.
 
@@ -43,3 +93,4 @@
 - [Managing Members](/openhands/usage/cloud/organizations/managing-members) - Learn how to invite users and manage roles.
 - [Organization Settings](/openhands/usage/cloud/organizations/settings) - Configure LLM providers, credits, and Git organization claims.
 - [Roles and Permissions](/openhands/usage/cloud/organizations/roles-permissions) - Understand the different permission levels.
+- [Configuring Organizations](/openhands/usage/cloud/organizations/configuring-organizations) - Settings for the default organization, personal workspaces, and user provisioning, and how to migrate an existing installation.