> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yahont.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Архитектура Craft

> Изоляция Craft, потоки данных, учётные данные, одобрения и общий доступ

Craft добавляет в Yahont недоверенную среду выполнения кода. Yahont управляет жизненным циклом песочницы,
хранит учётные данные вне песочницы и посредничает при доступе к знаниям компании,
внешним сервисам и созданным веб-приложениям.

![Архитектура среды выполнения Craft: браузер, плоскость управления Yahont, песочница каждого пользователя, прокси песочниц, поставщики моделей, поиск, внешние приложения и созданные веб-приложения](https://mintcdn.com/yahont-ai/uOUoHpXrpfUMZdwx/assets/security/OnyxCraftArchitecture.png?fit=max\&auto=format\&n=uOUoHpXrpfUMZdwx\&q=85\&s=79bfbe6d163c6b65623ad5e0707dff1d)

## Компоненты и границы доверия

| Компонент | Роль и доступ |
| - | - |
| **Браузер** | Отправляет запросы и файлы, получает поток событий, показывает одобрения и отображает созданные веб-приложения. |
| **Плоскость управления Yahont** | Аутентифицирует пользователей, проверяет доступ, управляет сессиями и песочницами, хранит состояние и проксирует созданные веб-приложения. |
| **Песочница пользователя** | Выполняет код и инструменты, созданные моделью. У каждой сессии Craft отдельное рабочее пространство внутри песочницы пользователя. |
| **Прокси песочниц** | Принимает HTTP- и HTTPS-трафик песочниц, блокирует внутренние адреса, подставляет учётные данные и применяет политики приложений. |
| **Хранилище Yahont** | Хранит записи сессий, одобрения, задачи, зашифрованные учётные данные, загруженные файлы, пакеты навыков и снимки. |
| **Внешние сервисы** | Поставщики моделей, публичные сайты и настроенные приложения получают исходящие запросы через прокси песочниц. |

Песочница — недоверенная граница. Она получает файлы и инструкции, необходимые для выполнения работы,
но не исходные учётные данные Yahont, поставщика модели или приложения.

## Жизненный цикл запроса

**1. Yahont авторизует запрос**

Браузер отправляет в API Yahont запрос, вложения, выбор модели и выбранные возможности.
Yahont проверяет доступ пользователя к Craft и моделям.

**2. Yahont готовит рабочее пространство**

Yahont создаёт или восстанавливает песочницу пользователя,
создаёт каталог для сессии и синхронизирует доступные этому пользователю навыки и файлы библиотеки пользователя.

**3. Агент работает в песочнице**

Песочница вызывает выбранную модель, выполняет код и инструменты и записывает файлы в рабочее пространство сессии.
Yahont передаёт события агента обратно в браузер потоком.

**4. Сетевые запросы проходят через прокси**

Прокси песочниц определяет песочницу и сессию,
блокирует внутренние адреса и подставляет учётные данные или запрашивает одобрение,
если этого требует адрес назначения.

**5. Yahont отдаёт результат**

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

## Изоляция песочницы и рабочего пространства

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

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

Когда песочница простаивает,
Yahont сохраняет состояние её сессий в настроенное файловое хранилище и останавливает среду выполнения.
Yahont восстанавливает это состояние, когда пользователь возвращается. Снимки обеспечивают засыпание и восстановление;
это не история версий для пользователя.

| Бэкенд | Граница изоляции |
| - | - |
| **Kubernetes** | Под-песочница в отдельном пространстве имён с ограниченным RBAC, межсетевым экраном внутри пода и NetworkPolicy. |
| **Docker Compose** | Контейнер-песочница на отдельном мосту, с межсетевым экраном внутри контейнера и без подключения к сети Compose по умолчанию. |

Бэкенд Docker требует от API-сервера и фонового рабочего процесса доступа к сокету Docker на чтение и запись.
Такой доступ фактически равен доступу root к хосту,
поэтому Docker Compose предназначен для небольших развёртываний на доверенном хосте.

## Исходящий сетевой трафик

Межсетевой экран песочницы разрешает DNS и путь через прокси песочниц. У HTTP- и HTTPS-запросов песочницы нет второго,
прямого маршрута в сеть.

Прокси ведёт себя по-разному в зависимости от адреса назначения:

| Назначение | Поведение прокси |
| - | - |
| **API Yahont** | Разрешает настроенные хост и порт API и подставляет ограниченные учётные данные песочницы в Yahont. |
| **Поддерживаемый поставщик модели** | Подставляет доступный ключ поставщика для Anthropic, OpenAI или OpenRouter. |
| **Настроенное приложение** | Сопоставляет URL и действие, применяет политику, затем подставляет учётные данные организации или пользователя. |
| **Другой публичный адрес** | Пересылает запрос без привилегированных учётных данных и без одобрения приложения. |
| **Приватный или неглобальный адрес** | Блокирует запрос, включая loopback, частные сети, link-local адреса и метаданные облака. Исключение — настроенный API Yahont. |

> [!NOTE]
>
> Прокси — это средство контроля исходящего трафика и граница учётных данных,
> а не список разрешённых адресов публичного интернета.
> Craft может просматривать сайты и устанавливать пакеты с публичных адресов без подключения приложения.

Kubernetes добавляет NetworkPolicy как второе средство контроля трафика от песочницы к прокси и DNS.
Песочницы Docker используют отдельный мост, который не может разрешать имена сервисов Compose Yahont и обращаться к ним.
Требования к операторам см. в руководствах по развёртыванию в [Kubernetes](https://docs.yahont.ai/deployment/local/craft_kubernetes.md)
и [Docker Compose](https://docs.yahont.ai/deployment/local/craft_docker_compose.md).

## Работа с учётными данными

Песочница получает значения-заполнители для учётных данных, которыми управляет Yahont.
Прокси определяет идентичность песочницы,
получает нужные учётные данные и добавляет их только к подходящему исходящему запросу.

| Учётные данные | Где хранит Yahont | Для чего подставляются |
| - | - | - |
| **Учётные данные песочницы в Yahont** | Зашифрованы вместе с записью песочницы | Настроенные хост и порт API Yahont |
| **Ключ поставщика модели** | Вместе с доступной пользователю конфигурацией поставщика | Хост соответствующего поддерживаемого поставщика модели |
| **Учётные данные приложения** | Зашифрованное хранилище учётных данных приложения организации или пользователя | URL, отнесённые к этому приложению |

Исходные учётные данные находятся в хранилище под управлением Yahont и ненадолго — в памяти прокси,
пока готовится запрос. Процесс подстановки не записывает их в рабочее пространство песочницы,
пакет навыков или созданные файлы.

## Знания компании

Craft ищет по знаниям компании через API Yahont,
а не подключает песочницу напрямую к векторной базе данных или проиндексированным источникам.
Yahont обрабатывает запрос от имени владельца песочницы и применяет права этого пользователя на документы.

Включение Craft,
предоставление доступа к навыку или подключение приложения не расширяет доступ пользователя к проиндексированным
документам. Результаты поиска всё равно могут попасть в запрос, созданный файл или веб-приложение,
поэтому пользователям нужно проверять результаты, прежде чем делиться ими.

## Приложения и одобрения

Запросы, отнесённые к приложению, используют политики, настроенные администратором:

| Политика | Применение |
| - | - |
| **Автоодобрение** | Прокси пересылает подходящее действие без остановки. |
| **Спрашивать** | Прокси приостанавливает запрос, пока пользователь не одобрит или не отклонит его. |
| **Запрещать** | Прокси блокирует запрос. |

Для действия **Спрашивать** процесс одобрения выглядит так:

**1. Приостановите запрос**

Прокси останавливает запрос до подстановки учётных данных приложения.

**2. Запросите решение**

Yahont отправляет в сессию карточку одобрения. Пользователь одобряет один раз,
одобряет подходящие действия на время сессии или отклоняет запрос.

**3. Перешлите или заблокируйте**

Прокси пересылает одобренный запрос с учётными данными или отклоняет его по умолчанию после отклонения или истечения
срока.

Если запрос соответствует нескольким встроенным действиям приложения, действует самая строгая политика: **Запрещать**,
затем **Спрашивать**, затем **Автоодобрение**. Запрос к встроенному приложению, которого нет в каталоге,
обрабатывается как **Спрашивать**. Пользовательские приложения используют **Спрашивать** для каждого запроса,
соответствующего их настроенным шаблонам URL.

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

## Созданные веб-приложения

Yahont отдаёт созданные веб-приложения через аутентифицированный прокси, а не открывает порты песочницы напрямую.
Прокси проверяет область общего доступа сессии, прежде чем переслать запрос:

| Область | Доступ |
| - | - |
| **Приватное** | Только владелец сессии |
| **Организация** | Аутентифицированные пользователи рабочего пространства Yahont |

Общий доступ открывает созданное веб-приложение, а не разговор в Craft или файловый обозреватель сессии.
Однако информация, записанная в само приложение, видна всем, кто может его открыть.

Перед отправкой запроса на сервер созданного приложения прокси удаляет cookie зрителя, заголовки авторизации,
заголовки CSRF, заголовки пересылки и заголовки идентичности.
Он также удаляет `set-cookie` из ответа созданного приложения. Предпросмотр работает в iframe с песочницей,
в котором включены скрипты, формы и переходы по инициативе пользователя.

> [!WARNING]
>
> Созданный клиентский код выполняется в браузере зрителя.
> Запросы со стороны браузера не являются исходящим трафиком песочницы и не проходят через прокси песочниц.
> Проверьте созданное приложение, прежде чем открывать к нему доступ организации.

## Состояние и операционные данные

| Хранилище | Данные Craft |
| - | - |
| **PostgreSQL** | Сессии, записи песочниц, состояние общего доступа, одобрения, конфигурация приложений, задачи и зашифрованные учётные данные |
| **Redis** | Координация потоковой передачи, сигналы одобрений, блокировки и краткоживущие кэши |
| **Файловое хранилище** | Вложения, содержимое библиотеки пользователя, пакеты навыков и снимки песочниц |
| **Хранилище активной песочницы** | Рабочие пространства сессий, созданные файлы, состояние агента и работающие веб-приложения |

> [!WARNING]
>
> Относитесь к журналам и трассировкам Craft как к потенциально конфиденциальным.
> В зависимости от конфигурации журналирования они могут включать запросы, имена файлов, URL, результаты инструментов,
> взаимодействия с моделями и метаданные одобрений.

## Соображения безопасности

| Риск | Меры защиты |
| - | - |
| Код, созданный моделью, ведёт себя неожиданно | Сохраняйте границу песочницы и средства контроля прокси; проверяйте результаты, прежде чем использовать их или делиться ими. |
| Навык содержит небезопасные инструкции или скрипты | Проверяйте пакеты пользовательских навыков, прежде чем предоставлять более широкий доступ. |
| Пользователь одобряет непредусмотренное действие приложения | Оставляйте значимые действия на **Спрашивать** или **Запрещать** и делайте предварительные одобрения запланированных задач узкими. |
| Созданное содержимое включает конфиденциальные данные компании | Права на документы защищают извлечение, но пользователи остаются ответственными за созданные файлы и открытые веб-приложения. |
| Запросы и контекст покидают Yahont | Изучите условия обработки данных и конфигурацию каждого поставщика модели и внешнего приложения. |
| Компрометация сокета Docker влияет на хост | Используйте Kubernetes для более крупных развёртываний и ограничьте Docker Compose доверенными контролируемыми хостами. |

> [card] [Развёртывание Craft](https://docs.yahont.ai/deployment/local/craft.md)
>
> Выберите бэкенд песочниц и настройте его средства защиты.

> [card] [Управление Craft](https://docs.yahont.ai/admins/managing_features/craft.md)
>
> Настройте доступ, приложения, навыки, модели и инструкции рабочего пространства.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.