From 3724edba2d4e8f5d97c8d9c2ada6ea006836e804 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 13 Oct 2026 14:43:37 +0000 Subject: [PATCH 1/6] docs: add organization key concepts and an Enterprise organizations page Co-authored-by: openhands --- docs.json | 3 +- .../admin-console-configuration.mdx | 4 +- .../cloud/organizations/enterprise-setup.mdx | 131 ++++++++++++++++++ .../usage/cloud/organizations/overview.mdx | 53 ++++++- 4 files changed, 188 insertions(+), 3 deletions(-) create mode 100644 openhands/usage/cloud/organizations/enterprise-setup.mdx diff --git a/docs.json b/docs.json index 76a3ebf7a..da4e7c38f 100644 --- a/docs.json +++ b/docs.json @@ -574,7 +574,8 @@ "openhands/usage/cloud/organizations/managing-members", "openhands/usage/cloud/organizations/roles-permissions", "openhands/usage/cloud/organizations/settings", - "openhands/usage/cloud/organizations/budgets" + "openhands/usage/cloud/organizations/budgets", + "openhands/usage/cloud/organizations/enterprise-setup" ] }, { diff --git a/enterprise/vm-install/admin-console-configuration.mdx b/enterprise/vm-install/admin-console-configuration.mdx index 2052f18b0..ba1cd1277 100644 --- a/enterprise/vm-install/admin-console-configuration.mdx +++ b/enterprise/vm-install/admin-console-configuration.mdx @@ -132,6 +132,8 @@ Changing this password restarts LiteLLM. Models added in LiteLLM appear in the O 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 [Organizations on OpenHands Enterprise](/openhands/usage/cloud/organizations/enterprise-setup). + ## Authentication and Integrations The following groups appear independently and reveal additional required fields when enabled. @@ -284,7 +286,7 @@ If you use external PostgreSQL, create and grant access to the Automations datab | `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/enterprise-setup#user-provisioning). | Change advanced options only when the corresponding integration or deployment requirement is understood. diff --git a/openhands/usage/cloud/organizations/enterprise-setup.mdx b/openhands/usage/cloud/organizations/enterprise-setup.mdx new file mode 100644 index 000000000..378adfa91 --- /dev/null +++ b/openhands/usage/cloud/organizations/enterprise-setup.mdx @@ -0,0 +1,131 @@ +--- +title: Organizations on OpenHands Enterprise +description: How the default organization, personal workspace, and user provisioning settings behave, and how to move an existing OpenHands Enterprise installation to organizations. +--- + + + This page applies to self-hosted OpenHands Enterprise. For the concepts behind it, see the + [Organizations Overview](/openhands/usage/cloud/organizations/overview#key-concepts). + + +## Settings + +Three settings shape how organizations work on an installation. Replicated VM installations set them in the +Admin Console. Helm installations set them in `values.yaml`. + +| Setting | Replicated VM | Helm | +|---|---|---| +| Default organization | `Enable Default OpenHands Organization` | No chart value | +| Add users automatically | `Automatically Add Signed-In Users` | No chart value | +| Hide personal workspaces | `Hide Personal Workspaces` | No chart value | +| User provisioning | `Enable OEM User Creation Flow` | `userProvisioning.enabled: true` | + +On the Replicated VM, the default organization settings 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). + + + Settings you do not turn on leave behavior unchanged. An installation that was set up before these settings + existed keeps working as it did, with a personal organization for every user. + + +## Default Organization + +Turning on `Enable Default OpenHands Organization` makes OpenHands set up a default organization the next time a +user signs in: + +- **No team organization exists.** The first user to sign in creates the default organization 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. + +### What Turning It Off Does + +These settings are additive. Turning them off does not delete organizations, remove members, or demote users. +Users stay in the default organization. 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. + + + 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. + + +For a worked example that creates an organization and provisions users into it, see +[Provision Users](/cookbook/provision-users). + +## Organization Creation + +Only super admins can create organizations on OpenHands Enterprise. A super admin who creates an organization +is not added to it as a member. Add the first owner by invitation or by provisioning a user into it. + +## 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 the steps below deletes or hides data until you choose to hide +personal workspaces. + + + + Only a super admin can create organizations. Every installation should already have one, usually the person + who installed OpenHands Enterprise. Use the [Super Admins and Organizations](/cookbook/org-admin) example to + find the super admin and grant the role to more people. + + + 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. + + + - **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. + - **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. + + + 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. + + + +## Next Steps + +- [Organizations Overview](/openhands/usage/cloud/organizations/overview) - Learn the concepts behind organizations. +- [Managing Members](/openhands/usage/cloud/organizations/managing-members) - Invite users and manage roles. +- [Admin Console Configuration](/enterprise/vm-install/admin-console-configuration) - Every Replicated Admin Console option. diff --git a/openhands/usage/cloud/organizations/overview.mdx b/openhands/usage/cloud/organizations/overview.mdx index d1df8a313..29930b527 100644 --- a/openhands/usage/cloud/organizations/overview.mdx +++ b/openhands/usage/cloud/organizations/overview.mdx @@ -24,6 +24,56 @@ Organizations provide the following capabilities: - **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 and Team Organizations + +Every user has a **personal organization**, created automatically the first time they sign in. It is a private +workspace 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 organization 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 + + + Super admins apply to OpenHands Enterprise. + + +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 + + + The default organization applies to OpenHands Enterprise. + + +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 +organizations so it is the only workspace users see. + +Existing data is never deleted when you turn these settings on or off. See +[Organizations on OpenHands Enterprise](/openhands/usage/cloud/organizations/enterprise-setup) 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 @@ are only visible to them. 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 [Organizations on OpenHands Enterprise](/openhands/usage/cloud/organizations/enterprise-setup). 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 @@ To start using Organizations: - [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. +- [Organizations on OpenHands Enterprise](/openhands/usage/cloud/organizations/enterprise-setup) - Settings for the default organization, personal workspaces, and user provisioning, and how to migrate an existing installation. From c4249be3eb2929df7d96aab49ed6d12d09e4c185 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 13 Oct 2026 14:53:23 +0000 Subject: [PATCH 2/6] docs: use generic VM install and Kubernetes install wording on the organizations page Co-authored-by: openhands --- .../usage/cloud/organizations/enterprise-setup.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/openhands/usage/cloud/organizations/enterprise-setup.mdx b/openhands/usage/cloud/organizations/enterprise-setup.mdx index 378adfa91..7cc64d91f 100644 --- a/openhands/usage/cloud/organizations/enterprise-setup.mdx +++ b/openhands/usage/cloud/organizations/enterprise-setup.mdx @@ -10,17 +10,17 @@ description: How the default organization, personal workspace, and user provisio ## Settings -Three settings shape how organizations work on an installation. Replicated VM installations set them in the -Admin Console. Helm installations set them in `values.yaml`. +These settings shape how organizations work on an installation. VM installs set them in the Admin Console. +Kubernetes installs set them in the Helm `values.yaml`. -| Setting | Replicated VM | Helm | +| Setting | VM Install | Kubernetes (Helm) Install | |---|---|---| | Default organization | `Enable Default OpenHands Organization` | No chart value | | Add users automatically | `Automatically Add Signed-In Users` | No chart value | | Hide personal workspaces | `Hide Personal Workspaces` | No chart value | | User provisioning | `Enable OEM User Creation Flow` | `userProvisioning.enabled: true` | -On the Replicated VM, the default organization settings are under **Default OpenHands Organization** and the +On a VM install, the default organization settings 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). @@ -128,4 +128,4 @@ personal workspaces. - [Organizations Overview](/openhands/usage/cloud/organizations/overview) - Learn the concepts behind organizations. - [Managing Members](/openhands/usage/cloud/organizations/managing-members) - Invite users and manage roles. -- [Admin Console Configuration](/enterprise/vm-install/admin-console-configuration) - Every Replicated Admin Console option. +- [Admin Console Configuration](/enterprise/vm-install/admin-console-configuration) - Every Admin Console option on a VM install. From d2eaa9e1f66adca6b574f9545a6752bc8cc13f25 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 13 Oct 2026 15:00:21 +0000 Subject: [PATCH 3/6] docs: rename the Enterprise organizations page to Configuring Organizations and trim overlap Co-authored-by: openhands --- docs.json | 4 +- .../admin-console-configuration.mdx | 4 +- ...etup.mdx => configuring-organizations.mdx} | 45 +++++++------------ .../usage/cloud/organizations/overview.mdx | 6 +-- 4 files changed, 24 insertions(+), 35 deletions(-) rename openhands/usage/cloud/organizations/{enterprise-setup.mdx => configuring-organizations.mdx} (73%) diff --git a/docs.json b/docs.json index da4e7c38f..97abb39f9 100644 --- a/docs.json +++ b/docs.json @@ -571,11 +571,11 @@ "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", - "openhands/usage/cloud/organizations/budgets", - "openhands/usage/cloud/organizations/enterprise-setup" + "openhands/usage/cloud/organizations/budgets" ] }, { diff --git a/enterprise/vm-install/admin-console-configuration.mdx b/enterprise/vm-install/admin-console-configuration.mdx index ba1cd1277..1e2d59f14 100644 --- a/enterprise/vm-install/admin-console-configuration.mdx +++ b/enterprise/vm-install/admin-console-configuration.mdx @@ -132,7 +132,7 @@ Changing this password restarts LiteLLM. Models added in LiteLLM appear in the O 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 [Organizations on OpenHands Enterprise](/openhands/usage/cloud/organizations/enterprise-setup). +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 @@ -286,7 +286,7 @@ If you use external PostgreSQL, create and grant access to the Automations datab | `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. See [User Provisioning](/openhands/usage/cloud/organizations/enterprise-setup#user-provisioning). | +| `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. diff --git a/openhands/usage/cloud/organizations/enterprise-setup.mdx b/openhands/usage/cloud/organizations/configuring-organizations.mdx similarity index 73% rename from openhands/usage/cloud/organizations/enterprise-setup.mdx rename to openhands/usage/cloud/organizations/configuring-organizations.mdx index 7cc64d91f..55a5d01f3 100644 --- a/openhands/usage/cloud/organizations/enterprise-setup.mdx +++ b/openhands/usage/cloud/organizations/configuring-organizations.mdx @@ -1,17 +1,16 @@ --- -title: Organizations on OpenHands Enterprise -description: How the default organization, personal workspace, and user provisioning settings behave, and how to move an existing OpenHands Enterprise installation to organizations. +title: Configuring Organizations +description: Settings that control the default organization, personal workspaces, and user provisioning, and how to move an existing installation to organizations. --- - This page applies to self-hosted OpenHands Enterprise. For the concepts behind it, see the - [Organizations Overview](/openhands/usage/cloud/organizations/overview#key-concepts). + 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). ## Settings -These settings shape how organizations work on an installation. VM installs set them in the Admin Console. -Kubernetes installs set them in the Helm `values.yaml`. +VM installs set these in the Admin Console. Kubernetes installs set them in the Helm `values.yaml`. | Setting | VM Install | Kubernetes (Helm) Install | |---|---|---| @@ -24,18 +23,15 @@ On a VM install, the default organization settings are under **Default OpenHands 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). - - Settings you do not turn on leave behavior unchanged. An installation that was set up before these settings - existed keeps working as it did, with a personal organization for every user. - +Settings you do not turn on leave behavior unchanged. An installation that predates these settings keeps working +with a personal organization for every user. ## Default Organization -Turning on `Enable Default OpenHands Organization` makes OpenHands set up a default organization the next time a -user signs in: +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 the default organization and becomes its - owner. +- **No team organization exists.** The first user to sign in creates it 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. @@ -65,10 +61,10 @@ When it is on: 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. -### What Turning It Off Does +### 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. Hidden personal workspaces reappear. +Users stay in the default organization, and hidden personal workspaces reappear. ## User Provisioning @@ -86,25 +82,18 @@ admins. without any user input, and turn it off again when you no longer do. -For a worked example that creates an organization and provisions users into it, see -[Provision Users](/cookbook/provision-users). - -## Organization Creation - -Only super admins can create organizations on OpenHands Enterprise. A super admin who creates an organization -is not added to it as a member. Add the first owner by invitation or by provisioning a user into it. +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 the steps below deletes or hides data until you choose to hide +without interrupting anyone, because nothing in these steps deletes or hides data until you choose to hide personal workspaces. - Only a super admin can create organizations. Every installation should already have one, usually the person - who installed OpenHands Enterprise. Use the [Super Admins and Organizations](/cookbook/org-admin) example to - find the super admin and grant the role to more people. + 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. A super admin creates the organization, then invites its first owner. An invited user who already has an @@ -126,6 +115,6 @@ personal workspaces. ## Next Steps -- [Organizations Overview](/openhands/usage/cloud/organizations/overview) - Learn the concepts behind organizations. - [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. diff --git a/openhands/usage/cloud/organizations/overview.mdx b/openhands/usage/cloud/organizations/overview.mdx index 29930b527..d6e7be3f8 100644 --- a/openhands/usage/cloud/organizations/overview.mdx +++ b/openhands/usage/cloud/organizations/overview.mdx @@ -71,7 +71,7 @@ installation. It can add every user who signs in to the same organization as a m organizations so it is the only workspace users see. Existing data is never deleted when you turn these settings on or off. See -[Organizations on OpenHands Enterprise](/openhands/usage/cloud/organizations/enterprise-setup) for the settings, +[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 @@ -84,7 +84,7 @@ are only visible to them. To start using Organizations: 1. Subscribe to an OpenHands Cloud plan or OpenHands Enterprise. -2. Create a new organization. In OpenHands Cloud, use the dashboard. In OpenHands Enterprise, a [super admin](#super-admins) creates it. See [Organizations on OpenHands Enterprise](/openhands/usage/cloud/organizations/enterprise-setup). +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. @@ -93,4 +93,4 @@ To start using Organizations: - [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. -- [Organizations on OpenHands Enterprise](/openhands/usage/cloud/organizations/enterprise-setup) - Settings for the default organization, personal workspaces, and user provisioning, and how to migrate an existing installation. +- [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. From 9ac3e9fc1b21d134b21e8d64cf4089f3b8c367eb Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 13 Oct 2026 15:16:35 +0000 Subject: [PATCH 4/6] docs: document Helm env values and defaults for the organization settings Co-authored-by: openhands --- .../admin-console-configuration.mdx | 4 +- .../configuring-organizations.mdx | 72 +++++++++++++++---- 2 files changed, 59 insertions(+), 17 deletions(-) diff --git a/enterprise/vm-install/admin-console-configuration.mdx b/enterprise/vm-install/admin-console-configuration.mdx index 1e2d59f14..e06be4c49 100644 --- a/enterprise/vm-install/admin-console-configuration.mdx +++ b/enterprise/vm-install/admin-console-configuration.mdx @@ -127,8 +127,8 @@ Changing this password restarts LiteLLM. Models added in LiteLLM appear in the O | 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. diff --git a/openhands/usage/cloud/organizations/configuring-organizations.mdx b/openhands/usage/cloud/organizations/configuring-organizations.mdx index 55a5d01f3..eddb49b08 100644 --- a/openhands/usage/cloud/organizations/configuring-organizations.mdx +++ b/openhands/usage/cloud/organizations/configuring-organizations.mdx @@ -8,30 +8,71 @@ description: Settings that control the default organization, personal workspaces behind them, see the [Organizations Overview](/openhands/usage/cloud/organizations/overview#key-concepts). -## Settings +## Available Settings -VM installs set these in the Admin Console. Kubernetes installs set them in the Helm `values.yaml`. +The Admin Console on a VM install and the Helm `values.yaml` on a Kubernetes install set the same underlying +configuration. The Admin Console options are applied to the Helm chart's `env` values when you deploy. -| Setting | VM Install | Kubernetes (Helm) Install | +| Setting | VM Install (Admin Console) | Kubernetes Install (Helm `values.yaml`) | |---|---|---| -| Default organization | `Enable Default OpenHands Organization` | No chart value | -| Add users automatically | `Automatically Add Signed-In Users` | No chart value | -| Hide personal workspaces | `Hide Personal Workspaces` | No chart value | -| User provisioning | `Enable OEM User Creation Flow` | `userProvisioning.enabled: true` | - -On a VM install, the default organization settings 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). +| Default organization | `Enable Default OpenHands Organization` | `env.OPENHANDS_DEFAULT_ORG_ENABLED` | +| Add users automatically | `Automatically Add Signed-In Users` | `env.OPENHANDS_DEFAULT_ORG_AUTO_ADD_USERS` | +| Hide personal workspaces | `Hide Personal Workspaces` | `env.HIDE_PERSONAL_WORKSPACES` and `env.OH_WEB_CLIENT_FEATURE_FLAGS_HIDE_PERSONAL_WORKSPACES` | +| Default organization name | Not available | `env.OPENHANDS_DEFAULT_ORG_NAME` | +| User provisioning | `Enable OEM User Creation Flow` | `userProvisioning.enabled` | + + + + The default organization options are under **Default OpenHands Organization**. 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). + + + ```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 + ``` + + Hiding personal workspaces is only safe together with the default organization and automatic membership, + because users need a workspace to land in. The Admin Console enforces this. Helm does not. + + + +## Defaults + +Out of the box, none of these settings are on. Every user has only a personal organization, and an installation +that predates these settings keeps working that way until you change them. + +| Setting | Default when not configured | Default in the Admin Console | +|---|---|---| +| Default organization | Off | Unchecked | +| Add users automatically | Off | Checked, once the default organization is enabled | +| Hide personal workspaces | Off | Checked, once the default organization is enabled | +| Default organization name | `Enterprise Org` | Not available | +| User provisioning | Off | Unchecked | -Settings you do not turn on leave behavior unchanged. An installation that predates these settings keeps working -with a personal organization for every user. + + On a VM install, checking `Enable Default OpenHands Organization` also 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. + ## 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 and becomes its owner. +- **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. @@ -103,7 +144,8 @@ personal workspaces. - **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. + 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. From 02d597e974dfa4e7513b56d7b913d755a5a356f2 Mon Sep 17 00:00:00 2001 From: openhands Date: Tue, 13 Oct 2026 15:22:53 +0000 Subject: [PATCH 5/6] docs: split organization settings and defaults into VM and Kubernetes tabs Co-authored-by: openhands --- .../configuring-organizations.mdx | 72 ++++++++++--------- 1 file changed, 37 insertions(+), 35 deletions(-) diff --git a/openhands/usage/cloud/organizations/configuring-organizations.mdx b/openhands/usage/cloud/organizations/configuring-organizations.mdx index eddb49b08..2f671383c 100644 --- a/openhands/usage/cloud/organizations/configuring-organizations.mdx +++ b/openhands/usage/cloud/organizations/configuring-organizations.mdx @@ -8,26 +8,48 @@ description: Settings that control the default organization, personal workspaces behind them, see the [Organizations Overview](/openhands/usage/cloud/organizations/overview#key-concepts). -## Available Settings +## Settings and Defaults -The Admin Console on a VM install and the Helm `values.yaml` on a Kubernetes install set the same underlying -configuration. The Admin Console options are applied to the Helm chart's `env` values when you deploy. +Out of the box, none of these settings are on. Every user has only a personal organization, and an installation +that predates these settings keeps working that way until you change them. -| Setting | VM Install (Admin Console) | Kubernetes Install (Helm `values.yaml`) | -|---|---|---| -| Default organization | `Enable Default OpenHands Organization` | `env.OPENHANDS_DEFAULT_ORG_ENABLED` | -| Add users automatically | `Automatically Add Signed-In Users` | `env.OPENHANDS_DEFAULT_ORG_AUTO_ADD_USERS` | -| Hide personal workspaces | `Hide Personal Workspaces` | `env.HIDE_PERSONAL_WORKSPACES` and `env.OH_WEB_CLIENT_FEATURE_FLAGS_HIDE_PERSONAL_WORKSPACES` | -| Default organization name | Not available | `env.OPENHANDS_DEFAULT_ORG_NAME` | -| User provisioning | `Enable OEM User Creation Flow` | `userProvisioning.enabled` | +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. - The default organization options are under **Default OpenHands Organization**. 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). + 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. + + + 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. + + 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" @@ -41,31 +63,11 @@ configuration. The Admin Console options are applied to the Helm chart's `env` v enabled: true ``` - Hiding personal workspaces is only safe together with the default organization and automatic membership, - because users need a workspace to land in. The Admin Console enforces this. Helm does not. + 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. -## Defaults - -Out of the box, none of these settings are on. Every user has only a personal organization, and an installation -that predates these settings keeps working that way until you change them. - -| Setting | Default when not configured | Default in the Admin Console | -|---|---|---| -| Default organization | Off | Unchecked | -| Add users automatically | Off | Checked, once the default organization is enabled | -| Hide personal workspaces | Off | Checked, once the default organization is enabled | -| Default organization name | `Enterprise Org` | Not available | -| User provisioning | Off | Unchecked | - - - On a VM install, checking `Enable Default OpenHands Organization` also 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. - - ## Default Organization Turning on `Enable Default OpenHands Organization` makes OpenHands set up the default organization the next time From edaecd2c7317faaa0eb633d1f16f92dc0f8dd1e5 Mon Sep 17 00:00:00 2001 From: openhands Date: Thu, 15 Oct 2026 13:46:10 +0000 Subject: [PATCH 6/6] Use personal workspace consistently instead of personal organization Co-authored-by: openhands --- .../cloud/organizations/configuring-organizations.mdx | 2 +- openhands/usage/cloud/organizations/overview.mdx | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/openhands/usage/cloud/organizations/configuring-organizations.mdx b/openhands/usage/cloud/organizations/configuring-organizations.mdx index 2f671383c..92852df52 100644 --- a/openhands/usage/cloud/organizations/configuring-organizations.mdx +++ b/openhands/usage/cloud/organizations/configuring-organizations.mdx @@ -10,7 +10,7 @@ description: Settings that control the default organization, personal workspaces ## Settings and Defaults -Out of the box, none of these settings are on. Every user has only a personal organization, and an installation +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 diff --git a/openhands/usage/cloud/organizations/overview.mdx b/openhands/usage/cloud/organizations/overview.mdx index d6e7be3f8..c77b2cd7b 100644 --- a/openhands/usage/cloud/organizations/overview.mdx +++ b/openhands/usage/cloud/organizations/overview.mdx @@ -26,15 +26,15 @@ Organizations provide the following capabilities: ## Key Concepts -### Personal and Team Organizations +### Personal Workspaces and Team Organizations -Every user has a **personal organization**, created automatically the first time they sign in. It is a private -workspace for one person. Conversations, secrets, API keys, and automations created while it is the current +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 organization and any number of team +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 @@ -68,7 +68,7 @@ the [Super Admins and Organizations](/cookbook/org-admin) cookbook example. 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 -organizations so it is the only workspace users see. +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,