Перейти к основному содержимому
Открыть Markdown

Команды, процессы и терминалы

Выполнение с буферизацией подходит для коротких задач, чей полный вывод помещается в один ответ. Для постепенного вывода используйте 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-ввод для выполнения с буферизацией.
Имена полей REST и MCP различаются

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; отдельный вызов может его переопределить.