---
title: "Create Environment"
method: POST
path: "/v1/environments"
tags: ["Environments"]
---

# Create Environment

`POST /v1/environments`

Creates a new team or personal environment. `repository_id` and `repository_set_id` are mutually exclusive; both may be omitted for an unbound environment that can back repo-less workspaces. Personal environments are visible only to the authenticated user. When `scope=user` and `source_environment_id` references a team environment, the personal environment inherits from that source instead of copying it.

## Request body

- CreateEnvironmentRequest — Request body for creating a new environment.
  - `name` string, required — Human-readable name (must be unique within the selected scope)
  - `description` string, nullable — Optional description
  - `scope` 'org' | 'user' — `org` creates a team environment. `user` creates a personal environment visible only to the authenticated user.
  - `source_environment_id` string, uuid, nullable — Optional source. Team environments copy from the source on create. Personal environments inherit from a team source and keep inherited config locked.
  - `repository_id` string, uuid, nullable — Bind to this repository. Mutually exclusive with `repository_set_id`.
  - `repository_set_id` string, uuid, nullable — Bind to this repository set. Mutually exclusive with `repository_id`.
  - `system_prompt` string, nullable — Optional system prompt prepended to the coding agent.
  - `mobile_testing_enabled` boolean — Enable mobile testing. Only valid for team environments on Team and Enterprise plans; otherwise returns `PLAN_UPGRADE_REQUIRED`.

## Response `201`

Environment created

- EnvironmentResponse
  - `environment` Environment, required — An environment — the config bundle workspaces are created from. Holds an optional repository binding plus the runtime variables, files, skills, MCPs, and warm hook applied to every workspace built from it. Every organization has a singleton Global environment (`is_global: true`) whose values are layered onto every other environment. Personal environments have `user_id` set and are visible only to their owner. Source-backed personal environments expose source-derived repository binding and system prompt values while keeping the source link in `source_environment_id`.
    - `id` string, uuid, required — Unique identifier
    - `organization_id` string, uuid, required — Owning organization
    - `user_id` string, uuid, nullable, required — Owning user for personal environments. Null for team environments.
    - `name` string, required — Human-readable name
    - `description` string, nullable, required — Optional description
    - `is_global` boolean, required — True for the org's singleton Global environment, whose values apply to every workspace. Global envs cannot be deleted, cannot be edited via PATCH, and have no repository binding.
    - `repository_id` string, uuid, nullable, required — Bound repository ID. Mutually exclusive with `repository_set_id`. Both null = unbound repo-less workspace.
    - `repository_set_id` string, uuid, nullable, required — Bound repository set ID. Mutually exclusive with `repository_id`.
    - `system_prompt` string, nullable, required — Optional system prompt prepended to every workspace's coding agent.
    - `mobile_testing_enabled` boolean, required — Whether workspaces from this environment receive mobile simulator access. Available on Team and Enterprise plans and configurable only on team environments.
    - `personal_preferences` string, nullable, required — User-authored instructions appended after the (inherited) system prompt. Only settable on personal environments, and editable even when source-backed.
    - `source_environment_id` string, uuid, nullable, required — Source team environment for source-backed personal environments. Null for standalone personal environments and team environments.
    - `variable_count` integer — Number of variables attached to this environment
    - `file_count` integer — Number of files
    - `skill_count` integer — Number of enabled skills
    - `mcp_count` integer — Number of MCPs
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `400` — Bad request - Missing or invalid parameters
- `401` — Unauthorized - Invalid or missing API key
- `409` — An environment with this name already exists
- `500` — Internal server error

---

[API](https://skmtc.net/tryreplicas/apis/replica-api.md) · [All operations](https://skmtc.net/tryreplicas/apis/replica-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryreplicas/replica-api/versions/aa3b4c932f7a/schema)