Samodzielny hosting OneCLI: konfiguracja Docker Compose

Co zyskujesz, hostując samodzielnie OneCLI

Samodzielne hostowanie OneCLI zapewnia każdemu członkowi zespołu własnego agenta, działającego w odizolowanym środowisku (sandbox). Klucze API są przechowywane w bramie, do której agenci nie mają bezpośredniego dostępu. Instalacja składa się ze stosu Docker Compose z bazą PostgreSQL, dostępnego pod adresem http://localhost:10254. Zaplanuj użycie dedykowanego serwera. Dokumentacja zakłada domyślnie 2 GiB pamięci RAM na sandbox agenta, więc nie jest to rozwiązanie dla VPS o pojemności 1 GB.

Stos składa się z siedmiu elementów. Zrozumienie roli każdego z nich ułatwia korzystanie z tego przewodnika.

• Panel webowy (Next.js), port 10254. Tworzenie agentów, czat, edycja pamięci i umiejętności, zarządzanie połączeniami oraz sekretami.
• Serwer API, port 10256. Płaszczyzna sterowania: baza danych, obsługa konwersacji, kolejki zadań.
• Brama Rust, port 10255. Przechwytuje żądania wychodzące od agentów i wstrzykuje poświadczenia.
• Runner. Dokumentacja opisuje go jako komponent, który „uruchamia, parkuje i usuwa środowiska sandbox agentów. Działa tylko w kierunku wychodzącym i nigdy nie łączy się z bazą danych”.
• Sandbox Supervisor. Dokumentacja opisuje go jako proces działający „wewnątrz każdego sandboxa, komunikujący się za pomocą neutralnego interfejsu, co pozwala na wymianę środowiska uruchomieniowego agenta”.
• Adapter kanałów. Demon łączący aplikację Slack, dzięki czemu agent odpowiada na kanałach i w wiadomościach prywatnych pod własną nazwą.
• PostgreSQL. Dostarczony plik compose uruchamia postgres:18-alpine z wolumenem pgdata.

Nazwa sugeruje CLI, produkt jest serwerem

OneCLI to platforma serwerowa. Nazwa wskazuje na narzędzie wiersza poleceń instalowane na laptopie, jednak ten obraz jest błędny w kontekście rozwiązania opisanego w tym przewodniku. Osobny klient wiersza poleceń istnieje w repozytorium onecli/onecli-cli i kieruje ruch lokalnego agenta programistycznego przez bramę. Wdrażana tutaj aplikacja to wieloużytkownikowa aplikacja webowa: system kont, w którym pierwsze konto jest właścicielem instancji, baza danych konwersacji i sekretów oraz środowisko uruchomieniowe inicjujące kontenery.

Model oparty na użytkownikach stanowi fundament projektu. Z pliku README: „Tworzysz agenta dla każdej osoby, nadajesz mu niezbędne uprawnienia, a on pracuje w piaskownicy, kierowany przez bramę, która wstrzykuje poświadczenia i egzekwuje politykę”. Każdy agent posiada własny system plików i powłokę, własną stronę konwersacji, pamięć utrzymywaną przez platformę oraz umiejętności zdefiniowane jednokrotnie. Poświadczenia działają odwrotnie niż w typowej konfiguracji. Zamiast kopiować klucz API do środowiska każdej osoby, przechowujesz klucz w jednym miejscu i udostępniasz go agentom, które mają prawo z niego korzystać.

Wymagania wstępne

• Docker z wtyczką Compose w wersji 2.19 lub nowszej. Plik compose wykorzystuje usługę jednorazowej migracji, na której oczekuje API; ta forma zależności wymaga wersji 2.19.
• Pamięć RAM, która stanowi główne ograniczenie. Przed wyborem planu należy zapoznać się z sekcją dotyczącą doboru rozmiaru poniżej.
• Wolne porty loopback 10254, 10255, 10256 oraz 5432.

