Exec¶

Run a command inside a running machine and get its output back. This is the headline primitive — it runs through the VM's network namespace, no SSH required.

Run a command¶

POST /v1/machines/{id}/exec

Scope: full. The machine must be running (otherwise 409).

Request body¶

Field	Type	Default	Notes
`script`	string	— (required)	Shell command/script to run
`timeout_sec`	int	`30`	Server clamps to a max of `120`

curl -X POST "https://api.sistemo.io/v1/machines/$ID/exec" \
  -H "Authorization: Bearer $SISTEMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"script":"python3 -c \"print(2+2)\"","timeout_sec":30}'

Response¶

{
  "exit_code": 0,
  "stdout": "4\n",
  "stderr": ""
}

Field	Type	Meaning
`exit_code`	int	Process exit code
`stdout`	string	Standard output
`stderr`	string	Standard error

Notes¶

Reuse the machine. Each call runs in the same VM, so state (installed packages, files in /tmp) persists between calls until the machine is stopped/destroyed.
Timeouts. A command exceeding timeout_sec is terminated; design long jobs to run in the background and poll.
Rate limit. Exec has its own per-account limit; on 429, back off (see Errors).

SDK equivalents¶

sb.run("python3 -c 'print(2+2)'", timeout=30)   # Python → ExecResult

await sb.run("node -e 'console.log(2+2)'", 30);  // JS → { exitCode, stdout, stderr }