# Использование секретов с песочницами

Передайте одно или несколько имен секретов аккаунта при создании песочницы. Шлюз разрешит и объединит их до создания песочницы, поэтому запрос не должен содержать сами значения.

В этом руководстве используется секрет типа `env` с именем `sandbox-demo` и переменной `DEMO_API_TOKEN`. Проверка подтвердит наличие переменной, не печатая ее значение.

## Перед началом[​](#before-you-begin "Прямая ссылка на Перед началом")

Вам нужны:

* секрет в том же активном аккаунте, где будет создана песочница;
* право на создание и использование песочниц в этом аккаунте;
* шаблон, доступный аккаунту;
* cURL, `jq` и персональный токен с правами *Полные* для REST-варианта.

В организации личный секрет можно подключить только к новой личной песочнице того же автора. Общая песочница (`"visibility": "org"`) принимает секреты организации. E2B создает личную песочницу и принимает личные секреты ее автора.

Создайте пример `sandbox-demo` по руководству [Создание и управление секретами](/secrets/create-and-manage.md), затем задайте:

```
export JUSTRUN_API="https://your-just-run-host"
export JUSTRUN_PAT="your-personal-access-token"
export JUSTRUN_TEMPLATE="base"
export SECRET_NAME="sandbox-demo"
```

Каждый выбранный секрет предоставляется как полная типизированная запись. Не подключайте запись со значениями, которые оператор песочницы не должен получить.

## Создание через веб-интерфейс[​](#create-through-the-web-ui "Прямая ссылка на Создание через веб-интерфейс")

1. Откройте *Песочницы* → *Новая песочница* и выберите карточку каталога.
2. Проверьте шаблон и настройки ресурсов.
3. Раскройте *Дополнительные настройки*, затем в разделе *Интеграции* раскройте *Секреты*.
4. Найдите и выберите каждый секрет для материализации. В этой же панели можно создать новый секрет — он выберется автоматически.
5. Нажмите *Создать песочницу*.

Веб-интерфейс отправляет только выбранные имена. Страница новой песочницы открывается сразу; дождитесь готовности песочницы и всех шагов подготовки.

## Создание через REST API[​](#create-through-the-rest-api "Прямая ссылка на Создание через 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` для одной логической операции создания. Повторяйте его только при неопределенном результате того же запроса.

## Ожидание готовности результата[​](#wait-until-the-result-is-usable "Прямая ссылка на Ожидание готовности результата")

Создание может вернуться до завершения асинхронной подготовки. Опрашивайте песочницу, пока она не станет `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`. У старых песочниц без записи об источниках скрыты все значения переменных окружения. Команды внутри песочницы по-прежнему могут читать свое окружение.

## Проверка без раскрытия значения[​](#verify-without-exposing-the-value "Прямая ссылка на Проверка без раскрытия значения")

Проверьте условие внутри песочницы вместо печати токена:

```
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`: ненулевой результат означает отсутствие переменной или ошибку проверки.

## Результат материализации[​](#understand-the-materialized-result "Прямая ссылка на Результат материализации")

При создании песочницы поддерживаются все типы секретов 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 или секрет неверного типа, разрешение продолжится без учетных данных, после чего приватный клон может завершиться ошибкой.

## Приоритет и жизненный цикл[​](#precedence-and-lifecycle "Прямая ссылка на Приоритет и жизненный цикл")

Поля песочницы, заданные напрямую, побеждают выбранные секреты:

```
{
  "template": "base",
  "env": {
    "DEMO_API_TOKEN": "inline-value"
  },
  "secrets": ["sandbox-demo"]
}
```

В этом запросе будет использовано значение, заданное напрямую. Среди секретов переменные окружения конфликтуют по ключу, учетные данные Git — по хосту, MCP-серверы — по имени. Порядок списка в запросе не задает приоритет; устраняйте пересечения записей вместо зависимости от внутренних ID.

Материализация создает снимок:

* ротация секрета не обновляет существующую песочницу;
* удаление секрета не убирает материализованные переменные окружения, файлы или конфигурацию из существующей песочницы;
* чтобы получить новое значение, создайте заменяющую песочницу;
* если все существующие копии должны перестать работать, отзовите учетные данные у внешнего провайдера.

## Очистка[​](#clean-up "Прямая ссылка на Очистка")

Удалите демонстрационную песочницу:

```
curl --fail-with-body --silent --show-error \
  --request DELETE "$JUSTRUN_API/v1/sandboxes/$SANDBOX_ID" \
  --header "Authorization: Bearer $JUSTRUN_PAT"
```

Успешное удаление возвращает HTTP `204`. Сохраните переиспользуемый секрет или отдельно удалите демонстрационный секрет на странице *Секреты* либо через его ID в API секретов.

## Решение проблем[​](#troubleshooting "Прямая ссылка на Решение проблем")

* HTTP `404` до создания: как минимум одно выбранное имя отсутствует в активном аккаунте.
* HTTP `503`: в инсталляции не настроен ключ шифрования секретов или ни один узел сейчас не может принять песочницу.
* `status: "running"` при `provisioning.status: "failed"`: проверьте `provisioning.steps`, чтобы найти сбойный шаг записи файла, клонирования или настройки.
* Вместо значения секрета появилось значение, заданное напрямую: поля, заданные напрямую, имеют намеренный приоритет.
* В старой песочнице нет ротированного значения: создайте новую песочницу; живой связи с исходным секретом нет.

## Связанные разделы[​](#related "Прямая ссылка на Связанные разделы")

* [Создание и управление секретами](/secrets/create-and-manage.md)
* [Типы секретов и материализация](/secrets/secret-types.md)
* [Настройка песочницы](/sandboxes/configure-a-sandbox.md)
* [Команды, процессы и терминалы](/sandboxes/commands-processes-and-terminals.md)
* [Наблюдаемость и диагностика](/sandboxes/observability-and-troubleshooting.md)
