Skip to main content
POST
/
api
/
v1
/
processes
Start a process
curl --request POST \
  --url https://{identifier}.sandbox.tensorlake.ai/api/v1/processes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "<string>",
  "args": [
    "<string>"
  ],
  "env": {},
  "working_dir": "<string>",
  "user": "<string>"
}
'
{
  "handle": 123,
  "pid": 123,
  "stdin_writable": true,
  "command": "<string>",
  "args": [
    "<string>"
  ],
  "started_at": 123,
  "exit_code": 123,
  "signal": 123,
  "ended_at": 123
}
Start a new process inside a sandbox.

​
Endpoint

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

​
Example Request

curl -X POST https://<sandbox-id>.sandbox.tensorlake.ai/api/v1/processes \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "python",
    "args": ["-m", "http.server", "8080"],
    "env": {"PORT": "8080"},
    "working_dir": "/workspace",
    "user": "tl-user",
    "stdin_mode": "pipe",
    "stdout_mode": "capture",
    "stderr_mode": "capture"
  }'

​
Request Body

{
  "command": "python",
  "args": ["-m", "http.server", "8080"],
  "env": {"PORT": "8080"},
  "working_dir": "/workspace",
  "user": "tl-user",
  "stdin_mode": "pipe",
  "stdout_mode": "capture",
  "stderr_mode": "capture"
}
  • 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}. The default is tl-user.
  • stdin_mode accepts closed or pipe. The default is closed.
  • stdout_mode and stderr_mode accept capture or discard. The default is capture.

​
Response

Tensorlake returns 201 Created with the started process metadata: 
{
  "handle": 1,
  "pid": 42,
  "status": "running",
  "exit_code": null,
  "signal": null,
  "stdin_writable": true,
  "command": "python",
  "args": ["-m", "http.server", "8080"],
  "started_at": 1710000000000,
  "ended_at": null
}
handle is a daemon-local stable identifier. Route paths use the operating-system pid.

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.

​
stdin_mode
enum<string>
Available options:
closed,
pipe
​
stdout_mode
enum<string>
Available options:
capture,
discard
​
stderr_mode
enum<string>
Available options:
capture,
discard

Response

Process created successfully

​
handle
integer<int64>
required
​
pid
integer<int32>
required
​
status
enum<string>
required
Available options:
running,
exited,
signaled,
oom_killed
​
stdin_writable
boolean
required
​
command
string
required
​
args
string[]
required
​
started_at
integer<int64>
required
​
exit_code
integer<int32> | null
​
signal
integer<int32> | null
​
ended_at
integer<int64> | null