---
title: "corestack_environment_create"
url: https://docs.corefinity.com/mcp/tools/corestack_environment_create
type: tool
last_updated: 2026-11-13
feature: environments
related:
  - https://docs.corefinity.com/api/reference/environments/create-site-environment.md
  - https://docs.corefinity.com/guides/sites/environments-and-copies/create-an-environment.md
---
# corestack_environment_create

**Add an environment.** Add a staging environment to a site — empty, copied from another environment (or a snapshot of one), or from a Git branch — protected by HTTP authentication from birth. Scope: write. Also needs exec when reveal_to_agent is true. Long-running: answers with a task. The secret opens in the person's browser; set reveal_to_agent to true to receive it yourself (needs exec).

- Scope: `write`
- Also needs `exec` when the generated HTTP-auth login
- Runs as a task: yes
- Returns a secret only when `reveal_to_agent` is set

## When to use it

Add a staging environment to a site — empty, copied from another environment (or a snapshot of one), or from a Git branch — protected by HTTP authentication from birth.

When another change in the same region is starting at that moment, the create waits for it instead of being refused: it is accepted at once, its operation stays `pending` with the `status_label` "Waiting for another change to finish. This carries on by itself." (the words the Control Panel shows), and it carries on by itself within a few minutes. Do not send it again. The task's status reads the same words while it waits.

When its DNS records cannot be published yet (Cloudflare busy, or a platform DNS problem for Corefinity to fix), the create waits at its `dns` step instead of failing: its operation stays `pending` with the `status_label` "Waiting for DNS", and the task's status reads the same words. It is tried again every minute and goes on by itself; do not send it again.

When the region has no room for the new environment yet, the create is not refused: it is accepted, waits briefly for room (`capacity_being_added`, "Setting up your site. This can take a little longer.") and then continues by itself. Do not retry it or create it again; follow it as usual.

When the region has no room for the environment's disk yet, the environment waits at its first step until there is, however long that takes: it carries on by itself, so do not create it again.

While restoring anywhere is switched on, `source.type` `snapshot` with `snapshot_id` restores any snapshot of the company's websites (corestack_company_snapshots_list lists them) into the new environment, optionally `anonymise`d. A pinned token needs the snapshot's website covered as well. A snapshot that cannot be used (not ready, gone, past its retention, in another region) is `invalid_arguments` on `source.snapshot_id`, with the reason in its sentence.

If the environment's usual platform address is already used by another site, a standalone CoreStack environment is created on the next free one and its operation's `notes` say so (`platform_address_changed`, naming the address it uses); in a CoreCluster the create is refused `in_use` before anything is made, naming the address (choose another environment name, or contact Corefinity support). A name still held by an earlier create of the same environment that failed and is being cleaned up is waited for (up to about 20 seconds) instead of refused.

The new environment takes the PHP memory limit, upload size and max execution time of the environment it is made from (the clone source, else production). A value its size does not allow is changed to the nearest one it does: the completed task's result then carries `notes` (`[{code, text}]`, code `php_settings_clamped`) naming each setting changed and the value it has now, as corestack_site_operation_get does; corestack_php_settings_get on the environment carries the same note while those values still apply.

On a Shopware site, the new environment's search follows the environment it is made from (the clone source, a snapshot's own environment, else production): on if it is on there and the new size is Medium (8 GB) or larger, otherwise off. RabbitMQ always starts off. Its operation's `notes` say what happened: `search_carried` (search is on, as on the source), `search_stays_off` (the source has search on, but the size is under Medium (8 GB); choose Medium or larger, or switch search on later after a resize) and `search_not_carried` (the source's setting could not be read, so search starts off; the create is never refused for it — switch search on from the Shopware tab once it is ready). Nothing is said when the source has search off. Search does not change the environment's size or price.

A new environment never fails while its certificate is issued: the task keeps waiting, for up to a few hours, and corestack_site_operation_get says "Certificate on its way" (note `certificate_on_its_way`) until it carries on by itself.

A create that stops on a temporary problem (the platform, its DNS or its SSH gateway not ready in time) is tried again automatically, at most three times, a few minutes apart; follow it with corestack_site_progress_get or corestack_site_operation_get (`notes`) instead of creating it again.

An environment is never refused because the region's staging servers are not ready yet: it is created on the region's production servers instead. When the region's servers are not taking new environments for the moment (being set up or replaced), it is created and waits, then goes on by itself once they are; there is nothing to retry.

An environment that needs a new server in the region while changes to cluster capacity are paused for planned maintenance is not refused: it is created and waits for its server, then goes on by itself once the pause ends; there is nothing to retry.

