# Start (/docs/api-reference/process/start)

<!-- agent-signals: reading_time_min: 3 · est_tokens: 2442 · updated: 2026-07-30 -->
Related: [CloseStdin](/docs/api-reference/process/closestdin.md), [Connect](/docs/api-reference/process/connect.md), [List](/docs/api-reference/process/list.md), [SendInput](/docs/api-reference/process/sendinput.md), [SendSignal](/docs/api-reference/process/sendsignal.md), [StreamInput](/docs/api-reference/process/streaminput.md)

# Start

`POST /process.Process/Start`

Server-streaming RPC. Use the Connect protocol with streaming support.

## OpenAPI

```json
{
  "security": [
    {
      "SandboxAccessTokenAuth": [],
      "SandboxUserAuth": []
    }
  ],
  "parameters": [
    {
      "name": "Connect-Protocol-Version",
      "in": "header",
      "required": true,
      "schema": {
        "type": "number",
        "title": "Connect-Protocol-Version",
        "description": "Define the version of the Connect protocol",
        "const": 1
      }
    },
    {
      "name": "Connect-Timeout-Ms",
      "in": "header",
      "schema": {
        "type": "number",
        "title": "Connect-Timeout-Ms",
        "description": "Define the timeout, in ms"
      }
    },
    {
      "name": "E2b-Sandbox-Id",
      "in": "header",
      "required": true,
      "description": "Identifier of the target sandbox. Routes the request to that sandbox's envd over the shared sandbox host.",
      "schema": {
        "type": "string"
      }
    },
    {
      "name": "E2b-Sandbox-Port",
      "in": "header",
      "required": true,
      "description": "Port envd listens on inside the sandbox (default 49983).",
      "schema": {
        "type": "integer",
        "default": 49983
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/connect+json": {
        "schema": {
          "type": "object",
          "properties": {
            "process": {
              "type": "object",
              "properties": {
                "cmd": {
                  "type": "string",
                  "title": "cmd"
                },
                "args": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "title": "args"
                },
                "envs": {
                  "type": "object",
                  "title": "envs",
                  "additionalProperties": {
                    "type": "string",
                    "title": "value"
                  }
                },
                "cwd": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "title": "cwd"
                }
              },
              "title": "ProcessConfig",
              "additionalProperties": false
            },
            "pty": {
              "oneOf": [
                {
                  "type": "object",
                  "properties": {
                    "size": {
                      "type": "object",
                      "properties": {
                        "cols": {
                          "type": "integer",
                          "title": "cols"
                        },
                        "rows": {
                          "type": "integer",
                          "title": "rows"
                        }
                      },
                      "title": "Size",
                      "additionalProperties": false
                    }
                  },
                  "title": "PTY",
                  "additionalProperties": false
                },
                {
                  "type": "null"
                }
              ],
              "title": "pty"
            },
            "tag": {
              "type": [
                "string",
                "null"
              ],
              "title": "tag"
            },
            "stdin": {
              "type": [
                "boolean",
                "null"
              ],
              "title": "stdin"
            }
          },
          "title": "StartRequest",
          "additionalProperties": false
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "description": "Stream of StartResponse events",
      "content": {
        "application/connect+json": {
          "schema": {
            "type": "object",
            "properties": {
              "event": {
                "type": "object",
                "oneOf": [
                  {
                    "properties": {
                      "data": {
                        "type": "object",
                        "oneOf": [
                          {
                            "properties": {
                              "pty": {
                                "type": "string",
                                "title": "pty",
                                "format": "byte"
                              }
                            },
                            "title": "pty",
                            "required": [
                              "pty"
                            ]
                          },
                          {
                            "properties": {
                              "stderr": {
                                "type": "string",
                                "title": "stderr",
                                "format": "byte"
                              }
                            },
                            "title": "stderr",
                            "required": [
                              "stderr"
                            ]
                          },
                          {
                            "properties": {
                              "stdout": {
                                "type": "string",
                                "title": "stdout",
                                "format": "byte"
                              }
                            },
                            "title": "stdout",
                            "required": [
                              "stdout"
                            ]
                          }
                        ],
                        "title": "DataEvent",
                        "additionalProperties": false
                      }
                    },
                    "title": "data",
                    "required": [
                      "data"
                    ]
                  },
                  {
                    "properties": {
                      "end": {
                        "type": "object",
                        "properties": {
                          "exitCode": {
                            "type": "integer",
                            "title": "exit_code",
                            "format": "int32",
                            "deprecated": true,
                            "description": "Deprecated: not populated by the server. Parse the exit code from the `status` string (e.g. \"exit status 0\")."
                          },
                          "exited": {
                            "type": "boolean",
                            "title": "exited"
                          },
                          "status": {
                            "type": "string",
                            "title": "status",
                            "description": "Process exit status string (e.g. \"exit status 0\"). Parse the integer exit code from this field."
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "title": "error"
                          }
                        },
                        "title": "EndEvent",
                        "additionalProperties": false
                      }
                    },
                    "title": "end",
                    "required": [
                      "end"
                    ]
                  },
                  {
                    "properties": {
                      "keepalive": {
                        "type": "object",
                        "title": "KeepAlive",
                        "additionalProperties": false
                      }
                    },
                    "title": "keepalive",
                    "required": [
                      "keepalive"
                    ]
                  },
                  {
                    "properties": {
                      "start": {
                        "type": "object",
                        "properties": {
                          "pid": {
                            "type": "integer",
                            "title": "pid"
                          }
                        },
                        "title": "StartEvent",
                        "additionalProperties": false
                      }
                    },
                    "title": "start",
                    "required": [
                      "start"
                    ]
                  }
                ],
                "title": "ProcessEvent",
                "additionalProperties": false
              }
            },
            "title": "StartResponse",
            "additionalProperties": false
          }
        }
      }
    },
    "502": {
      "description": "Sandbox not found",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "sandboxID",
              "message",
              "code"
            ],
            "properties": {
              "message": {
                "type": "string",
                "description": "Error message"
              },
              "code": {
                "type": "integer",
                "description": "Error code"
              },
              "sandboxID": {
                "type": "string",
                "description": "Identifier of the sandbox"
              }
            }
          }
        }
      }
    }
  }
}
```