Instalacja PostgreSQL nie jest wymagana: plik compose uruchamia go jako usługę. Nie jest również wymagane środowisko Node.js ani Rust. Są one potrzebne wyłącznie w przypadku budowania ze źródeł, gdzie mise ustala wersję łańcucha narzędzi.

Ile piaskownic agentów mieści się na VPS?

Dokumentacja runnera podaje konkretne liczby zamiast szacunków. Każda piaskownica otrzymuje 2048 MB pamięci (RUNNER_SANDBOX_MEMORY_MB), jeden procesor (RUNNER_SANDBOX_CPUS) oraz 512 procesów (RUNNER_SANDBOX_PIDS). Limit współbieżności wynosi 4 (RUNNER_MAX_SANDBOXES), a dokumentacja zaleca około 10 GiB wolnej pamięci ponad bazowy stos, aby obsłużyć ten limit.

[
  {
    "plan": "2 GB box",
    "ram_gb": 2,
    "sandbox_slots": 0
  },
  {
    "plan": "4 GB box",
    "ram_gb": 4,
    "sandbox_slots": 1
  },
  {
    "plan": "8 GB box",
    "ram_gb": 8,
    "sandbox_slots": 3
  },
  {
    "plan": "16 GB box",
    "ram_gb": 16,
    "sandbox_slots": 7
  },
  {
    "plan": "32 GB box",
    "ram_gb": 32,
    "sandbox_slots": 15
  }
]

Liczba slotów wynika z obliczeń, a nie z testów wydajności: całkowita pamięć minus około 2 GB na PostgreSQL i cztery długo działające usługi, podzielone przez limit 2 GiB na piaskownicę. Na tej podstawie plan 2 GB box mieści 0 piaskownic, więc najtańszy plan w ogóle nie pozwala na uruchomienie hostowanego agenta. Plan 16 GB box pozostawia miejsce na 7, co jest wartością bezpiecznie przekraczającą domyślny limit czterech jednostek oraz zalecane 10 GiB wolnej pamięci. Plan 32 GB box pozwala na 15.

Dwa czynniki zmieniają te wyliczenia. Piaskownica z działającym procesem w tle nigdy nie przechodzi w stan spoczynku, więc zajmuje slot na stałe. Oznacza to, że należy dobrać RUNNER_MAX_SANDBOXES pod kątem trwałego obciążenia, a nie szczytowego momentu. Pamięć kończy się szybciej niż zasoby CPU. Każda piaskownica ma limit jednego procesora, więc cztery aktywne agenty wymagają czterech rdzeni, ale cztery bezczynne, lecz uruchomione agenty nadal zajmują 8 GiB pamięci.

Instalacja OneCLI przy użyciu Docker Compose

Oficjalna dokumentacja self-hostingowa podaje następującą sekwencję kroków. Wymaga ona zapisania trzech sekretów w pliku docker/.env obok pliku compose, a następnie uruchomienia stosu.

git clone https://github.com/onecli/onecli.git && cd onecli/docker
cat > .env <<EOF
SECRET_ENCRYPTION_KEY=$(head -c 32 /dev/urandom | base64)
GATEWAY_INTERNAL_SECRET=$(head -c 32 /dev/urandom | base64)
BETTER_AUTH_SECRET=$(head -c 32 /dev/urandom | base64)
COMPOSE_PROFILES=runner
EOF
chmod 600 .env
docker compose up -d --wait

Przed wykonaniem powyższego bloku należy zapoznać się z jego treścią. Znacznik heredoc nie jest ujęty w cudzysłów, co oznacza, że powłoka wykona każde polecenie head -c 32 /dev/urandom | base64 i zapisze wynik, zamiast traktować go jako tekst dosłowny. SECRET_ENCRYPTION_KEY to klucz AES-256-GCM dla każdego sekretu w bazie danych. GATEWAY_INTERNAL_SECRET uwierzytelnia bramę (gateway) względem API. BETTER_AUTH_SECRET służy do podpisywania ciasteczek sesyjnych. COMPOSE_PROFILES=runner jest najważniejszą linią, ponieważ usługa uruchomieniowa (runner) znajduje się za profilem Compose: pominięcie jej spowoduje, że stos uruchomi się poprawnie, ale piaskownica agenta (agent sandbox) nigdy nie wystartuje.