When the PHP version the new environment would run is not open to new sites yet (just after a PHP security update, before its tested release is opened), the create is not refused if the environment keeps the site's own PHP version (`php_version` left out, or the one production runs) or if no PHP version of its list is open. It is accepted and waits for that version, then goes on by itself once it is open, never on another one. Its operation stays `pending` with the `status_label` "Waiting for PHP 8.3 to be available", corestack_site_get on the new environment's row returns `version_wait` with `kind` `php` and `php` (the version it waits for), and the task says "Waiting for PHP 8.3 to be available for new sites. Your environment will be set up as soon as it is." Do not create it again. An environment that waits can be deleted with corestack_environment_delete.

## Inputs

- `site_id` (integer, ≥ 1, required): Any row of the site.
- `name` (string, 1–40 characters, required)
- `slug` (string, 2–16 characters, pattern `^[a-z][a-z0-9-]{1,15}$`): Default from the name; unique among the site's environments.
- `tier` (string, up to 16 characters): A CoreCluster site's environment: a tier the package offers (default the production row's).
- `uat_size` (string, up to 16 characters): A CoreStack site's environment: a size from corestack_uat_sizes_list.
- `php_version` (string, up to 8 characters)
- `mariadb_version` (string, up to 8 characters): Default the site's own. A site on a version new sites are not offered keeps it for its environments (a Magento 2 site on MariaDB 12.3 gets environments on 12.3); any other version must be one new sites are offered. For a clone whose `scope` copies the database and that names no `snapshot_id`, the default is the clone source row's own version instead when the copy engine would refuse the site's own (a database of MariaDB 12.3 cannot be copied into a row running 11.8), so leave it out to copy a moved 12.3 environment onto 12.3.
- `node_major` (integer, 10–99): Default the source row's Node.js major (the clone source, else production), with its global packages, which a chosen major keeps.
- `node_acknowledge` (array of one of `eol`, up to 1 items): ["eol"] once the person knows the Node.js major the environment will run, chosen or inherited, is end of life (refused with ack_required otherwise).
- `source` (object, required)
  - `type` (one of `empty`, `clone`, `branch`, required; `snapshot` too while `restore_anywhere` is on)
  - `environment_id` (integer, ≥ 1): clone: the row to copy from.
  - `scope` (one of `files_db`, `db`, `files`): clone: what to copy (files_db).
  - `snapshot_id` (integer, ≥ 1): clone: a ready snapshot of that row; snapshot (only while `restore_anywhere` is on): any snapshot of the company's websites.
  - `branch` (string, up to 255 characters): branch: the Git branch.
  - `data_from_environment_id` (integer, ≥ 1): branch: copy the data of this row.
  - `auto_deploy` (boolean): branch: deploy each push.
