> For the complete documentation index, see [llms.txt](https://docs.durohub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.durohub.com/account-management/sandbox-organizations.md).

# Sandbox Organizations

A sandbox organization is a full organization that inherits its parent organization's plan and entitlements. It gives admins a real organization to experiment in — practice SSO setup, model libraries differently, run demos or training — without touching production. A sandbox behaves like any other organization (its own libraries, members, and features), but it is created as a child of an existing **production** organization and does **not** consume an organization-creation grant.

Each parent can host a limited number of sandboxes, set by its subscription's `sandbox_orgs` entitlement. Whether sandbox creation is available at all depends on that entitlement.

### GraphQL surface

```graphql
# true when the organization is a sandbox
type Organization {
  # ...existing fields
  isSandbox: Boolean!
}

# The signed-in user's namespace reports what they may create
type UserQueryNamespace {
  # ...existing fields
  orgCreationOptions: OrgCreationOptions!
}

type OrgCreationOptions {
  # true when the user holds a live organization-creation grant
  hasPendingGrant: Boolean!
  # Production organizations the user may create a sandbox under
  sandboxParents: [SandboxParentOption!]!
}

type SandboxParentOption {
  organizationId: ID!
  name: String!
  slug: String!
  sandboxLimit: Int!
  sandboxUsed: Int!
  headroom: Int!
}

# Point at a production parent to create a sandbox; omit it to create a production organization
input CreateOrganizationInput {
  # ...existing fields
  parentOrganizationId: ID
}

type OrganizationMutationNamespace {
  # ...existing methods
  archiveSandboxOrganization(id: ID!): Organization!
}
```

### Deciding what to create

Query `orgCreationOptions` to learn whether the current user can create a production organization (`hasPendingGrant`), and which production organizations they can create a sandbox under:

```graphql
query {
  user {
    orgCreationOptions {
      hasPendingGrant
      sandboxParents {
        organizationId
        name
        slug
        sandboxLimit
        sandboxUsed
        headroom
      }
    }
  }
}
```

`sandboxParents` lists every active production organization the user is the **Site Admin** of, including parents with no headroom left, so you can show why another sandbox cannot be added. `headroom` is the number of sandboxes the parent can still take (`sandboxLimit` minus `sandboxUsed`, never below zero); only a parent with `headroom` above zero can take a new one. The list is empty when sandbox creation is not available.

{% hint style="info" %}
`orgCreationOptions` is the authoritative per-parent check. [`me.canCreateOrg`](https://docs.durohub.com/getting-started/current-user.md#checking-whether-a-user-can-create-an-organization) is a cheaper hint that does not check headroom.
{% endhint %}

### Creating a sandbox

Pass `parentOrganizationId` when creating an organization to make it a sandbox child of that parent. The parent must be an active production organization you are the Site Admin of, with a subscription.

```graphql
mutation {
  organization {
    create(input: {
      name: "Acme Sandbox"
      parentOrganizationId: "parent-org-uuid"
    }) {
      id
      isSandbox
    }
  }
}
```

The request can fail with:

| Code                        | When                                                                                     |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `SANDBOX_PARENT_FORBIDDEN`  | The parent cannot host a sandbox, or you are not its Site Admin.                         |
| `ENTITLEMENT_LIMIT_REACHED` | The parent has no sandbox headroom left. `extensions.entitlement` is `sandbox_orgs`.     |
| `SANDBOX_NAME_TAKEN`        | Another organization in the same company already has this name. Choose a different name. |
| `SANDBOX_NOT_AVAILABLE`     | Sandbox creation is not currently available.                                             |

See [Sandbox Organization Errors](https://docs.durohub.com/advanced-topics/error-handling.md#sandbox-organization-errors) for the full payloads.

### Archiving a sandbox

Archiving a sandbox frees its slot: only non-archived sandboxes count against the parent's `sandbox_orgs` quota. The Site Admin of the sandbox or of its parent can archive it. The mutation only archives sandbox organizations; any other target is rejected with `SANDBOX_ARCHIVE_FORBIDDEN`.

```graphql
mutation {
  organization {
    archiveSandboxOrganization(id: "sandbox-org-uuid") {
      id
    }
  }
}
```

{% hint style="warning" %}
Sandboxes cannot be nested — only a production organization can be a parent. A sandbox can never create another sandbox.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.durohub.com/account-management/sandbox-organizations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
