gitpod.v1.AccountService10

gitpod.v1.AgentSecurityService1

gitpod.v1.AgentService24

gitpod.v1.BaseSnapshotService6

gitpod.v1.BillingService48

gitpod.v1.EditorService3

gitpod.v1.EnvironmentAutomationService18

gitpod.v1.EnvironmentService16

gitpod.v1.ErrorsService1

gitpod.v1.EventService3

gitpod.v1.GatewayService1

gitpod.v1.GroupService14

gitpod.v1.IdentityService3

gitpod.v1.InsightsService6

gitpod.v1.IntegrationService13

gitpod.v1.NotificationService5

gitpod.v1.OnaIntelligenceService5

gitpod.v1.OrganizationService48

gitpod.v1.PrebuildService11

gitpod.v1.ProjectService15

gitpod.v1.RunnerConfigurationService22

gitpod.v1.RunnerInteractionService33

gitpod.v1.RunnerManagerService6

gitpod.v1.RunnerService16

gitpod.v1.SecretService5

gitpod.v1.SecurityService5

gitpod.v1.ServiceAccountService10

gitpod.v1.SessionService9

gitpod.v1.TeamService8

gitpod.v1.UsageService18

gitpod.v1.UserService14

gitpod.v1.WebhookService8

gitpod.v1.WorkflowService16

gitpod.v1.EnvironmentService

CreateEnvironmentFromProject

Creates an environment from an existing project configuration and starts it.

This method uses project settings as defaults but allows overriding specific configurations. Project settings take precedence over default configurations, while custom specifications in the request override project settings.

Examples

Create with project defaults:

Creates an environment using all default settings from the project configuration.
```
projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
```

Create with custom compute resources:

Creates an environment from project with custom machine class and timeout settings.

projectId: "b0e12f6c-4c67-429d-a4a6-d9838b5da047"
spec:
  machine:
    class: "d2c94c27-3b76-4a42-b88c-95a85e392c68"
  timeout:
    disconnected: "14400s"  # 4 hours in seconds

post/gitpod.v1.EnvironmentService/CreateEnvironmentFromProject

Request body

annotationsobject

annotations are key/value pairs attached to the environment metadata.

namestring nullable

name is a user-defined identifier for the environment. If not specified, the system will generate a name.

projectIdstring uuid

sessionIdstring uuid

session_id is the ID of the session this environment belongs to. If empty, a new session is created implicitly.

specGitpodV1EnvironmentSpec — unresolved $ref

Response

Success

Changes

Changed in 12 of the 18 revisions of this API.81695

Jul 30, 202644d50c2ac284311See the full diff
- ●
  removed the request property spec/secrets/items/credentialProxy/format
  request-property-removed
- ●
  removed the optional property environment/spec/secrets/items/credentialProxy/format from the response with the 200 status
  response-optional-property-removed
- ●
  added the new ENVIRONMENT_ROLE_BASE_SNAPSHOT_BUILD enum value to the environment/metadata/role response property for the response status 200
  response-property-enum-value-added
- ○
  added the new optional request property spec/kernelControlsConfig/veto/file
  new-optional-request-property
- ○
  added the new optional request property spec/secrets/items/sourceDetails
  new-optional-request-property
- ○
  added the new optional request property spec/securityPolicyId
  new-optional-request-property
- ○
  request property spec/kernelControlsConfig/veto/exec/denyBlockDevices deprecated
  request-property-deprecated
- ○
  added the optional property environment/metadata/pinnedByCreator to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/kernelControlsConfig/veto/file to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/secrets/items/sourceDetails to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/securityPolicyId to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/status/codex to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/status/content/git/changedFiles/items/oldPath to the response with the 200 status
  response-optional-property-added
- ○
  response property environment/spec/kernelControlsConfig/veto/exec/denyBlockDevices deprecated
  response-property-deprecated
This revision also has 24 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 2, 2026dabc0ff98cd723See the full diff
- ○
  added the new optional request property annotations
  new-optional-request-property
- ○
  added the new optional request property sessionId
  new-optional-request-property
- ○
  added the new optional request property spec/kernelControlsConfig/bpfDebugLevel
  new-optional-request-property
- ○
  added the new optional request property spec/kernelControlsConfig/veto/exec/denyBlockDevices
  new-optional-request-property
- ○
  added the new optional request property spec/kernelControlsConfig/veto/exec/resolveBareNames
  new-optional-request-property
- ○
  added the new optional request property spec/kernelControlsConfig/veto/exec/untouchable
  new-optional-request-property
- ○
  added the new optional request property spec/kernelControlsConfig/veto/exec/watch
  new-optional-request-property
- ○
  added the new optional request property spec/machine/preferDualDisk
  new-optional-request-property