- `anonymise` (boolean; only while `restore_anywhere` and `restore_anonymise` are on): With a snapshot source: anonymise the copied data.
- `varnish` (object; only while new Magento 2 sites are born with Varnish): Magento 2 only: `{enabled: true|false, version?}`. Left out, the environment follows the site: Varnish on at the site's version, or off when the person switched Varnish off on the site. `version` is one the site's Magento version allows (`version_unsupported` otherwise); a size with no room for Varnish is `varnish_too_small`.
- `reveal_to_agent` (boolean, default `false`): Return the secret to you instead of opening it in the person's browser. Needs exec.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "mariadb_version": {
      "maxLength": 8,
      "type": "string"
    },
    "name": {
      "maxLength": 40,
      "minLength": 1,
      "type": "string"
    },
    "node_acknowledge": {
      "description": "[\"eol\"] once the person knows the Node.js major the environment will run, chosen or inherited, is end of life (refused with ack_required otherwise).",
      "items": {
        "enum": [
          "eol"
        ],
        "type": "string"
      },
      "maxItems": 1,
      "type": "array"
    },
    "node_major": {
      "description": "Default the source row's Node.js major (the clone source, else production), with its global packages, which a chosen major keeps.",
      "maximum": 99,
      "minimum": 10,
      "type": "integer"
    },
    "php_version": {
      "maxLength": 8,
      "type": "string"
    },
    "reveal_to_agent": {
      "default": false,
      "description": "Return the secret to you instead of opening it in the person's browser. Needs exec.",
      "type": "boolean"
    },
    "site_id": {
      "description": "Any row of the site.",
      "minimum": 1,
      "type": "integer"
    },
    "slug": {
      "description": "Default from the name; unique among the site's environments.",
      "maxLength": 16,
      "minLength": 2,
      "pattern": "^[a-z][a-z0-9-]{1,15}$",
      "type": "string"
    },
    "source": {
      "additionalProperties": false,
      "properties": {
        "auto_deploy": {
          "description": "branch: deploy each push.",
          "type": "boolean"
        },
        "branch": {
          "description": "branch: the Git branch.",
          "maxLength": 255,
          "type": "string"
        },
        "data_from_environment_id": {
          "description": "branch: copy the data of this row.",
          "minimum": 1,
          "type": "integer"
        },
        "environment_id": {
          "description": "clone: the row to copy from.",
          "minimum": 1,
          "type": "integer"
        },
        "scope": {
          "description": "clone: what to copy (files_db).",
          "enum": [
            "files_db",
            "db",
            "files"
          ],
          "type": "string"
        },
        "snapshot_id": {
          "description": "clone: a ready snapshot of that row; snapshot: any snapshot of the company's websites.",
          "minimum": 1,
          "type": "integer"
        },
        "type": {
          "enum": [
            "empty",
            "clone",
            "branch",
            "snapshot"
          ],
          "type": "string"
        }
      },
      "required": [
        "type"
      ],
      "type": "object"
    },
    "tier": {
      "description": "A CoreCluster site's environment: a tier the package offers (default the production row's).",
      "maxLength": 16,
      "type": "string"
    },
    "uat_size": {
      "description": "A CoreStack site's environment: a size from corestack_uat_sizes_list.",
      "maxLength": 16,
      "type": "string"
    },
    "varnish": {
      "properties": {
        "enabled": {
          "type": "boolean"
        },
        "version": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "required": [
    "site_id",
    "name",
    "source"
  ],
  "type": "object"
}
```

## Refusals

- `ack_required`: the change needs the person's acknowledgements first; `required[]` lists them — confirm with the person, then call again with them.
- `invalid_arguments` on `source.environment_id` or `source.snapshot_id` (message: "This WordPress site is built with Bedrock, so it can only be copied to a site that deploys the same way. For a staging copy, use a branch (Git) environment."): a new environment made from a copy deploys manually, and a WordPress site built with Bedrock that deploys from Git is not copied into one. Create a branch environment instead (`source.type` `branch` with `data_from_environment_id` for the data). A copy of the database alone (`scope` `db`) is not refused for this.
- `snapshot_transfer` on `source.snapshot_id` (message: "A saved snapshot can be copied only to an environment on the same servers for now, and these two environments are on different servers. Copy the live environment instead, or restore the snapshot to an environment on the same servers."): with `source.type` `clone`, the new environment would run on other servers than the row the snapshot was taken from (a staging tier of its own, for example), and a saved snapshot is not copied across. corestack_site_clone_preview with no target lists it in `blockers` first. Tell the person they can copy the live environment instead (leave out `source.snapshot_id`), or restore the snapshot to an environment on the same servers. Nothing was created.
  Where it is switched on and both servers can, a saved snapshot on other servers is sent to the new environment's servers first instead: the answer's `source.transport` reads `sent_local`, and the new environment's size must leave room on those servers for the snapshot too. `snapshot_transfer` stays for a snapshot the servers cannot send.
- `invalid_arguments` on `uat_size` or `tier` (message beginning "The data being copied needs" or "The snapshot is larger than the space this environment has"): with `source.type` `clone` (a copy of files and database) or `snapshot`, the size asked for cannot hold the data; the message names the smallest size that does ("Choose Medium (100 GB) or larger."), or says no size here can. Ask the person which size to use and call again with it; nothing is ever chosen or bought for them. Nothing was created.
- `invalid_arguments` on `php_version` (message "PHP 8.4 isn't available for new sites yet"): the version named is not open to new sites while another version of the environment's list is. Leave `php_version` out to keep the site's own version, or name an open one. An environment restored from a snapshot (`source.type` `snapshot`) keeps the snapshot's own PHP version, so it waits for that version instead; a `clone` naming `source.snapshot_id` takes the site's (or the named) version and waits as above. Either way, the snapshot cannot be deleted until the environment has been made.
- `feature_off`: an input needs a feature that is switched off (for example `apply: "tonight"` while the maintenance window queue is switched off); leave that input out.
- `demo_keep_required`: the site or cluster is a free demo that is not kept yet, and an extra priced environment costs money: it starts once the demo is kept. Ask the person to keep it (`corestack_demo_keep`, or open `keep_url`); `change` names this change and what it would cost a month once kept.
- `managed_elsewhere` (message: "This site is managed by another control panel"): another control panel manages this
  site, so environments are added there. This is refused before anything else about the site is checked, as in the
  Control Panel and the API. Nothing was created.
- `rate_limited`: the person has added as many environments this minute as the limit allows (60 by default, shared with the Control Panel and the API; changing an environment's settings has a limit of its own). A create that is refused does not count. Wait `retry_after_seconds`, then call again.
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

## Example

```json
{
  "name": "corestack_environment_create",
  "arguments": {
    "site_id": 4211,
    "name": "Staging",
    "source": {
      "type": "empty"
    }
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_environment_create with site_id 4211, name Staging, source {"type":"empty"}. (Add an environment.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [POST /api/corestack/sites/{site}/environments](https://docs.corefinity.com/api/reference/environments/create-site-environment.md)
- Guide: [Create an environment](https://docs.corefinity.com/guides/sites/environments-and-copies/create-an-environment.md)
