# Повна документація Capka > Capka — open-source платформа ШІ-агентів на власному сервері з постійними файлами та окремою Linux-пісочницею для кожного чату. Канонічний індекс: https://capka.app/uk/llms.txt Репозиторій: https://github.com/LyoSU/capka --- # Документація Capka Source: https://capka.app/uk/docs/ Capka — open-source платформа ШІ-агентів на власному сервері для роботи з файлами. Кожен чат отримує постійний робочий простір та ізольовану Linux-пісочницю з Python, Node.js, LibreOffice, FFmpeg, Playwright і OCR. ## Що таке Capka Capka створена для роботи, результатом якої має бути файл, а не лише відповідь у чаті. Прикріпіть таблиці, документи, архіви чи код, опишіть результат — агент може повернути звіт, чистий набір даних, конвертований документ або патч. Ви запускаєте Capka на власному Linux-сервері та підключаєте потрібні моделі: Anthropic, OpenRouter, OpenAI-сумісний API або локальні моделі через Ollama. У Capka немає власної хмари чи плати за користувача. ## Як влаштована система - Окрема непривілейована Linux-пісочниця для кожного чату. - Постійні файли між кроками агента й сесіями браузера. - Приватні чати та файли кожного користувача на спільному інстансі. - Керування ролями, моделями, політиками, аудитом і витратами токенів. - Навички, MCP-конектори та набори з маркетплейсу для повторюваних процесів. ## З чого почати - [Встановіть Capka](/uk/docs/installation/) на Linux-сервер із Docker. - [Підключіть хмарні або локальні моделі](/uk/docs/models/). - Розберіться з [ізоляцією пісочниці](/uk/docs/sandbox/) і [моделлю безпеки](/uk/docs/security/) до відкриття інстансу недовіреним користувачам. - Перегляньте, як [зберігаються файли](/uk/docs/files/) і працює [адміністрування команди](/uk/docs/admin/). --- # Встановлення Capka на власний сервер Source: https://capka.app/uk/docs/installation/ Capka працює на Linux-сервері з Docker. Для старту достатньо невеликого VPS; Kubernetes або зовнішні керовані сервіси не потрібні. ## Системні вимоги - Linux на x86_64 або arm64. - Docker; інсталятор може встановити його, якщо Docker відсутній. - Щонайменше 2 GB RAM і 20 GB диска; рекомендовано 4 GB RAM. - API-ключ моделі, OpenAI-сумісний endpoint або доступний інстанс Ollama. ## Запуск інсталятора Спочатку перегляньте [код інсталятора на GitHub](https://github.com/LyoSU/capka/blob/master/install.sh), а потім виконайте: ```bash curl -fsSL https://raw.githubusercontent.com/LyoSU/capka/master/install.sh | sh ``` Інсталятор перевіряє Docker, завантажує готовий стек, створює секрети й запускає Capka. Без домену він може запропонувати безкоштовну HTTPS-адресу `<ваш-ip>.sslip.io`, а з доменом Caddy автоматично випускає сертифікат. Деталі можуть змінюватися між релізами, тому інсталятор у репозиторії є джерелом істини. ## Перший запуск - Відкрийте адресу, яку показав інсталятор. - Створіть перший обліковий запис адміністратора. - Підключіть провайдера моделі або локальний endpoint. - Створіть чат, прикріпіть невеликий файл і перевірте завантаження результату. > Не відкривайте реєстрацію, доки доступ до моделей, мережа пісочниці й політики адміністратора не відповідають рівню довіри до користувачів. ## Оновлення й підтримка Дотримуйтеся інструкцій поточного [релізу Capka](https://github.com/LyoSU/capka/releases). Pull-only інсталяції мають стежити за гілкою `stable` або фіксувати `CAPKA_VERSION`; `master` є гілкою розробки. Перед оновленням зробіть backup, бо міграції бази даних ідуть лише вперед. Відтворювані проблеми описуйте в [GitHub Issues](https://github.com/LyoSU/capka/issues). --- # Налаштування інстансу Capka Source: https://capka.app/uk/docs/configuration/ На початку визначте п'ять речей: хто може приєднатися, які моделі доступні, де лежать файли, куди може ходити пісочниця і які дії агента потребують дозволу. ## Рекомендований порядок - Створіть і захистіть обліковий запис адміністратора. - Додайте одного провайдера моделі й перевірте його перед додаванням інших. - Перевірте постійне сховище та політику резервного копіювання. - Встановіть allow, ask або deny для чутливих дій агента. - Визначте доступ пісочниць до інтернету й внутрішніх сервісів. - Запрошуйте користувачів лише після перевірки ізоляції та доступів. ## Секрети та ключі моделей Capka може використовувати спільний ключ провайдера або окремі ключі користувачів. Зберігайте ключі в конфігурації інстансу, а не в чатах чи робочих файлах. Видавайте лише потрібні провайдери й можливості. Якщо модель працює поза вашою інфраструктурою, потрібний для запиту вміст може покидати сервер. Локальна модель дозволяє лишити весь процес у вашій мережі. ## Політики та конектори Навички й MCP-конектори підключають процедури та зовнішні сервіси. Перед встановленням набору перевірте хости, команди й запитувані секрети. Оновлення з ширшими доступами потребує такої самої перевірки, як нова інтеграція. > Точні параметри змінюються разом із релізами. Перед автоматизацією розгортання перевіряйте актуальний репозиторій і release notes. --- # Змінні середовища Capka Source: https://capka.app/uk/docs/environment/ Змінні середовища призначені для deployment-рівня: root secrets, маршрутизації хоста, жорстких security-обмежень, ресурсів, retention та observability. ## Перед редагуванням .env Підтримуваний шлях self-hosting — `npm run up` або `scripts/up.sh`. Під час першого запуску скрипт створює сильні значення обов'язкових секретів і не перезаписує вже наявні значення в `.env`. Для локальної розробки `npm run docker:dev` дає loopback-only defaults без копіювання production-файла. Для прямого production `docker compose up`, Coolify чи іншого orchestrator задайте обов'язкові секрети самостійно. Не додавайте `.env` у git; збережіть ті самі значення в password manager або secret store. ## Безпечне застосування змін - Зробіть backup бази та постійних даних перед зміною storage, retention або version settings. - Після редагування `.env` виконайте `docker compose up -d` і перевірте `docker compose ps` та логи сервісів. - Змінюйте по одній ризиковій групі: secrets, routing, sandbox security, а вже потім resource tuning. - Не обертайте `CAPKA_MASTER_KEY` без окремого плану: це root key для зашифрованих ключів провайдерів. > Нижче є всі operator-facing змінні з актуального `.env.example`, а також `OTEL_EXPORTER_OTLP_HEADERS` і явний небезпечний fallback master key, згаданий у ньому. Внутрішні service-to-service змінні навмисно не подані як deployment knobs. --- # Хмарні й локальні моделі в Capka Source: https://capka.app/uk/docs/models/ Capka не прив'язана до одного провайдера: використовуйте власний ключ, OpenAI-сумісний endpoint або локальні моделі через Ollama. ## Варіанти підключення - Моделі Anthropic із вашим API-ключем. - OpenRouter із вашим обліковим записом. - OpenAI-сумісні endpoint, зокрема self-hosted шлюзи. - Локальні моделі через Ollama. ## Вибір моделі Робота з файлами може вимагати довгого контексту, надійного виклику інструментів і достатнього ліміту відповіді. Невелика локальна модель підходить для приватних або типових задач, а складний аналіз документів чи зміни коду можуть потребувати сильнішої хмарної моделі. Перевіряйте повний процес: прикріпіть типовий файл, дайте агенту скористатися інструментами й оцініть готовий артефакт. ## Приватність і вартість Завантажені та готові файли зберігаються на інстансі Capka. Дані для інференсу надсилаються обраному провайдеру. З локальною моделлю інференс може повністю лишатися у вашій інфраструктурі. Capka не додає націнки чи плати за користувача. Сервер і моделі оплачуєте напряму, а адміністратор бачить витрати токенів по користувачах без доступу до приватних чатів. --- # Ізоляція Linux-пісочниць у Capka Source: https://capka.app/uk/docs/sandbox/ Кожен чат Capka отримує власну Linux-пісочницю. Агент запускає код та інструменти без спільного каталогу або контексту виконання з іншими чатами. ## Як працює ізоляція Пісочниця містить робочі файли, інструменти й середовище виконання. Контейнери ніколи не привілейовані, використовують `no-new-privileges`, скидають Linux capabilities, а команди агента працюють як UID `1000:1000`. Сесія монтує лише каталоги свого користувача. Файли зберігаються між кроками й сесіями, а задача продовжує працювати на сервері після закриття вкладки. ## Що працює всередині - Програми на Python, Node.js і Java. - Документи й таблиці через LibreOffice. - Аудіо та відео через FFmpeg. - Автоматизація браузера через Playwright. - OCR, ImageMagick, Pandoc, Graphviz та інші потрібні пакети. ## Посилення для недовірених користувачів Непривілейований runc-контейнер є базовою межею для довірених користувачів. Для публічних інстансів додайте gVisor як user-space kernel і rootless Docker, щоб вихід із контейнера не дорівнював root на хості. Пісочниці мають ліміти пам'яті, CPU, PID та розміру файлів. Вихід у мережу на свіжому інстансі вимкнений до явного дозволу адміністратора; його можна жорстко заборонити або обмежити списком хостів. Прочитайте [документацію з безпеки](/uk/docs/security/) та [SECURITY.md](https://github.com/LyoSU/capka/blob/master/SECURITY.md) до відкриття інстансу. > Попередній перегляд дозволів навичок і конекторів дає поінформовану згоду, але не замінює ізоляцію пісочниці. --- # Постійні файли та інструменти агента Source: https://capka.app/uk/docs/files/ Для Capka файли є і вхідними даними, і готовим результатом. Кожен чат має постійний робочий каталог для аналізу, перетворення й повернення артефактів. ## Сценарії роботи з файлами - Перетворити ZIP із джерелами на PDF-звіт і Excel-таблицю. - Очистити, об'єднати чи проаналізувати CSV і таблиці. - Конвертувати офісні документи через LibreOffice. - Перевірити репозиторій і повернути патч. - Обробити медіа через FFmpeg або розпізнати текст через OCR. ## Постійність та розділення Файли лишаються в каталозі чату між кроками агента й сесіями браузера. Закриття вкладки не скасовує роботу на сервері, а результат лишається в тому самому чаті. Сховища чатів розділені. Одна задача не читає робочі файли іншої, а файли одного користувача не з'являються в іншого. ## Інструменти та пакети Пісочниця є справжнім Linux-середовищем. Агент запускає Python і Node.js, керує браузером та встановлює потрібні пакети в межах пісочниці. > Вважайте завантажені пакети, документи й сайти недовіреними даними. Налаштуйте мережу та правила підтвердження відповідно до ризику. --- # Модель безпеки Capka Source: https://capka.app/uk/docs/security/ Capka розділяє середовище виконання, приватність користувачів і рівень дозволів. Вони захищають від різних ризиків і мають працювати разом. ## Межа виконання Кожен чат працює в окремій непривілейованій Linux-пісочниці без доступу до файлової системи хоста. Capabilities скинуті, команди працюють як UID `1000:1000`, а пам'ять, CPU, PID, розмір файлів і workspace обмежені. Для вищого ризику поєднайте gVisor із rootless Docker та обмежте мережу. ## Приватність користувача й адміністратора Файли та чати приватні для кожного користувача. Адміністратор керує доступом, ролями й витратами токенів, але не бачить чужих чатів і файлів у панелі. Реєстрація за замовчуванням закрита. Відкривайте її лише для навмисно публічного інстансу після посилення пісочниці. ## Дозволи, інтеграції та аудит Перед встановленням набору Capka показує хости конекторів, команди в пісочниці та запитувані секрети. Оновлення з ширшими доступами блокуються до підтвердження. Адміністратор задає allow, ask або deny та переглядає журнал аудиту. Ці засоби зменшують ризик випадкового доступу, а пісочниця лишається головною технічною межею. ## Повідомлення про вразливість Дотримуйтеся приватних інструкцій у [політиці безпеки](https://github.com/LyoSU/capka/blob/master/SECURITY.md). Не публікуйте невиправлену вразливість у відкритому issue. --- # Команди й адміністрування Source: https://capka.app/uk/docs/admin/ Один інстанс Capka обслуговує команду, лишаючи файли й чати кожної людини приватними. Адміністрування стосується доступу й операцій, а не читання розмов. ## Чим керує адміністратор - Доступом користувачів і ролями. - Спільними чи особистими ключами моделей і доступними провайдерами. - Витратами токенів по користувачах. - Правилами allow, ask або deny. - Мережею пісочниць та інтеграціями. - Журналом аудиту. ## Що лишається приватним Робочі каталоги, завантажені файли та історія чатів розділені. Адмінпанель показує ролі й витрати, але не вміст чужої роботи. ## Безпечний порядок запуску - Почніть із малої групи та одного провайдера. - Перевірте типові файлові задачі й завантаження результатів. - Перегляньте дозволи конекторів і мережу пісочниць. - Визначте правила використання й стежте за витратами. - Резервуйте постійні дані перед розширенням доступу чи оновленням. --- # Усунення проблем у Capka Source: https://capka.app/uk/docs/troubleshooting/ Перевіряйте Capka від зовнішнього до внутрішнього: спочатку сервер і контейнери, потім модель, після цього окрему пісочницю й задачу. ## Інстанс не відкривається - Перевірте сервер, вільний диск і пам'ять. - Переконайтеся, що Docker працює, а контейнери Capka справні. - Перевірте reverse proxy, DNS і TLS для адреси інстансу. - Знайдіть перший помилковий крок у виводі встановлення чи оновлення. ## Модель не відповідає - Перевірте ключ, endpoint і назву моделі. - Переконайтеся, що OpenAI-сумісний endpoint доступний із сервера Capka. - Для Ollama перевірте завантажену модель і доступність endpoint із мережі застосунку. - Спочатку виконайте короткий текстовий запит, а тоді файлову задачу. ## Задача в пісочниці падає - Перевірте ліміти пам'яті й диска. - Переконайтеся, що мережева політика дозволяє потрібні хости. - Повторіть із малим типовим файлом. - Запишіть версію релізу, кроки й потрібні логи до створення issue. ## Допомога Спочатку пошукайте в [GitHub Issues](https://github.com/LyoSU/capka/issues). Додайте версію Capka, архітектуру сервера, очікуваний і фактичний результат та мінімальне безпечне відтворення. Ніколи не публікуйте API-ключі, приватні файли чи секрети.