> ## Documentation Index
> Fetch the complete documentation index at: https://docs.domesystems.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

> Create tenants and workspaces, select a CLI context, or provision a disposable sandbox

export const environment = "An environment in Dome is the place platform work runs: a tenant for hard isolation, a workspace for day-to-day operations, and a CLI context that points tools at that workspace.";

<p>
  {environment}
</p>

## Overview

Dome nests environments under an organization. An organization contains tenants. A tenant contains workspaces. Agents, resources, Gateways, rules, Guards, Quotas, and audit events live in a workspace. Tenants isolate data. Workspaces separate teams and environments inside a tenant. Refer to [Scope Hierarchy](/concepts/platform/scopes) concept for isolation and rule inheritance.

Creating a tenant or workspace defines a durable boundary. A CLI context does not create a boundary. It selects which workspace subsequent CLI and MCP commands use. A sandbox creates a throwaway tenant or workspace for a try-out instead of a durable boundary.

The typical workflow is:

1. [Create a tenant](#create-a-tenant) when you need a new hard isolation boundary.
2. [Create a workspace](#create-a-workspace) for the team or environment inside that tenant.
3. [Select a CLI context](#select-a-cli-context) so commands run against that workspace.
4. Optionally [scaffold a project](#scaffold-a-project) against the selected context.

Use a [sandbox](#provision-a-sandbox) when you need a disposable try-out instead of steps 1–2.

The sections below explain the attributes that shape a tenant or workspace at creation, and when a sandbox is the better path.

### Plans

Each tenant receives a plan that determines available features.

| Plan         | Use for                                   |
| ------------ | ----------------------------------------- |
| `sandbox`    | Experimentation and testing               |
| `essential`  | Core platform features                    |
| `managed`    | Dome-managed platform + gateway           |
| `enterprise` | Full feature set with SLA                 |
| `complete`   | Everything, including custom integrations |

You set the plan when you [create a tenant](#create-a-tenant).

### Join policies

`join_policy` controls how non-members enter a tenant or a workspace. Every tenant and every workspace carries its own value. The workspace policy is independent of its tenant's. New tenants and workspaces default to `invite_only` when the field is omitted at creation.

| `join_policy` | Who can enter                            |
| ------------- | ---------------------------------------- |
| `open`        | Verified-domain users join automatically |
| `request`     | Users request access. Admins approve     |
| `invite_only` | Admins must invite users (default)       |

You set `join_policy` when you [create a tenant](#create-a-tenant) or [create a workspace](#create-a-workspace).

### Sandboxes

A sandbox is a disposable shortcut. A workspace-scoped sandbox creates a throwaway workspace in the current tenant. A tenant-scoped sandbox creates a throwaway tenant, workspace, and one-time API key. Neither path replaces a durable tenant or workspace for production work.

Use a sandbox when you need a try-out. Use [create a tenant](#create-a-tenant) and [create a workspace](#create-a-workspace) when the boundary must persist.

## Requirements

Before you begin, authenticate the Dome CLI.

### Permissions

Tenant and workspace creation use org- and tenant-scoped roles. Each operation states the permission it requires.

For exhaustive flags, tool parameters, and endpoint contracts, refer to the [CLI](/cli/settings/tenants), [MCP](/reference/mcp/platform), and [API](/api/management/create-tenant) references.

| Default roles                             | Permission                 | Grants                                             |
| ----------------------------------------- | -------------------------- | -------------------------------------------------- |
| Org `admin` or `owner`                    | `tenant.manage`            | Create tenants or provision tenant sandboxes       |
| Tenant `admin`, `operator`, or `security` | Workspace / sandbox create | Create workspaces or provision workspace sandboxes |

## Create a tenant

Create a tenant under your organization when you need a hard isolation boundary. You can set [plan](#plans) and [join policy](#join-policies) in the same call.

<Callout icon="key">Requires org-level `tenant.manage` (held by org `admin` or `owner`).</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome tenants create --name acme-prod --plan managed
    dome tenants list
    ```

    | Flag       | Description                                                    |
    | ---------- | -------------------------------------------------------------- |
    | `--name`   | Tenant display name (required).                                |
    | `--plan`   | `essential` (default), `managed`, `enterprise`, or `complete`. |
    | `--org-id` | Target org. Defaults to the active context's org.              |

    <Callout icon="terminal">Reference: [`dome tenants create`](/cli/settings/tenants#create)</Callout>
  </Tab>

  <Tab title="MCP">
    Tools: `dome_tenants_create`, `dome_tenants_list`, `dome_tenants_get`

    <Callout icon="cpu">Reference: [`dome_tenants_create`](/reference/mcp/platform#tenants-create)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/CreateTenant
    {
      "name": "acme-prod",
      "plan": "managed",
      "join_policy": "request"
    }
    ```

    <Callout icon="code">Reference: [`CreateTenant`](/api/management/create-tenant)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Create a tenant" theme={"system"}
    Create a tenant named "acme-prod" on the managed plan.
    ```
  </Tab>
</Tabs>

## Create a workspace

Create a durable workspace for a team or environment inside a tenant. You can set [join policy](#join-policies) in the same call. List or delete workspaces as teams and projects change.

<Callout icon="key">Requires a tenant `admin`, `operator`, or `security` role.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome workspace create --name "payments-team"
    dome workspace list
    dome workspace delete <workspace-id>
    ```

    <Callout icon="terminal">Reference: [`dome workspace`](/cli/settings/workspace)</Callout>
  </Tab>

  <Tab title="MCP">
    Tools: `dome_workspaces_create`, `dome_workspaces_list`, `dome_workspaces_get`, `dome_workspaces_delete`

    <Callout icon="cpu">Reference: [`dome_workspaces_create`](/reference/mcp/workspaces)</Callout>
  </Tab>

  <Tab title="API">
    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/CreateWorkspace
    {
      "tenant_id": "{{TENANT_ID}}",
      "slug": "payments",
      "name": "Payments",
      "join_policy": "invite_only"
    }
    ```

    <Callout icon="code">Reference: [`CreateWorkspace`](/api/management/create-workspace)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Create a workspace" theme={"system"}
    Create a workspace named "payments-team".
    ```
  </Tab>
</Tabs>

## Select a CLI context

Sync after creating a tenant or workspace, then select the target so CLI and MCP commands run against that workspace.

```bash theme={"system"}
dome context sync
dome context list
dome context use production
dome context current
```

Use `workspace`, `tenant/workspace`, or `org/tenant/workspace` shorthand when names overlap.

## Provision a sandbox

Provision a sandbox for a disposable try-out instead of a durable [tenant](#create-a-tenant) or [workspace](#create-a-workspace). A workspace-scoped sandbox creates a throwaway workspace in the current tenant. A tenant-scoped sandbox creates a throwaway tenant, workspace, and one-time API key.

* **Workspace scope:** Disposable workspace in the current tenant.
* **Tenant scope:** Isolated tenant, workspace, and one-time API key.

<Callout icon="key">Workspace sandboxes require a tenant `admin`, `operator`, or `security` role. Tenant sandboxes require org `admin` or `owner`.</Callout>

<Tabs>
  <Tab title="CLI">
    ```bash theme={"system"}
    dome sandbox provision --scope=workspace --workspace-name my-sandbox
    dome sandbox provision --scope=tenant --tenant-name my-sandbox
    ```

    | Flag               | Default   | Description                     |
    | ------------------ | --------- | ------------------------------- |
    | `--scope`          | Required  | `tenant` or `workspace`.        |
    | `--tenant-name`    | Generated | Tenant suffix for tenant scope. |
    | `--workspace-name` | Generated | Workspace suffix.               |

    <Callout icon="terminal">Reference: [`dome sandbox`](/cli/developer/sandbox)</Callout>
  </Tab>

  <Tab title="MCP">
    Tool: `dome_provision_sandbox`

    ```json theme={"system"}
    {
      "scope": "workspace",
      "workspace_name": "my-sandbox"
    }
    ```

    <Callout icon="cpu">Reference: [`dome_provision_sandbox`](/reference/mcp/workspaces#provision-sandbox)</Callout>
  </Tab>

  <Tab title="API">
    Workspace scope:

    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/ProvisionSandboxWorkspace
    { "name": "my-sandbox" }
    ```

    Tenant scope:

    ```http theme={"system"}
    POST /dome.mgmt.v1.Management/ProvisionSandboxTenant
    {
      "org_id": "{{ORG_ID}}",
      "tenant_name": "my-sandbox",
      "workspace_name": "my-sandbox"
    }
    ```

    <Callout icon="code">Reference: [`ProvisionSandboxWorkspace`](/api/management/provision-sandbox-workspace)</Callout>
  </Tab>

  <Tab title="Agent">
    ```text title="Provision a sandbox" theme={"system"}
    Provision a workspace sandbox named "my-sandbox".
    ```
  </Tab>
</Tabs>

Tenant-scoped responses include the tenant, workspace, API key ID, and one-time API key secret. Sync context after the sandbox is ready.

## Scaffold a project

Create a starter project against the selected environment.

```bash theme={"system"}
dome quickstart my-agent-project
```

The command generates SDK setup, `dome.yaml`, environment placeholders, a Dockerfile, and starter Cedar rules.

## Next steps

* [Manage Access](/manage/access)
* [Configure Platform](/manage/settings)
* [Quickstart](/quickstart)