- ○
  added the new optional request property spec/ports/items/authNonce
  new-optional-request-property
- ○
  added the new optional request property spec/secrets/items/credentialProxy
  new-optional-request-property
- ○
  added the optional property environment/metadata/lockdownAt to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/metadata/sessionId to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/kernelControlsConfig/bpfDebugLevel to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/kernelControlsConfig/veto/exec/denyBlockDevices to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/kernelControlsConfig/veto/exec/resolveBareNames to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/kernelControlsConfig/veto/exec/untouchable to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/kernelControlsConfig/veto/exec/watch to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/machine/preferDualDisk to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/ports/items/authNonce to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/secrets/items/credentialProxy to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/status/environmentUrls/vmLiveUsage to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/status/machine/dualDisk to the response with the 200 status
  response-optional-property-added
- ○
  removed the PRINCIPAL_AGENT_EXECUTION enum value from the environment/metadata/creator/principal response property for the response status 200
  response-property-enum-value-removed
Feb 18, 20261923b5d386552See the full diff
- ○
  added the new optional request property spec/kernelControlsConfig/veto/exec/action
  new-optional-request-property
- ○
  added the optional property environment/spec/kernelControlsConfig/veto/exec/action to the response with the 200 status
  response-optional-property-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Feb 11, 2026b97dcde8412849See the full diff
- ●
  added the new ADMISSION_LEVEL_CREATOR_ONLY enum value to the environment/spec/admission response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ADMISSION_LEVEL_CREATOR_ONLY enum value to the environment/spec/ports/items/admission response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ADMISSION_LEVEL_ORGANIZATION enum value to the environment/spec/admission response property for the response status 200
  response-property-enum-value-added
- ●
  added the new ADMISSION_LEVEL_ORGANIZATION enum value to the environment/spec/ports/items/admission response property for the response status 200
  response-property-enum-value-added
- ○
  added the new optional request property name
  new-optional-request-property
- ○
  added the new optional request property spec/kernelControlsConfig
  new-optional-request-property
- ○
  added the new optional request property spec/secrets/items/scope
  new-optional-request-property
- ○
  added the new ADMISSION_LEVEL_CREATOR_ONLY enum value to the request property spec/admission
  request-property-enum-value-added
- ○
  added the new ADMISSION_LEVEL_CREATOR_ONLY enum value to the request property spec/ports/items/admission
  request-property-enum-value-added
- ○
  added the new ADMISSION_LEVEL_ORGANIZATION enum value to the request property spec/admission
  request-property-enum-value-added
- ○
  added the new ADMISSION_LEVEL_ORGANIZATION enum value to the request property spec/ports/items/admission
  request-property-enum-value-added
- ○
  added the optional property environment/spec/kernelControlsConfig to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/secrets/items/scope to the response with the 200 status
  response-optional-property-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jan 21, 20262423c089f28024See the full diff
- ▲
  removed subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 from the spec/automationsFile/triggerFilter/items/ request property oneOf list
  request-property-one-of-removed
- ▲
  added subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 subschema #6 to the environment/spec/automationsFile/triggerFilter/items/ response property oneOf list for the response status 200
  response-property-one-of-added
- ○
  added the new optional request property spec/automationsFile/triggerFilter/items/beforeSnapshot
  new-optional-request-property
- ○
  added subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 subschema #6 to the spec/automationsFile/triggerFilter/items/ request property oneOf list
  request-property-one-of-added
- ○
  added the optional property environment/spec/automationsFile/triggerFilter/items/beforeSnapshot to the response with the 200 status
  response-optional-property-added
- ○
  removed subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 from the environment/spec/automationsFile/triggerFilter/items/ response property oneOf list for the response status 200
  response-property-one-of-removed
Dec 15, 2025d62ef4b9187c3618See the full diff
- ▲
  the spec/ports/items/port request property's min was increased to 1024.00
  request-property-min-increased
- ▲
  removed subschema #1 subschema #2 subschema #3 subschema #4 from the spec/secrets/items/ request property oneOf list
  request-property-one-of-removed
- ▲
  added subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 to the environment/spec/secrets/items/ response property oneOf list for the response status 200
  response-property-one-of-added
- ●
  added the new CLONE_TARGET_MODE_REMOTE_TAG enum value to the environment/spec/content/initializer/specs/items/git/targetMode response property for the response status 200
  response-property-enum-value-added
- ●
  added the new CONTENT_PHASE_UNAVAILABLE enum value to the environment/status/automationsFile/phase response property for the response status 200
  response-property-enum-value-added
- ●
  added the new CONTENT_PHASE_UNAVAILABLE enum value to the environment/status/content/phase response property for the response status 200
  response-property-enum-value-added
