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

# Configuring Organizations

> 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 theme={null}
    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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.