# Create environment

`POST /v1/projects/{project}/environments`, operation `environments.CreateEnvironment`

Creates an environment and starts it. It is PROVISIONING until it runs.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `project` | path | Yes | `string` | The project's ID. |
| `requestId` | query | No | `string (uuid)` | Makes retries safe: creating again with the same ID in the project returns the environment the first request created, rather than another. |
| `validateOnly` | query | No | `boolean` | Checks the environment, and the quotas it would take, without creating it. |

## Request body

Content-Type: `application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `diskGib` | `integer (int32)` | No | The disk in GiB, from 10 to 500, and at most what the project's policies allow; 20 unless set. It never changes. |
| `displayName` | `string` | Yes | Name shown in user interfaces. |
| `idleTimeoutSeconds` | `integer (int64)` | No | How long, in seconds, the environment runs unused before kosem stops it: from 900 (15 minutes) to 14400 (4 hours), and an hour unless set, or the longest that the environments.maxIdleTimeout policy allows if less. |
| `image` | `string` | No | Container image reference, with a tag or digest; the configured kosem image unless set. The environment keeps it. |
| `memoryMib` | `integer (int32)` | No | Memory in MiB, from 1024 to 6656 for each vCPU, and at most what the environments.maxMemoryGib policy allows; 4096 for each vCPU unless set. It takes vcpus, and never changes. |
| `runnerPool` | `string` | No | A runner pool to run in, on hosts of the organization's or the project's own, rather than on kosem's machines: the project's own, or one its organization shares with it. Its vCPUs and disk take none of the organization's quotas of them. It never changes. |
| `stoppedTtlSeconds` | `integer (int64)` | No | How long, in seconds, the environment is kept stopped before kosem deletes it, with its disk: from 86400 (a day) to 2592000 (30 days). Unset, it is kept until someone deletes it, or, where the environments.maxStoppedTtl policy bounds it, as long as that allows. Setting it shorter than that takes environments.environments.delete. |
| `vcpus` | `integer (int32)` | No | Virtual CPUs, from 1 to 8, and at most what the environments.maxVcpus policy allows; 2 unless set, or the most that the policies allow if less. It never changes. |

## Responses

### 201

Created

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `createTime` | `string (date-time)` | Yes | When the environment was created. |
| `displayName` | `string` | Yes | Name shown in user interfaces. |
| `idleTimeoutSeconds` | `integer (int64)` | Yes | How long, in seconds, the environment runs unused before kosem stops it, keeping its disk; 0 if kosem never does. Unused is since lastUsedTime, with no background job running whose end its owner is told of: a job that nobody waits for, such as a server, stops with it. |
| `image` | `string` | Yes | Container image reference, with a tag or digest, which supplies the environment's OS, packages and tools; its entrypoint and command are not run. The environment keeps it; a digest makes restarts reproducible. |
| `lastUsedTime` | `string (date-time)` | No | When the environment was last used: when its owner last started it, ran a command in it or reached its files, or a command last ran in it for a caller; absent until it is used. A background job that runs on in it doesn't use it. |
| `name` | `string` | Yes | Resource name, projects/{project_id}/environments/{environment_id}. |
| `owner` | `string` | Yes | The principal that owns the environment, such as an agent, agent:{agent_id}, which alone runs commands in it and makes and starts it as it needs to; empty for environments that people create. People may still stop and delete it. |
| `runner` | `string` | No | The runner of its pool that holds its disk, once kosem placed it. |
| `runnerPool` | `string` | No | The runner pool it runs in, on hosts of its organization's or its project's own; absent on kosem's machines. |
| `runningJobs` | `integer (int32)` | No | How many background jobs run in the environment, such as servers and builds that its owner left running, as the environment last said; 0 unless it is RUNNING. Each runs until it ends, its owner ends it or the environment stops. |
| `size` | `EnvironmentSize` | Yes | How large the environment and its disk are. |
| `size.diskGib` | `integer (int32)` | Yes | The disk in GiB. |
| `size.memoryMib` | `integer (int32)` | Yes | Memory in MiB. |
| `size.vcpus` | `integer (int32)` | Yes | Virtual CPUs. |
| `state` | `string` | Yes | Where the environment is in its lifecycle: PROVISIONING while its disk and compute are made, RUNNING, STOPPING while its compute is removed, STOPPED with only its disk, STARTING again on its disk, and DELETING with its disk. Values: `PROVISIONING`, `RUNNING`, `STOPPING`, `STOPPED`, `STARTING`, `DELETING`. |
| `stateReason` | `string` | Yes | What the environment waits for, such as capacity, or what keeps it from getting there, which it keeps trying past. |
| `stoppedTtlSeconds` | `integer (int64)` | Yes | How long, in seconds, the environment is kept stopped before kosem deletes it, with its disk; 0 if it is kept until someone deletes it. |
| `updateTime` | `string (date-time)` | Yes | When the environment was last changed. |

### default

Error

Base URL: `https://api.kosem.ai`. See [API conventions](https://docs.kosem.ai/reference/api-conventions.md) for authentication, pagination and errors, and [https://docs.kosem.ai/openapi.yaml](https://docs.kosem.ai/openapi.yaml) for the full OpenAPI document.