Skip to main content
These settings apply to self-hosted OpenHands Enterprise, not to OpenHands Cloud (SaaS). For the concepts behind them, see the Organizations Overview.

​
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.
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.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.

​
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.
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, see 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.
1

Find a Super Admin

Only a super admin can create organizations. Use the Super Admins and Organizations example to find yours and grant the role to more people.
2

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.
3

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.
4

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.

​
Next Steps