Skip to main content
POST
/
api
/
v1
/
processes
/
run
Run a process
curl --request POST \
  --url https://{identifier}.sandbox.tensorlake.ai/api/v1/processes/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "<string>",
  "args": [
    "<string>"
  ],
  "env": {},
  "working_dir": "<string>",
  "user": "<string>",
  "timeout": 123
}
'
"data: {\"handle\":1,\"pid\":42,\"started_at\":1710000000000}\n\n"
Start a process, stream its captured output over Server-Sent Events, and receive a final exit event. Use this endpoint when you want a single request for non-interactive command execution. If the process needs stdin, use Start Process, Process Stdin, and Close Process Stdin instead.

​
Endpoint

POST /api/v1/processes/run
Use this endpoint on the sandbox proxy host: 
https://<sandbox-id-or-name>.sandbox.tensorlake.ai/api/v1/processes/run

​
Example Request

curl -N -X POST https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes/run \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "python",
    "args": ["-c", "import os; print(os.environ[\"MODE\"])"],
    "env": {"MODE": "batch"},
    "working_dir": "/workspace",
    "timeout": 30
  }'

​
Request Body

{
  "command": "python",
  "args": ["-c", "print('hello')"],
  "env": {"MODE": "batch"},
  "working_dir": "/workspace",
  "user": "tl-user",
  "timeout": 30
}
  • command is required.
  • args defaults to [].
  • env defaults to {} and is applied to the process environment.
  • working_dir is optional.
  • user is optional and accepts a username, UID string, uid:gid string, or an object such as {"uid": 1000, "gid": 1000}.
  • timeout is optional. When set, Tensorlake kills the process if it is still running after that many seconds.
/processes/run always starts the process with stdin closed and stdout/stderr captured, even if stdin_mode, stdout_mode, or stderr_mode are present in the request body.

​
SSE Events

Tensorlake streams JSON payloads in SSE data: frames: 
data: {"handle":1,"pid":42,"started_at":1710000000000}

data: {"line":"hello","timestamp":1710000000010,"stream":"stdout"}

data: {"exit_code":0}
The first event contains handle, pid, and started_at. Output events contain line, timestamp, and stream. The final event contains exit_code or signal; if the kernel OOM killer ended the process, it includes signal: 9 and oom_killed: true.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
command
string
required
​
args
string[]
​
env
object
​
working_dir
string
​
user

Username, UID string, or uid:gid string.

​
timeout
number<double>

Maximum seconds to wait before killing the process.

Response

Process event stream

JSON payload carried in each Server-Sent Events data: frame from /api/v1/processes/run.

​
handle
integer<int64>
required
​
pid
integer<int32>
required
​
started_at
integer<int64>
required