General concepts > Primary and sandbox environments

Traditional CMSs often treat content as a one-off effort, which makes content management difficult to fit into existing development lifecycles.

Content environments make it easier for your development team to manage and maintain the content structure once your content has been published. Think of environments as code branches: they're great for testing, development and pre-production.

In short, environments ensure quick turnaround times and flexibility for developers — without interrupting the editorial workflow.

What's an environment?

By default, every project has one environment, called the primary environment, which is meant to be used for the regular editorial workflow. Additionally, developers can create multiple sandbox environments to safely test and experiment with changes in the content.

Sandbox environments start out as exact copies of one of the existing environments (i.e., the primary one). The process of creating a new sandbox from an existing environment is called forking.

Each environment is identified by a name (e.g., master) and stores the following information:

• Models

• Records

• Uploads

• Plugins

• The content navigation bar

• Configuration (locales, timezone settings, appearance, SEO preferences)

When making changes to any of the aforementioned entities in any environment, including the primary environment, the data in all other environments remains unaffected.

Creating a new sandbox environment

To manage all your project's environments, head over to the Project Settings > Environments section. To create a new sandbox starting from an existing environment, click on the contextual menu > Fork, and choose a name for the new environment.

DatoCMS will perform a deep copy of all the information contained inside the source and transfer it to the new sandbox.

Once there's at least one sandbox environment, developers will be able to switch environments using the top bar panel.

Editors will never see this panel due to a reduced set of permissions and will continue their editorial workflow in the primary environment as usual.

Promotion of sandbox environments

At any time, you can promote a sandbox environment to become the new primary environment. The old primary environment will be demoted to a sandbox environment, and content editors will immediately see the interface refresh. From that moment, they will only be able to see and make changes to the new primary environment.

To be updated when a sandbox gets promoted, you can set up a webhook listening to the "Environment Promote" event.

Renaming environments

At any time, you can change the name of an existing environment. This change won't impact those working on the CMS:

To be updated when a sandbox gets renamed, you can set up a webhook listening to the "Environment Update" event.

Forcing use of sandbox environments

Changes to a primary environment can be potentially disruptive, so we give you the ability to block any user from editing the primary schema or configuration.

You can do this by going to Project settings > Global properties and enabling "Force the use of sandbox environments". If enabled, no user can edit the primary environment and make changes to its schema and configuration, regardless of their role.