Processes and Terminals

The Processes and Terminals API is provided by envd's process.Process Connect RPC service. It is used to start commands inside the sandbox, connect to existing processes, send input, resize PTYs, and terminate processes.

Before calling this API, see the Sandbox Runtime API to get the envd endpoint and envdAccessToken.

To specify the execution user inside the sandbox, set Authorization: Basic <base64("user:")>. If no user is specified, envd uses the sandbox default user. Request and response bodies use protobuf JSON field names, which are lowerCamelCase.

Connect RPC Paths

Method	Request Path	Type	Description
List	/process.Process/List	Unary	List running processes
Start	/process.Process/Start	Server streaming	Start a process and stream process events
Connect	/process.Process/Connect	Server streaming	Connect to an existing process and stream process events
Update	/process.Process/Update	Unary	Update process configuration. Currently mainly used to resize a PTY
SendInput	/process.Process/SendInput	Unary	Send stdin or PTY input to a process
StreamInput	/process.Process/StreamInput	Client streaming	Send input through a client stream and preserve input order
SendSignal	/process.Process/SendSignal	Unary	Send a signal to a process
CloseStdin	/process.Process/CloseStdin	Unary	Close stdin for a non-PTY process

Data Structures

ProcessConfig

Field	Type	Description
cmd	string	Executable command
args	string[]	Command arguments
envs	object	Environment variables
cwd	string	Working directory

PTY

Field	Type	Description
size.cols	integer	Terminal columns
size.rows	integer	Terminal rows

ProcessSelector

Select a process by PID or tag:

Field	Type	Description
pid	integer	Process ID
tag	string	Process tag

ProcessEvent

Start and Connect return a stream of process events:

Event	Field	Description
start	pid	Process started and PID assigned
data	stdout / stderr / pty	Process output. Binary fields are represented as base64 in the JSON protocol
end	exitCode / exited / status / error	Process end event
keepalive	None	Keepalive event

List Processes

Request Path

POST /process.Process/List

Request Parameters

The request body is an empty object:

{}

Response Fields

Field	Type	Description
processes[].config	object	Process start configuration
processes[].pid	integer	Process ID
processes[].tag	string	Process tag

Request Example

curl -X POST "$ENVD_API_BASE/process.Process/List" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -H "Authorization: Basic dXNlcjo=" \
  -H "Connect-Protocol-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{}'

Start a Process

Request Path

POST /process.Process/Start

Request Parameters

Parameter	Type	Required	Description
process	object	Yes	Process configuration
pty	object	No	PTY configuration. When provided, the process runs in pseudo-terminal mode
tag	string	No	Process tag
stdin	boolean	No	Whether to open stdin. Compatibility field; default behavior is determined by the server

Request Examples

Start a regular command:

curl -N -X POST "$ENVD_API_BASE/process.Process/Start" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -H "Authorization: Basic dXNlcjo=" \
  -H "Connect-Protocol-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "process": {
      "cmd": "bash",
      "args": ["-lc", "echo hello"]
    },
    "tag": "hello"
  }'

Start a PTY:

{
  "process": {
    "cmd": "bash",
    "args": ["-i", "-l"],
    "envs": {
      "TERM": "xterm"
    },
    "cwd": "/home/user"
  },
  "pty": {
    "size": {
      "cols": 80,
      "rows": 24
    }
  },
  "tag": "terminal"
}

Connect to an Existing Process

Request Path

POST /process.Process/Connect

Request Parameters

Parameter	Type	Required	Description
process.pid	integer	One of two	Connect by PID
process.tag	string	One of two	Connect by tag

Request Example

{
  "process": {
    "pid": 1234
  }
}

Send Input

Request Path

POST /process.Process/SendInput

Request Parameters

Parameter	Type	Required	Description
process	object	Yes	Process selector
input.stdin	bytes	One of two	stdin input for a non-PTY process
input.pty	bytes	One of two	PTY input

In the JSON protocol, bytes fields are represented as base64.

Request Example

{
  "process": {
    "tag": "terminal"
  },
  "input": {
    "pty": "ZWNobyBoZWxsbwo="
  }
}

Resize a PTY

Request Path

POST /process.Process/Update

Request Parameters

Parameter	Type	Required	Description
process	object	Yes	Process selector
pty.size.cols	integer	No	New terminal column count
pty.size.rows	integer	No	New terminal row count

Request Example

{
  "process": {
    "tag": "terminal"
  },
  "pty": {
    "size": {
      "cols": 120,
      "rows": 40
    }
  }
}

Send a Signal

Request Path

POST /process.Process/SendSignal

Request Parameters

Parameter	Type	Required	Description
process	object	Yes	Process selector
signal	string or integer	Yes	Signal. Available values include SIGNAL_SIGTERM (15) and SIGNAL_SIGKILL (9)

Close stdin

Request Path

POST /process.Process/CloseStdin

Request Parameters

Parameter	Type	Required	Description
process	object	Yes	Process selector

CloseStdin only applies to non-PTY processes. In PTY scenarios, send Ctrl+D (0x04) to indicate EOF.

Related Documents

• Sandbox Runtime
• File System