--wait blokuje powłokę do momentu, aż każda usługa zgłosi stan healthy, więc kod wyjścia różny od zera jest pierwszym sygnałem wystąpienia błędu. W takim przypadku należy sprawdzić, które kontenery faktycznie zostały uruchomione.

docker compose ps
docker compose logs migrations

Należy przypiąć wersję. ONECLI_VERSION ustawia tag dla wszystkich usług jednocześnie, a obraz piaskownicy agenta podąża za nim, chyba że RUNNER_AGENT_IMAGE wskazuje inną lokalizację. Według stanu na 19 sierpnia 2026 aktualne wydanie to v2.0.1, opublikowane 18 sierpnia 2026. Należy dodać tę wartość do tego samego pliku i ponownie uruchomić stos.

echo 'ONECLI_VERSION=v2.0.1' >> .env
docker compose up -d --wait

Dostępny jest również instalator curl -fsSL https://onecli.sh/install | sh, który zapisuje konfigurację w ~/.onecli/.env i wykonuje te same czynności. Ścieżka z użyciem Docker Compose pozwala na weryfikację każdego pliku przed uruchomieniem czegokolwiek i jest zalecana na serwerach, na których działają już inne stosy Compose. Budowanie ze źródeł to trzecia metoda, udokumentowana jako pnpm install, a następnie pnpm run setup w sklonowanym repozytorium. Ta ścieżka wymaga zainstalowania mise, języka Rust dla bramy oraz Docker, i jest przeznaczona dla użytkowników zamierzających modyfikować kod źródłowy.

Dostęp do panelu z poziomu laptopa

Każdy opublikowany port w dostarczonym pliku compose jest powiązany z ${ONECLI_BIND_HOST:-127.0.0.1}. Na serwerze VPS oznacza to, że panel działa, ale jest niedostępny z zewnątrz. To ustawienie domyślne jest prawidłowe. Należy je zachować i skorzystać z tunelu:

ssh -N -L 10254:127.0.0.1:10254 you@your-server

Teraz otwórz http://localhost:10254 na swoim laptopie. Ruch odbywa się przez połączenie SSH, więc niezaszyfrowany panel nie jest dostępny w publicznym Internecie i nie wymaga otwierania dodatkowych portów w zaporze sieciowej.

Ustawienie ONECLI_BIND_HOST=0.0.0.0 publikuje panel przez zwykły protokół HTTP, udostępniając jednocześnie bazę danych PostgreSQL. Jeśli z panelu ma korzystać więcej osób, należy umieścić reverse proxy z obsługą TLS (transport layer security) przed portem 10254 i pozostawić adres powiązania bez zmian. Należy to wykonać, zanim instancja zyska właściciela. Dokumentacja źródłowa jasno określa powód: „Dopóki tego nie zrobisz, instancja nie ma właściciela, a na dostępnym hoście pierwsza osoba, która uzyska dostęp, stanie się nim”. Jeśli takie proxy obsługuje już inne Twoje aplikacje, przekierowanie uwierzytelniania przez własną warstwę logowania jednokrotnego (SSO) zabezpieczy panel mechanizmem, z którego korzysta już Twój zespół. Dzięki temu usunięcie użytkownika w jednym miejscu zamyka dostęp również tutaj.

Utworzenie pierwszego konta i nadanie klucza modelu

Otwórz panel sterowania i niezwłocznie utwórz konto. To konto jest właścicielem instancji, a po jego utworzeniu dołączenie do niej wymaga zaproszenia.

