SandboxesProcesses

Start a process

Start a process in a sandbox. Without wait=true, return 201 with the running process. With wait=true, wait up to wait_timeout_seconds and return 200. If the wait times out, return the still-running process without an exit code; otherwise return the finished result. Always auto-resume a paused sandbox.

POST
/v1/sandboxes/{sandboxIdOrName}/processes
AuthorizationBearer <token>

API key starting with tektona_. Create one at app-dev.tektona.ai under API Keys.

In: header

Path Parameters

sandboxIdOrName*string

Sandbox ID (ULID) or name

Query Parameters

org?string

Required when the path names the sandbox by name.

project?string

Required when the path names the sandbox by name.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

autostart?boolean

Persist the definition and relaunch on every boot; requires name

command*string

Shell command, executed as a process group

Length1 <= length
cwd?string

Working directory

env?

Environment variables

max_log_bytes?integer

Log retention cap in bytes; null = sandbox default, 0 = logging off

Formatint64
Range0 <= value
name?string

Optional name ([a-z0-9_-], unique among running processes); a memorable name is generated when omitted

Match^[a-z0-9]([a-z0-9_-]*[a-z0-9])?$
Lengthlength <= 64
on_hibernate?string

Behavior when the sandbox pauses

Default"preserve"

Value in

  • "preserve"
  • "stop"
  • "restart_after_resume"
prevent_auto_pause?boolean

Keep the sandbox awake while this process runs

timeout_seconds?integer

Kill the process group after this many seconds (0 = no timeout)

Formatint64
Range0 <= value
tty?

TTY config; tty.enabled=true allocates a PTY at cols/rows, otherwise pipe mode

user?string

Run-as Linux user; defaults to the image's default user

wait?boolean

Block until the process exits, up to wait_timeout_seconds

wait_timeout_seconds?integer

Wait cap in seconds (1–120)

Formatint64
Range1 <= value <= 120
Default60

Response Body

application/json

application/json

application/problem+json

curl -X POST "https://example.com/v1/sandboxes/string/processes" \  -H "Content-Type: application/json" \  -d '{    "command": "string"  }'
{  "already_finished": true,  "autostart": true,  "command": "string",  "cwd": "string",  "error": "string",  "exit_code": 0,  "finish_reason": "string",  "finished_at": "2019-08-24T14:15:22Z",  "id": "string",  "max_log_bytes": 0,  "name": "string",  "on_hibernate": "string",  "pid": 0,  "prevent_auto_pause": true,  "restarted_from": "string",  "signal": "string",  "started_at": "2019-08-24T14:15:22Z",  "status": "running",  "stderr": "string",  "stdout": "string",  "tty": {    "cols": 0,    "enabled": true,    "rows": 0  },  "user": "string"}