Команды, процессы и терминалы
Выполнение с буферизацией подходит для коротких задач, чей полный вывод помещается в один ответ. Для постепенного вывода используйте SSE, для долговременного сервиса — фоновый процесс, а для интерактивной работы — браузерный терминал.
Выполнение с буферизацией
POST /v1/sandboxes/{id}/exec ждет завершения и возвращает stdout, stderr и
код выхода:
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID/exec" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--data '{
"cmd": "sh",
"args": ["-lc", "printf \"working\\n\"; exit 0"],
"cwd": "/tmp",
"env": {"JOB_NAME": "demo"},
"timeout": 30000
}' |
jq
Поля тела REST-запроса:
cmd— строка с исполняемым файлом;args— массив аргументов;cwd— необязательная рабочая директория;env— дополнительные переменные команды;timeout— миллисекунды, по умолчанию пять минут;user— необязательное переопределение Unix-пользователя;stdin— необязательный base64-ввод для выполнения с буферизацией.
MCP-инструмент sandbox_exec называет аргумент timeout_ms и переводит его в
REST timeout. Не отправляйте старый массив cmd или timeout_ms прямо в
REST-эндпоинт /exec.
HTTP 200 означает, что результат процесса получен. Всегда проверяйте
exit_code: ненулевой код не превращается в HTTP-ошибку.
SSE-стриминг
POST /v1/sandboxes/{id}/exec-stream принимает ту же команду, кроме stdin, и
возвращает text/event-stream:
{"type":"stdout","text":"one line\n"}
{"type":"stderr","text":"warning\n"}
{"type":"exit","code":0}
Читайте поток до события exit. Эндпоинт явно отклоняет stdin.
Фоновый процесс
POST /v1/sandboxes/{id}/start возвращает PID и HTTP 200. Он подходит для
сервиса, продолжающего работу после ответа. Затем можно отправить поддерживаемый
сигнал через /processes/{pid}/signal или подключиться по WebSocket.
Браузерный терминал
Откройте активную песочницу и выберите Терминал. Надпись Подключено означает
готовность интерактивной сессии. Используйте ее для TTY и состояния оболочки, а
/exec — для автоматизации и детерминированного результата.
Границы ошибок
- Выполнение требует активной песочницы. Остановленной песочнице нужно возобновление, песочнице в гибернации — пробуждение.
- Таймаут команды и код выхода — разные сигналы.
- Команда идет от настроенного пользователя по умолчанию, обычно
user; отдельный вызов может его переопределить.