Następnie zapisz klucz modelu przed utworzeniem agenta. Hostowany agent wymaga nadanego klucza modelu, a kolejność działań ma znaczenie: zapisz klucz w panelu sterowania, nadaj go agentowi, a dopiero potem rozpocznij konwersację. Pominięcie nadania uprawnień spowoduje, że środowisko izolowane (sandbox) nigdy się nie uruchomi, co objawia się tym, że agent pozostaje w stanie bezczynności.

Nadawaj uprawnienia w sposób ograniczony. Każdy agent otrzymuje tylko to, co mu przydzielono, a brama (gateway) egzekwuje to przy każdym żądaniu. Dzięki temu agent mający dostęp do jednego repozytorium nie ma możliwości uzyskania dostępu do klucza dostawcy płatności. Ta sama lista uprawnień stanowi narzędzie kontroli wydatków. Agent przypisany do użytkownika, który może korzystać z dowolnego posiadanego modelu, generuje indywidualne koszty, dlatego warto zapoznać się z informacjami o tym, jak ograniczyć wydatki agenta na wywołania modeli, zanim przydzielisz ich dziesięć.

W jaki sposób bramka chroni klucze przed agentami

Bramka to proxy HTTPS napisane w Rust, nasłuchujące na porcie 10255. Klient HTTP agenta jest skierowany na ten port, a sam agent przechowuje symbol zastępczy poświadczeń zamiast rzeczywistych danych. Bramka dopasowuje żądanie wychodzące do uprawnień danego agenta, odszyfrowuje właściwy sekret, wstawia go do żądania i przesyła dalej. Sekrety znajdują się w PostgreSQL, zaszyfrowane za pomocą AES-256-GCM (Advanced Encryption Standard, 256-bit, Galois/Counter Mode) i są odszyfrowywane wyłącznie w momencie żądania. Każde wywołanie jest rejestrowane wraz z tożsamością agenta i celem, co tworzy ścieżkę audytu niemożliwą do uzyskania, gdy klucze znajdują się w profilach powłoki dziesięciu różnych użytkowników.

Dwa mechanizmy decydują o sposobie wdrożenia:

• Przechwytywanie HTTPS to atak typu man-in-the-middle. Bramka generuje lokalny urząd certyfikacji (CA), agent darzy go zaufaniem, a bramka kończy połączenie TLS agenta i otwiera nowe do usługi nadrzędnej. Dlatego agent, którego klient HTTP nie ufa urzędowi certyfikacji bramki, kończy działanie błędem weryfikacji certyfikatu, a nie błędem uwierzytelniania.
• Agent identyfikuje się za pomocą nagłówka Proxy-Authorization. Na pojedynczej maszynie, gdzie agenci i bramka współdzielą wewnętrzną sieć Docker, nagłówek ten nigdy nie opuszcza sieci, którą zarządzasz. W przypadku skierowania agenta spoza maszyny na bramkę, port proxy wymaga własnego TLS, ponieważ wspomniany nagłówek jest tokenem typu bearer.

Uczciwy kompromis: bramka odczytuje każde żądanie wysyłane przez agentów w postaci jawnej, zgodnie z założeniami projektowymi. Jest to najbardziej wrażliwy proces na maszynie. Traktuj hosta bramki odpowiednio i ogranicz liczbę osób posiadających dostęp do logowania, stosując zasadę minimalnych uprawnień użytkowników Linux.

Dlaczego runner nie wymaga portów przychodzących

Runner działa wyłącznie w trybie wychodzącym. Zgodnie z dokumentacją: „nie utrzymuje żadnych portów dostępnych z zewnątrz, dzięki czemu laptop, domowe laboratorium czy VPC za NAT działają bez ruchu przychodzącego, tuneli i konieczności terminacji TLS”. NAT to translacja adresów sieciowych, czyli mechanizm realizowany przez domowy router. Runner łączy się z płaszczyzną sterowania (control plane) i pobiera z niej zadania, więc nie ma potrzeby przekierowywania portów ani otwierania żadnych połączeń.

