---
title: "Replace environment"
method: PUT
path: "/api/v1/environments/{id}"
tags: ["Environments"]
---

# Replace environment

`PUT /api/v1/environments/{id}`

Replaces an environment definition when `If-Match` matches the current
environment revision. The path id is authoritative; the request body
omits `id`.

## Path parameters

- `id` string, required

## Headers

- `If-Match` string, required

## Request body

- ReplaceEnvironmentRequest — Request body for replacing a server-managed environment. The path id is authoritative.
  - `provider` 'local' | 'docker' | 'daytona', required — Desired environment provider.
  - `cwd` string, nullable — Local-provider command working directory for this environment. Docker and Daytona ignore this value.
  - `image` EnvironmentApiImageSettings, required — REST-safe environment image settings. Dockerfile sources are inline-only; local paths are rejected by the REST API.
    - `docker` string, nullable, required
    - `dockerfile` EnvironmentApiDockerfileSourceInline, required
      - `type` 'inline', required
      - `value` string, required
  - `resources` EnvironmentResourcesSettings, required
    - `cpu` integer, nullable, required
    - `memory` string, nullable, required
    - `disk` string, nullable, required
  - `network` EnvironmentNetworkSettings, required
    - `mode` 'allow_all' | 'block' | 'cidr_allow_list', required
    - `allow` string[], required
  - `lifecycle` EnvironmentLifecycleSettings, required
    - `preserve` boolean, required
    - `stop_on_terminal` boolean, required
    - `auto_stop` string, nullable, required
  - `labels` StringMap, required
  - `env` object, required

## Response `200`

Environment replaced

- Environment — Public server-managed environment definition.
  - `id` string, required
  - `revision` string, required — Stable revision used with `If-Match` for optimistic concurrency.
  - `provider` 'local' | 'docker' | 'daytona', required — Desired environment provider.
  - `cwd` string, nullable — Local-provider command working directory for this environment. Docker and Daytona ignore this value.
  - `image` EnvironmentApiImageSettings, required — REST-safe environment image settings. Dockerfile sources are inline-only; local paths are rejected by the REST API.
    - `docker` string, nullable, required
    - `dockerfile` EnvironmentApiDockerfileSourceInline, required
      - `type` 'inline', required
      - `value` string, required
  - `resources` EnvironmentResourcesSettings, required
    - `cpu` integer, nullable, required
    - `memory` string, nullable, required
    - `disk` string, nullable, required
  - `network` EnvironmentNetworkSettings, required
    - `mode` 'allow_all' | 'block' | 'cidr_allow_list', required
    - `allow` string[], required
  - `lifecycle` EnvironmentLifecycleSettings, required
    - `preserve` boolean, required
    - `stop_on_terminal` boolean, required
    - `auto_stop` string, nullable, required
  - `labels` StringMap, required
  - `env` object, required

## Other responses

- `400` — Malformed JSON request body, invalid environment id, or invalid revision header
- `404` — Environment not found
- `409` — Environment revision mismatch or protected environment conflict
- `422` — Environment failed domain validation
- `428` — Missing required `If-Match` header
- `500` — Environment store operation failed

---

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