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

# Create environment

`POST /api/v1/environments`

Creates a server-owned environment definition in the environment catalog.
REST environment requests only accept inline Dockerfile content; local
Dockerfile paths are supported by workflow/settings files but rejected
by this API.

## Request body

- CreateEnvironmentRequest — Request body for creating a server-managed environment.
  - `id` string, required
  - `provider` string, required — Sandbox provider kind. `local`, `docker`, and `daytona` are bundled with the server; any other value names a sandbox-driver plugin configured under `server.sandbox.providers.<kind>`.
  - `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 `201`

Environment created

- Environment — Public server-managed environment definition.
  - `id` string, required
  - `revision` string, required — Stable revision used with `If-Match` for optimistic concurrency.
  - `provider` string, required — Sandbox provider kind. `local`, `docker`, and `daytona` are bundled with the server; any other value names a sandbox-driver plugin configured under `server.sandbox.providers.<kind>`.
  - `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
- `409` — Environment id already exists
- `422` — Environment failed domain validation
- `500` — Environment store operation failed

## Changes

- **2026-09-10** `478e995209e9` — 4 breaking, 4 info
  - removed the enum value `daytona` of the request property `provider`
  - removed the enum value `docker` of the request property `provider`
  - removed the enum value `local` of the request property `provider`
  - added the pattern `^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$` to the request property `provider`
  - …4 more
- **2026-09-09** `64d7e2ed03af` — 1 breaking, 3 warning, 5 info
  - request property `provider` was restricted to a list of enum values
  - added the new `daytona` enum value to the `provider` response property for the response status `201`
  - added the new `docker` enum value to the `provider` response property for the response status `201`
  - added the new `local` enum value to the `provider` response property for the response status `201`
  - …5 more
- **2026-09-08** `9aaa5d3a64cc` — 4 breaking, 4 info
  - removed the enum value `daytona` of the request property `provider`
  - removed the enum value `docker` of the request property `provider`
  - removed the enum value `local` of the request property `provider`
  - added the pattern `^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$` to the request property `provider`
  - …4 more
- **2026-06-14** `fbe22f7c5ef7` — 2 info
  - added the new optional request property `cwd`
  - added the optional property `cwd` to the response with the `201` status
- …earlier changes not shown

[Full history](https://skmtc.dev/fabro-sh/apis/fabro-run-api/changes/api/v1/environments/post.md)

---

[API](https://skmtc.dev/fabro-sh/apis/fabro-run-api.md) · [All operations](https://skmtc.dev/fabro-sh/apis/fabro-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fabro-sh/apis/fabro-run-api/revisions/1258a4cf33df?raw)