Taka konstrukcja sprawdza się w sieci piaskownicy (sandbox). Plik compose definiuje drugą sieć oznaczoną internal: true, co w Docker oznacza brak jakiejkolwiek trasy wyjściowej poza hosta. Piaskownice dołączają do tej sieci. Brama (gateway) posiada interfejsy w obu sieciach, więc stanowi jedyną drogę wyjścia. Dokumentacja runnera jasno to określa: „sieć internal z bramą posiadającą interfejs w tej sieci sprawia, że ruch wychodzący ograniczony do bramy jest wymuszony, a nie tylko sugerowany”. Agent, który próbowałby wysłać kod źródłowy na wybrany przez siebie adres, nie ma technicznej możliwości nawiązania takiego połączenia.

Warto zweryfikować to samodzielnie na własnym serwerze, zamiast polegać wyłącznie na powyższym opisie.

docker network ls
docker network inspect onecli-sandboxes | grep -i internal

Powinieneś zobaczyć "Internal": true. Jeśli wynik to false, kontrola ruchu wychodzącego jest wyłączona, a brama pełni jedynie funkcję sugestii. Użyj nazwy sieci piaskownicy, którą zwraca docker network ls, ponieważ onecli-sandboxes to tylko wartość domyślna.

Jak silna jest piaskownica OneCLI?

Należy przeczytać tę sekcję uważnie, ponieważ termin „piaskownica” (sandboxed) ma duże znaczenie w opisie projektu, podczas gdy sam mechanizm został udokumentowany tylko w jednym miejscu.

Plik README podaje, że każdy agent otrzymuje „własną, odizolowaną piaskownicę z systemem plików i powłoką” oraz wskazuje Sandbox Supervisor jako komponent, który „działa wewnątrz każdej piaskownicy, korzystając z niezależnego od dostawcy interfejsu, co pozwala na wymianę środowiska uruchomieniowego agenta”. Żadne z tych zdań nie precyzuje, na czym polega izolacja. Dokumentacja runnera wyjaśnia to: domyślnym backendem jest Docker (RUNNER_BACKEND=docker), a piaskownica to kontener Docker z limitami pamięci, procesora i liczby procesów, podłączony do sieci wewnętrznej. Kod zawiera punkty styku dla innych backendów, a dokumentacja wymienia Kubernetes oraz microVM jako moduły, które ktoś musiałby zaimplementować. Obecnie na Twoim serwerze piaskownica jest kontenerem.

Równie istotne jest to, czego dokumentacja nie zawiera. Brak modelu zagrożeń. Nie ma informacji o uruchamianiu Docker daemon w trybie rootless, o mapowaniu przestrzeni nazw użytkowników (user namespace remapping), o profilach seccomp lub AppArmor wykraczających poza domyślne ustawienia Docker, ani deklaracji o izolacji na poziomie jądra, takiej jak gVisor czy microVM. Należy zatem przyjąć interpretację zawężającą. Limity dotyczą zasobów. Sieć wewnętrzna stanowi realną kontrolę ruchu wychodzącego. Izolacja między agentem a hostem ogranicza się do tego, co zapewnia standardowy kontener Docker, a kontener współdzieli jądro systemu z hostem.

Istnieje drugi fakt, który należy wziąć pod uwagę. Usługa runnera montuje /var/run/docker.sock, ponieważ w ten sposób tworzone są piaskownice. Dostęp do gniazda Docker jest równoznaczny z uprawnieniami root na hoście, ponieważ każdy, kto może wywołać to API, może uruchomić kontener z zamontowanym wewnątrz systemem plików hosta. Każdy runner oparty na Docker działa w ten sposób. Konsekwencją jest to, że proces runnera jest równie wrażliwy, co gateway.