- ●
  added the new CONTENT_PHASE_UNAVAILABLE enum value to the environment/status/secrets/items/phase response property for the response status 200
  response-property-enum-value-added
- ●
  added the new CONTENT_PHASE_UNAVAILABLE enum value to the environment/status/sshPublicKeys/items/phase response property for the response status 200
  response-property-enum-value-added
- ●
  added the new PRINCIPAL_AGENT_EXECUTION enum value to the environment/metadata/creator/principal response property for the response status 200
  response-property-enum-value-added
- ○
  added the new optional request property spec/automationsFile/triggerFilter
  new-optional-request-property
- ○
  added the new optional request property spec/devcontainer/lifecycleStage
  new-optional-request-property
- ○
  added the new optional request property spec/ports/items/protocol
  new-optional-request-property
- ○
  added the new optional request property spec/secrets/items/apiOnly
  new-optional-request-property
- ○
  added the new optional request property spec/workflowActionId
  new-optional-request-property
- ○
  added the new CLONE_TARGET_MODE_REMOTE_TAG enum value to the request property spec/content/initializer/specs/items/git/targetMode
  request-property-enum-value-added
- ○
  added subschema #1 subschema #2 subschema #3 subschema #4 subschema #5 to the spec/secrets/items/ request property oneOf list
  request-property-one-of-added
- ○
  added the optional property environment/metadata/prebuildId to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/metadata/role to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/automationsFile/triggerFilter to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/devcontainer/lifecycleStage to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/ports/items/protocol to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/secrets/items/apiOnly to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/workflowActionId to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/status/environmentUrls/ops to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/status/environmentUrls/supportBundle to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/status/machine/versions/amiId to the response with the 200 status
  response-optional-property-added
- ○
  removed subschema #1 subschema #2 subschema #3 subschema #4 from the environment/spec/secrets/items/ response property oneOf list for the response status 200
  response-property-one-of-removed
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jun 10, 2025ca9a49ac7fbb17See the full diff
- ●
  added the new PRINCIPAL_RUNNER_MANAGER enum value to the environment/metadata/creator/principal response property for the response status 200
  response-property-enum-value-added
- ○
  added the new optional request property spec/devcontainer/defaultDevcontainerImage
  new-optional-request-property
- ○
  added the new optional request property spec/secrets/items/id
  new-optional-request-property
- ○
  added the optional property environment/metadata/archivedAt to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/devcontainer/defaultDevcontainerImage to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec/secrets/items/id to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/status/automationsFile/warningMessage to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/status/secrets/items/id to the response with the 200 status
  response-optional-property-added
This revision also has 43 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Feb 21, 20253655d5ad0ac32116See the full diff
- ▲
  the spec request property type/format changed from / to object/
  request-property-type-changed
- ▲
  the environment response's property type/format changed from / to object/ for status 200
  response-property-type-changed
- ●
  removed gitpod.v1.EnvironmentSpec from the spec request property allOf list
  request-property-all-of-removed
- ○
  added the new optional request property spec/admission
  new-optional-request-property
- ○
  added the new optional request property spec/automationsFile
  new-optional-request-property
- ○
  added the new optional request property spec/content
  new-optional-request-property
- ○
  added the new optional request property spec/desiredPhase
  new-optional-request-property
- ○
  added the new optional request property spec/devcontainer
  new-optional-request-property
- ○
  added the new optional request property spec/machine
  new-optional-request-property
- ○
  added the new optional request property spec/ports
  new-optional-request-property
- ○
  added the new optional request property spec/secrets
  new-optional-request-property
- ○
  added the new optional request property spec/specVersion
  new-optional-request-property
- ○
  added the new optional request property spec/sshPublicKeys
  new-optional-request-property
- ○
  added the new optional request property spec/timeout
  new-optional-request-property
- ○
  added the optional property environment/metadata to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/spec to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property environment/status to the response with the 200 status
  response-optional-property-added
- ○
  removed gitpod.v1.Environment from the environment response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  added the required property environment/id to the response with the 200 status
  response-required-property-added
Feb 18, 2025cd6a05ae99d21See the full diff
- ●
  removed the optional property detail from the response with the default status
  response-optional-property-removed
Feb 18, 2025bef0e79f204c3See the full diff
- ○
  added the new optional request property spec/allOf[subschema #1: EnvironmentSpec]/devcontainer/allOf[subschema #1: DevContainer]/dotfiles
  new-optional-request-property
- ○
  added the optional property environment/allOf[subschema #1: Environment]/spec/allOf[subschema #1: EnvironmentSpec]/devcontainer/allOf[subschema #1: DevContainer]/dotfiles to the response with the 200 status
  response-optional-property-added
- ○
  the response property environment became required for the status 200
  response-property-became-required

Full history (12 revisions)