---
title: "(-- api-linter: core::0133::method-signature=disabled aip.dev/not-precedent: Method signature includes auto_run field which is a non-standard field for immediate execution workflow. --) Creates a new process."
method: POST
path: "/v1/{parent}/processes"
tags: ["ProcessService"]
---

# (-- api-linter: core::0133::method-signature=disabled aip.dev/not-precedent: Method signature includes auto_run field which is a non-standard field for immediate execution workflow. --) Creates a new process.

`POST /v1/{parent}/processes`

## Request

- Base URL: `https://docs.h2o.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.h2o.ai/v1/{parent}/processes`
- Auth: none declared
- TypeScript: <https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto/docs/v1/:parent/processes/post.ts> (a function with typed inputs; its response is checked against the schema)

Authorization: Only the creator of the parent SandboxEngine is allowed to call this method.

## Path parameters

- `parent` string, required

## Query parameters

- `processId` string
- `autoRun` boolean

## Request body

- V1Process: Process represents a command executed in the sandbox.
  - `name` string
  - `command` string, required: Required. The command that will be executed.
  - `args` string[]: Optional. The arguments for the command.
  - `workingDirectory` string: Optional. The working directory for the process. All paths are rooted at the sandbox filesystem root. The path must start with a forward slash (e.g., "/workspace"). If empty, defaults to the sandbox root directory ("/").
  - `environmentVariables` object: Optional. A map of environment variables to set for the process. If a variable name exists in both environment_variables and secret_environment_variables, the secret value takes precedence.
  - `secretEnvironmentVariables` object: Optional. A map of environment variables populated from H2O Secure Store secrets. The key is the environment variable name, and the value contains the secret configuration including the secret version resource name. These secret-based environment variables will override any variables with the same name specified in the environment_variables field. Example: { "API_TOKEN": { "secret_version": "workspaces/my-workspace/secrets/api-key/versions/latest" } }
  - `state` 'STATE_UNSPECIFIED' | 'STATE_PENDING' | 'STATE_RUNNING' | 'STATE_SUCCEEDED' | 'STATE_FAILED': The state of the process. - STATE_UNSPECIFIED: The state is not specified. - STATE_PENDING: The process has been created but has not yet started execution. This is the initial state after a successful `CreateProcess` call. Use `StartProcess` method to begin execution. - STATE_RUNNING: The process is currently executing. - STATE_SUCCEEDED: The process completed successfully, typically with an exit code of 0. - STATE_FAILED: The process terminated with an error, typically with a non-zero exit code or due to an external signal.
  - `exitCode` integer: Output only. The exit code of the process.
  - `createTime` string, date-time: Output only. The time the process was created.
  - `startTime` string, date-time, nullable: Output only. The time the process actually started execution. This is set when the process transitions to STATE_RUNNING.
  - `endTime` string, date-time, nullable: Output only. The time the process finished.

## Response `200`

A successful response.

- V1CreateProcessResponse: Response for creating a process.
  - `process` V1Process: Process represents a command executed in the sandbox.
    - `name` string
    - `command` string, required: Required. The command that will be executed.
    - `args` string[]: Optional. The arguments for the command.
    - `workingDirectory` string: Optional. The working directory for the process. All paths are rooted at the sandbox filesystem root. The path must start with a forward slash (e.g., "/workspace"). If empty, defaults to the sandbox root directory ("/").
    - `environmentVariables` object: Optional. A map of environment variables to set for the process. If a variable name exists in both environment_variables and secret_environment_variables, the secret value takes precedence.
    - `secretEnvironmentVariables` object: Optional. A map of environment variables populated from H2O Secure Store secrets. The key is the environment variable name, and the value contains the secret configuration including the secret version resource name. These secret-based environment variables will override any variables with the same name specified in the environment_variables field. Example: { "API_TOKEN": { "secret_version": "workspaces/my-workspace/secrets/api-key/versions/latest" } }
    - `state` 'STATE_UNSPECIFIED' | 'STATE_PENDING' | 'STATE_RUNNING' | 'STATE_SUCCEEDED' | 'STATE_FAILED': The state of the process. - STATE_UNSPECIFIED: The state is not specified. - STATE_PENDING: The process has been created but has not yet started execution. This is the initial state after a successful `CreateProcess` call. Use `StartProcess` method to begin execution. - STATE_RUNNING: The process is currently executing. - STATE_SUCCEEDED: The process completed successfully, typically with an exit code of 0. - STATE_FAILED: The process terminated with an error, typically with a non-zero exit code or due to an external signal.
    - `exitCode` integer: Output only. The exit code of the process.
    - `createTime` string, date-time: Output only. The time the process was created.
    - `startTime` string, date-time, nullable: Output only. The time the process actually started execution. This is set when the process transitions to STATE_RUNNING.
    - `endTime` string, date-time, nullable: Output only. The time the process finished.

## Other responses

- `default`: An unexpected error response.

---

[API](https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto.md) - [All operations](https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto/llms.txt) - [OpenAPI document](https://skmtc.dev/h2o/apis/ai-h2o-engine-sandbox-v1-filesystem-proto/revisions/297cfadc1d39?raw)