Należy traktować tę granicę jako niepotwierdzoną, dopóki autorzy projektu nie przedstawią stosownej dokumentacji. W praktyce oznacza to trzy zasady:

1. Uruchamiaj OneCLI na serwerze, który nie pełni żadnych innych funkcji. Żadnych niezwiązanych usług produkcyjnych, współdzielonych baz danych ani danych innych zespołów.
2. Załóż, że agent, który uzyska możliwość wykonania dowolnego kodu wewnątrz piaskownicy, może wydostać się na hosta. Zapewnij możliwość przetrwania takiego zdarzenia dzięki kopiom zapasowym przechowywanym poza serwerem.
3. Przeczytaj apps/runner/src lub zapytaj autorów projektu, zanim poinformujesz współpracownika, że agent jest w pełni odizolowany.

Aby zobaczyć, jak wygląda udokumentowana granica bezpieczeństwa i jakie pytania warto zadać autorom projektu, porównaj to z tym, jak wygląda rzeczywista granica piaskownicy agenta. Różnica polega na tym, czy ktoś opisał mechanizm działania i to, czego on nie powstrzymuje.

Podział licencji i powody, dla których należy sprawdzić ją przed rozpoczęciem budowy

Rdzeń OneCLI jest objęty licencją Apache-2.0, co pozwala na jego samodzielne hostowanie w środowisku produkcyjnym. Katalogi o nazwie ee/ podlegają oddzielnej licencji OneCLI Enterprise License: bezpłatnej do celów programistycznych, testowych i ewaluacyjnych, przy czym użycie produkcyjne wymaga subskrypcji. Informacje o wydaniu v2.0.1 z dnia 18 sierpnia 2026 roku wspominają o przywróceniu pliku licencji Apache-2.0 wykrywanego przez GitHub, dlatego oznaczenie na stronie repozytorium uległo ostatnio zmianie. Należy sprawdzić tag, który faktycznie jest wdrażany, zamiast polegać na podsumowaniu sporządzonym w innym terminie.

cd onecli && find . -type d -name ee -not -path '*/node_modules/*'

Wszystko, co znajduje się w tych ścieżkach, stanowi część komercyjną. Jeśli funkcja, na której planujesz polegać, znajduje się w tym obszarze, wyceń ją przed zbudowaniem wokół niej procesu.

Aktualizacje, migracje i jeden plik, którego nie można utracić

Aktualizacje polegają na zmianie wersji i restarcie. Jednorazowa usługa migracji uruchamia się przed API przy każdym up. Jeśli migracja zakończy się niepowodzeniem, stos odmawia uruchomienia, zamiast pracować na częściowo zmigrowanym schemacie. Jest to pożądane zachowanie, ponieważ nieudana aktualizacja jest widoczna jako awaria, a nie jako cicha korupcja danych, co wyjaśnia docker compose logs migrations.

cd onecli/docker
docker compose pull
docker compose up -d --wait
docker compose logs migrations

W przypadku instalacji za pomocą skryptu instalacyjnego, należy uruchomić go ponownie zamiast ręcznego pobierania obrazów. Dzięki temu plik compose pozostaje zgodny z wersjami obrazów, do których się odwołuje.

Należy wykonać kopię zapasową dwóch elementów. PostgreSQL przechowuje agentów, konwersacje, pamięć oraz zaszyfrowane sekrety. Plik docker/.env zawiera SECRET_ENCRYPTION_KEY. Bez tego klucza zaszyfrowane sekrety są nieczytelne, więc sam zrzut bazy danych nie pozwala na przywrócenie użytecznej instancji.

cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backup

Obie kopie należy przechowywać poza serwerem. Procedura jest identyczna jak w przypadku każdego stosu Compose przechowującego stan. Jeśli użytkownik posiada już harmonogram, w ramach którego wykonuje kopie zapasowe i aktualizuje stos Docker Compose, należy dodać te dwie ścieżki do listy zadań i nie martwić się o nie w przyszłości.

