Использование секретов с песочницами
Передайте одно или несколько имен секретов аккаунта при создании песочницы. Шлюз разрешит и объединит их до создания песочницы, поэтому запрос не должен содержать сами значения.
В этом руководстве используется секрет типа env с именем sandbox-demo и
переменной DEMO_API_TOKEN. Проверка подтвердит наличие переменной, не печатая
ее значение.
Перед началом
Вам нужны:
- секрет в том же активном аккаунте, где будет создана песочница;
- право на создание и использование песочниц в этом аккаунте;
- шаблон, доступный аккаунту;
- cURL,
jqи персональный токен с правами Полные для REST-варианта.
В организации личный секрет можно подключить только к новой личной песочнице
того же автора. Общая песочница ("visibility": "org") принимает секреты
организации. E2B создает личную песочницу и принимает личные секреты ее автора.
Создайте пример sandbox-demo по руководству Создание и управление
секретами, затем задайте:
export JUSTRUN_API="https://your-just-run-host"
export JUSTRUN_PAT="your-personal-access-token"
export JUSTRUN_TEMPLATE="base"
export SECRET_NAME="sandbox-demo"
Каждый выбранный секрет предоставляется как полная типизированная запись. Не подключайте запись со значениями, которые оператор песочницы не должен получить.
Создание через веб-интерфейс
- Откройте Песочницы → Новая песочница и выберите карточку каталога.
- Проверьте шаблон и настройки ресурсов.
- Раскройте Дополнительные настройки, затем в разделе Интеграции раскройте Секреты.
- Найдите и выберите каждый секрет для материализации. В этой же панели можно создать новый секрет — он выберется автоматически.
- Нажмите Создать песочницу.
Веб-интерфейс отправляет только выбранные имена. Страница новой песочницы открывается сразу; дождитесь готовности песочницы и всех шагов подготовки.
Создание через REST API
Соберите запрос из шаблона и имени секрета, затем сохраните ID созданной песочницы:
CREATE_RESPONSE="$(
jq -n '{
template: env.JUSTRUN_TEMPLATE,
name: "secret-consumer-demo",
secrets: [env.SECRET_NAME]
}' |
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: secret-consumer-demo-1" \
--data-binary @-
)"
SANDBOX_ID="$(jq -er '.id' <<<"$CREATE_RESPONSE")"
jq '{id, status, provisioning}' <<<"$CREATE_RESPONSE"
Новая песочница возвращает HTTP 201. Разрешение секретов происходит до
передачи запроса узлу. Если хотя бы одно явно выбранное имя неизвестно, API
возвращает 404 и не создает песочницу.
Используйте один Idempotency-Key для одной логической операции создания.
Повторяйте его только при неопределенном результате того же запроса.
Ожидание готовности результата
Создание может вернуться до завершения асинхронной подготовки. Опрашивайте
песочницу, пока она не станет running, а необязательная сводка подготовки —
ready:
while :; do
SANDBOX="$(
curl --fail-with-body --silent --show-error \
"$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
--header "Authorization: Bearer $JUSTRUN_PAT"
)"
STATUS="$(jq -r '.status' <<<"$SANDBOX")"
PROVISIONING="$(jq -r '.provisioning.status // "ready"' <<<"$SANDBOX")"
if [ "$STATUS" = "failed" ] || [ "$PROVISIONING" = "failed" ]; then
jq '{status, provisioning}' <<<"$SANDBOX"
exit 1
fi
if [ "$STATUS" = "running" ] && [ "$PROVISIONING" = "ready" ]; then
break
fi
sleep 2
done
Переменные окружения доступны командам в песочнице. Файлы, репозитории,
SSH-ключи, учетные данные реестров и конфигурация MCP могут иметь шаги
подготовки, поэтому не используйте их артефакты до состояния ready.
API песочниц возвращает ******** для итоговых значений переменных окружения
из секретов и перечисляет ключи в redacted_env_keys. У старых песочниц без
записи об источниках скрыты все значения переменных окружения. Команды внутри
песочницы по-прежнему могут читать свое окружение.
Проверка без раскрытия значения
Проверьте условие внутри песочницы вместо печати токена:
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",
"test -n \"$DEMO_API_TOKEN\" && printf \"secret-present\\n\""
],
"timeout": 30000
}' |
jq '{exit_code, stdout, stderr}'
Ожидаемый вывод:
{
"exit_code": 0,
"stdout": "secret-present\n",
"stderr": ""
}
HTTP 200 означает только завершение выполнения команды. Проверяйте
exit_code: ненулевой результат означает отсутствие переменной или ошибку
проверки.
Результат материализации
При создании песочницы поддерживаются все типы секретов Just Run:
envдобавляет переменные окружения;git_credentialнастраивает HTTPS-аутентификацию для подходящих хостов Git;repoдобавляет клонирование репозитория и при необходимости разрешает связанныйgit_credential;mcp_serverдобавляет удаленный сервер в конфигурацию MCP-клиента песочницы;ssh_keyзаписывает файлы ключей и необязательныйknown_hosts;registry_credentialзаписывает аутентификацию в реестре пакетов или контейнеров;fileзаписывает декодированные байты с заданными путем и правами доступа.
Если путь секрета типа file начинается с ~/, Just Run разрешает ~ в
домашний каталог настроенного пользователя по умолчанию и передает этому
пользователю владение новым файлом. Явный абсолютный путь вроде
/root/credentials сохраняется без изменения; процесс по умолчанию без прав
root не сможет прочитать файл, принадлежащий root, с правами 0600.
Репозитории из секретов и репозитории, заданные напрямую в песочнице,
добавляются друг к другу. Ошибка клонирования обязательного репозитория
переводит подготовку в failed. Если сохраненный репозиторий ссылается на
отсутствующие учетные данные Git или секрет неверного типа, разрешение
продолжится без учетных данных, после чего приватный клон может завершиться
ошибкой.
Приоритет и жизненный цикл
Поля песочницы, заданные напрямую, побеждают выбранные секреты:
{
"template": "base",
"env": {
"DEMO_API_TOKEN": "inline-value"
},
"secrets": ["sandbox-demo"]
}
В этом запросе будет использовано значение, заданное напрямую. Среди секретов переменные окружения конфликтуют по ключу, учетные данные Git — по хосту, MCP-серверы — по имени. Порядок списка в запросе не задает приоритет; устраняйте пересечения записей вместо зависимости от внутренних ID.
Материализация создает снимок:
- ротация секрета не обновляет существующую песочницу;
- удаление секрета не убирает материализованные переменные окружения, файлы или конфигурацию из существующей песочницы;
- чтобы получить новое значение, создайте заменяющую песочницу;
- если все существующие копии должны перестать работать, отзовите учетные данные у внешнего провайдера.
Очистка
Удалите демонстрационную песочницу:
curl --fail-with-body --silent --show-error \
--request DELETE "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
--header "Authorization: Bearer $JUSTRUN_PAT"
Успешное удаление возвращает HTTP 204. Сохраните переиспользуемый секрет или
отдельно удалите демонстрационный секрет на странице Секреты либо через его ID
в API секретов.
Решение проблем
- HTTP
404до создания: как минимум одно выбранное имя отсутствует в активном аккаунте. - HTTP
503: в инсталляции не настроен ключ шифрования секретов или ни один узел сейчас не может принять песочницу. status: "running"приprovisioning.status: "failed": проверьтеprovisioning.steps, чтобы найти сбойный шаг записи файла, клонирования или настройки.- Вместо значения секрета появилось значение, заданное напрямую: поля, заданные напрямую, имеют намеренный приоритет.
- В старой песочнице нет ротированного значения: создайте новую песочницу; живой связи с исходным секретом нет.