Быстрый старт с API
Тремя аутентифицированными REST-запросами создайте песочницу, выведите сообщение и удалите ее. API доступен по тому же адресу, что и дашборд Just Run.
Перед началом
Нужны cURL, jq и персональный токен с правами Полные. Создайте его в
Токены → Новый токен, сохраните значение токена — Just Run показывает его только
один раз — и задайте:
export JUSTRUN_API="https://your-just-run-host"
export JUSTRUN_PAT="your-personal-access-token"
Не коммитьте эти значения.
1. Создание песочницы
CREATE_RESPONSE=$(
curl --fail-with-body --silent --show-error \
--request POST "$JUSTRUN_API/v1/sandboxes" \
--header "Authorization: Bearer $JUSTRUN_PAT" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: api-quickstart-1" \
--data '{"template":"base","name":"api-quickstart"}'
)
SANDBOX_ID=$(jq -er '.id' <<<"$CREATE_RESPONSE")
printf 'created %s\n' "$SANDBOX_ID"
Первое создание возвращает HTTP 201. Сохраните ID для следующих операций.
Повтор этого запроса с тем же ключом идемпотентности в течение 30 дней после создания
возвращает ответ первого создания — с тем же ID песочницы и кодом 200 вместо 201.
Удаление песочницы ключ не сбрасывает: если песочницу удалили, повтор в эти 30 дней
возвращает HTTP 404. Чтобы пройти инструкцию повторно, задайте в Idempotency-Key
новое значение.
2. Выполнение команды
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":"echo","args":["hello from just-run"],"timeout":30000}' |
jq
REST-контракт выполнения использует строковый cmd, отдельный массив args и
timeout в миллисекундах. Оболочка при этом не запускается: для конвейеров и &&
передайте "cmd":"sh","args":["-c","…"].
Проверка результата
Ответ HTTP 200 содержит:
{
"exit_code": 0,
"stdout": "hello from just-run\n",
"stderr": ""
}
Ненулевой exit_code при ответе HTTP 200 означает, что команда запустилась и
завершилась с ошибкой. Если команду не удалось запустить, API возвращает HTTP-ошибку:
несуществующая команда дает HTTP 422 с кодом request.validation_failed, а не
ненулевой exit_code.
3. Очистка ресурсов
curl --fail-with-body --silent --show-error \
--request DELETE "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
--header "Authorization: Bearer $JUSTRUN_PAT"
Успешное удаление возвращает HTTP 204.
Диагностика
- HTTP
401: проверьте хост и персональный токен — его значение и срок действия. - HTTP
403с кодомpermission.read_only_token: токен с правами Только чтение не может создавать и удалять песочницы, нужен токен с правами Полные. - HTTP
429: с кодомquota.exceeded— исчерпана квота, с кодомrate_limit.exceeded— превышено ограничение частоты запросов, повторите запрос позже. - Песочница существует, но не выполняет команды: проверьте ее статус и события по порядку диагностики.