Gdy rozwiązanie nie działa

• Stos nie osiąga stanu gotowości, a docker compose up -d --wait kończy pracę z kodem wyjścia innym niż zero. W pierwszej kolejności należy zapoznać się z docker compose logs migrations, ponieważ API celowo oczekuje na tę usługę.
• Agent pozostaje w stanie bezczynności i nie pojawia się żadna piaskownica (sandbox). Należy sprawdzić, czy COMPOSE_PROFILES=runner znajduje się w docker/.env oraz czy docker compose ps wyświetla uruchomiony proces (runner). Następnie należy zweryfikować, czy agent posiada przyznany klucz modelu, ponieważ piaskownice nie uruchamiają się bez niego.
• Brak dostępnych slotów. Wartość domyślna RUNNER_MAX_SANDBOXES to 4, a piaskownica z działającym procesem w tle zajmuje swój slot na stałe. Polecenie docker ps pokazuje rzeczywisty stan aktywnych procesów.
• Kontenery znikają lub host działa bardzo wolno. Wystąpił brak pamięci operacyjnej. Plik dmesg -T | grep -i oom rejestruje zdarzenia przerwania procesów przez mechanizm OOM (Out-of-Memory) jądra systemu, a pojedyncza piaskownica może samodzielnie zająć 2048 MB pamięci.
• Wywołania HTTPS agenta kończą się błędami weryfikacji certyfikatu zamiast błędami uwierzytelniania. Klient HTTP agenta nie ufa urzędowi certyfikacji bramy.
• Stare kontenery lub wolumeny pozostają w systemie po usunięciu agenta. Proces runnera przeprowadza synchronizację co 60 sekund i usuwa osierocone zasoby starsze niż RUNNER_ORPHAN_GRACE_SECONDS (wartość domyślna to 3600), dlatego przed zgłoszeniem wycieku zasobów należy odczekać godzinę.

Czy to rozwiązanie jest odpowiednie dla Twoich potrzeb?

Test dopasowania jest krótki. OneCLI zyskuje na znaczeniu w środowisku, w którym kilka osób potrzebuje dostępu do agenta, a poświadczenia powinny znajdować się w jednym miejscu: jeden magazyn do rotacji kluczy, jeden dziennik audytu do analizy, jeden panel sterowania, w którym odebranie dostępu użytkownikowi faktycznie go unieważnia. Jest to realny problem operacyjny, a kopiowanie klucza API na sześć różnych laptopów jest nieefektywnym rozwiązaniem.

Dla jednej osoby jest to zbyt rozbudowana infrastruktura, która nie przynosi korzyści. Uruchamianie PostgreSQL, płaszczyzny sterowania (control plane), bramy (gateway) oraz agenta wykonawczego (runner) tylko po to, by obsłużyć jednego użytkownika, jest nieuzasadnione. Problem zarządzania poświadczeniami, który rozwiązuje brama, praktycznie nie istnieje, gdy klucz posiada tylko jedna osoba. W takim przypadku lepiej uruchomić pojedynczy zestaw narzędzi na mniejszej maszynie: pojedynczy agent na VPS wykonuje to zadanie przy ułamku zużycia pamięci. Jeśli jeszcze nie podjęto decyzji co do wyboru rozwiązania, zestawienie w porównanie samodzielnie hostowanych agentów AI będzie bardziej opłacalnym pierwszym krokiem.

FAQ

Jakie są minimalne wymagania serwerowe do samodzielnego hostowania OneCLI?

Wymagany jest Docker z wtyczką Compose w wersji 2.19 lub nowszej oraz odpowiednia ilość pamięci RAM. PostgreSQL jest dostarczany w pliku compose, więc nie wymaga osobnej instalacji. Pamięć RAM determinuje plan: runner domyślnie przydziela 2048 MB na piaskownicę agenta. Dokumentacja zaleca około 10 GiB wolnej pamięci poza podstawowym stosem, aby obsłużyć domyślny limit czterech piaskownic, a około 2 GB jest potrzebne dla PostgreSQL i czterech usług działających w tle. Serwer z 4 GB RAM obsłuży jednego agenta jednocześnie. Serwer z 16 GB RAM pozwala na swobodną obsługę domyślnego limitu. VPS z 1 GB lub 2 GB RAM nie uruchomi hostowanego agenta.

Czy OneCLI wymaga PostgreSQL, czy może korzystać z SQLite?

Wymagany jest PostgreSQL. DATABASE_URL jest udokumentowany jako ciąg połączenia PostgreSQL, dostarczony plik compose uruchamia postgres:18-alpine z wolumenem pgdata, a osobna usługa migracji stosuje schemat przed uruchomieniem API. Brak udokumentowanej opcji dla SQLite. Jeśli PostgreSQL działa już w innym miejscu, należy wskazać na niego DATABASE_URL i zachować usługę migracji, ponieważ nieudana migracja zatrzymuje stos, zamiast pozwalać na działanie z częściowo wdrożonym schematem.

Czy piaskownica agenta OneCLI stanowi realną barierę bezpieczeństwa?

Udokumentowany mechanizm to kontener Docker z limitami pamięci, CPU i procesów, podłączony do sieci oznaczonej jako internal: true, co uniemożliwia ruch wychodzący poza bramę sieciową. Kontrola ruchu wychodzącego jest skuteczna i można ją zweryfikować za pomocą docker network inspect. Izolacja hosta opiera się na standardowych mechanizmach kontenerów; producent nie publikuje modelu zagrożeń, nie deklaruje pracy w trybie rootless ani z użyciem user-namespace, nie stosuje też barier jądra takich jak gVisor czy microVM. Runner montuje również /var/run/docker.sock, co jest równoważne z dostępem root na hoście. Granicę między agentem a hostem należy traktować jako niezweryfikowaną, dopóki producent nie przedstawi stosownych zapewnień. OneCLI należy uruchamiać na dedykowanym serwerze, a kopie zapasowe przechowywać poza nim.

Czy muszę otwierać jakiekolwiek porty przychodzące dla OneCLI?

Nie. Runner działa wyłącznie w trybie wychodzącym i nie nasłuchuje na portach dostępnych z zewnątrz, dzięki czemu działa za NAT bez konieczności tworzenia tuneli. Plik compose domyślnie wiąże pulpit nawigacyjny, bramę, API i PostgreSQL z 127.0.0.1. Dostęp do pulpitu nawigacyjnego można uzyskać przez tunel SSH lub umieszczając reverse proxy z terminacją TLS przed portem 10254, jeśli dostęp jest potrzebny wielu użytkownikom. Brama na porcie 10255 służy agentom, a na pojedynczym serwerze agenci łączą się z nią poprzez wewnętrzną sieć Docker.

Czy OneCLI jest darmowy do użytku wewnątrz firmy?

Rdzeń oprogramowania jest objęty licencją Apache-2.0 i samodzielne hostowanie w środowisku produkcyjnym jest dozwolone bez licencji komercyjnej. Katalogi o nazwie ee/ podlegają licencji OneCLI Enterprise License, która jest darmowa do celów programistycznych, testowych i ewaluacyjnych, ale wymaga subskrypcji w środowisku produkcyjnym. Podział ten zmienia się między wydaniami, a notatki do wersji v2.0.1 z 18 sierpnia 2026 wspominają o przywróceniu pliku licencji Apache-2.0 wykrywalnego przez GitHub. Przed zbudowaniem workflow w oparciu o konkretną funkcję należy sprawdzić LICENSE oraz zawartość katalogów ee/ w konkretnym tagu, który jest wdrażany.