Samodzielny hosting OneCLI: konfiguracja Docker Compose
Dowiedz się, jak zainstalować OneCLI na własnym serwerze VPS. Instrukcja obejmuje konfigurację PostgreSQL, wymagania sprzętowe 2 GiB RAM na agenta oraz architekturę Docker.
Co zyskujesz, uruchamiając OneCLI we własnym zakresie
Uruchom OneCLI samodzielnie, a każdy członek zespołu otrzyma 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 odpowiednie zasoby sprzętowe. Domyślna konfiguracja przewiduje limit 2 GiB pamięci RAM na sandbox agenta, dlatego należy oddzielnie zaplanować zasoby dla podstawowego stosu oraz rzeczywiste zapotrzebowanie na pamięć operacyjną agentów.
Stos składa się z ośmiu komponentów. Zrozumienie roli każdego z nich ułatwi lekturę dalszej części przewodnika.
- Panel webowy (Next.js), port
10254. Służy do tworzenia agentów, prowadzenia czatów, edycji pamięci i umiejętności, a także zarządzania połączeniami i sekretami. - Serwer API, port
10256. Płaszczyzna sterowania: obsługa bazy danych, zarządzanie konwersacjami i kolejkami zadań. - Brama Rust, port
10255. Przechwytuje żądania wychodzące od agentów i wstrzykuje poświadczenia. - Runner. Dokumentacja README opisuje go jako komponent, który "uruchamia, wstrzymuje i usuwa środowiska sandbox agentów. Działa wyłącznie w trybie wychodzącym i nie ma dostępu do bazy danych".
- Sandbox Supervisor. Dokumentacja README opisuje go jako proces działający "wewnątrz każdego sandboxa, komunikujący się za pomocą niezależnego od dostawcy interfejsu, co pozwala na wymianę środowiska uruchomieniowego agenta".
- Terminator SSH, port
10257. Dokumentacja README określa go jako "bramę wejściową SSH": kończy połączenia SSH przy użyciu krótkotrwałych certyfikatów wydawanych przez API i przekazuje każdą sesję do sandboxa agenta. Działa w ramach tego samego profilurunnerco runner. - 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-alpinez wolumenempgdata.
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ń faktycznie istnieje w repozytorium onecli/onecli-cli i kieruje ruch lokalnego agenta programistycznego przez bramę. Wdrażane tutaj rozwiązanie to wieloużytkownikowa aplikacja webowa: system kont z organizacjami i zaproszeniami, baza danych konwersacji i sekretów oraz środowisko uruchomieniowe inicjujące kontenery.
Model przypisany do osoby stanowi podstawę 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ę bezpieczeństwa”. 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 jednorazowo. Poświadczenia działają odwrotnie niż w typowej konfiguracji. Zamiast kopiować klucz API do środowiska każdej osoby, przechowuje się go w jednym miejscu i udostępnia agentom, które mają prawo z niego korzystać.
Wymagania wstępne dla serwera
- Docker z wtyczką Compose w wersji 2.24.0 lub nowszej. Dostarczony plik compose wykorzystuje opcjonalne mapowania
env_filezrequired: false, które Docker wspiera od wersji 2.24.0. Komentarze dotyczące migracji wskazują wersję 2.19 jako minimalną dla obsługi zależności typu one-shot w ramachup --wait, jednak nie obejmuje to opcjonalnych plików środowiskowych używanych w tym pliku. - Pamięć RAM, która stanowi główne ograniczenie. Przed wyborem planu należy zapoznać się z sekcją dotyczącą doboru zasobów poniżej.
- Wolne porty loopback
10254,10255,10256,10257oraz5432. Port10257jest głównym punktem dostępu SSH, który uruchamia się wraz z profilemrunneraktywowanym w tym przewodniku.
Nie ma potrzeby samodzielnej instalacji PostgreSQL: plik compose uruchamia go jako usługę. Kreator konfiguracji opisany poniżej wymaga obecności Node.js oraz pnpm na hoście. Praca nad samym kodem wykorzystuje również mise do ustalenia wersji łańcucha narzędzi, w tym Rust dla bramy (gateway).
Ile piaskownic agenta mieści się na VPS?
Dokumentacja runnera podaje konkretne liczby zamiast szacunków. Każda piaskownica ma limit 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.
Dane, na których opiera się ten wykres
[
{
"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 zarezerwowane dla PostgreSQL i innych usług działających w tle, podzielone przez limit 2 GiB na piaskownicę. Na tej podstawie 2 GB box określa budżet dla 0 piaskownic przy pełnym wykorzystaniu pamięci; zero oznacza brak budżetu przy pełnym obciążeniu zgodnie z tymi założeniami, a nie odmowę uruchomienia agenta przez Docker. Plan 16 GB box zapewnia miejsce dla 7 piaskownic, co jest wartością bezpiecznie przekraczającą domyślny limit czterech oraz zalecane 10 GiB wolnej pamięci. Plan 32 GB box ustawia 15. Uruchomienie więcej niż czterech jednocześnie wymaga również zwiększenia RUNNER_MAX_SANDBOXES.
Dwa czynniki modyfikują te obliczenia. Piaskownica z działającym procesem w tle nigdy nie przechodzi w stan uśpienia, więc zajmuje slot na stałe. Oznacza to, że RUNNER_MAX_SANDBOXES należy planować pod kątem stałego obciążenia, a nie szczytowych wartości. Platforma nakłada na to ograniczenie: domyślnie każdy runner utrzymuje maksymalnie RUNNER_MAX_SANDBOXES minus jeden piaskownic w stanie aktywnym (nigdy mniej niż jedną, wartość można nadpisać przez MAX_HELD_AWAKE_SANDBOXES w API). Powyżej tego limitu usuwana jest piaskownica najdłużej pozostająca w bezczynności, a monitorowany proces zgłaszany jest jako utracony. Zużycie pamięci i procesora zależy od wykonywanej pracy. Każda piaskownica ma limit jednego procesora, więc cztery aktywne agenty mogą wykorzystać cztery rdzenie, jednak limit 2 GiB pamięci jest sufitem, a nie rezerwacją: cztery bezczynne, lecz aktywne agenty nie zużywają automatycznie 8 GiB.
Ustawienia runnera, które można zmienić
RUNNER_MAX_SANDBOXES(domyślnie4): ile piaskownic działa jednocześnie.RUNNER_SANDBOX_MEMORY_MB(domyślnie2048): limit pamięci na piaskownicę.RUNNER_SANDBOX_CPUS(domyślnie1): limit procesora na piaskownicę.RUNNER_SANDBOX_PIDS(domyślnie512): limit procesów na piaskownicę.RUNNER_NETWORK_INTERNAL(domyślnietrue): utrzymuje sieć piaskownicy bez trasy wyjściowej. Należy pozostawić włączone.RUNNER_SANDBOX_NETWORK(domyślnieonecli-sandboxes): sieć, do której dołączają piaskownice.RUNNER_RECONCILE_SECONDS(domyślnie60): częstotliwość synchronizacji stanu przez runnera.RUNNER_ORPHAN_GRACE_SECONDS(domyślnie3600): czas, po którym usuwane są osierocone kontenery i wolumeny.RUNNER_AGENT_IMAGE: nadpisuje obraz piaskownicy, który w przeciwnym razie jest zgodny zONECLI_VERSION.
Instalacja OneCLI przy użyciu Docker Compose
Oryginalna dokumentacja self-hostingowa przewiduje zapisanie trzech sekretów w docker/.env obok pliku compose. Procedura ta pomija token runnera, grupę gniazda Docker oraz poświadczenia SSH wymagane przez aktywowane usługi, dlatego przed uruchomieniem stosu należy wykonać kreator konfiguracji.
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
cd ..
pnpm install
pnpm run setup
cd docker
docker compose up -d --waitPrzed uruchomieniem bloku należy zapoznać się z jego treścią. Znacznik heredoc nie jest ujęty w cudzysłów, więc powłoka wykonuje każde head -c 32 /dev/urandom | base64 i zapisuje wynik zamiast dosłownego tekstu. SECRET_ENCRYPTION_KEY to klucz AES-256-GCM dla każdego sekretu w bazie danych. GATEWAY_INTERNAL_SECRET uwierzytelnia bramę w API. BETTER_AUTH_SECRET podpisuje ciasteczka sesyjne. COMPOSE_PROFILES=runner to najważniejszy wiersz, ponieważ usługa runnera znajduje się za profilem Compose: pominięcie go sprawi, że stos uruchomi się poprawnie, ale żadna piaskownica agenta nie zostanie zainicjowana.
--wait oczekuje na uruchomienie lub osiągnięcie stanu healthy przez usługi oraz na pomyślne zakończenie zależności migracji, więc niezerowy kod wyjścia jest pierwszym sygnałem błędu. Następnie należy sprawdzić, które kontenery faktycznie zostały uruchomione.
docker compose ps
docker compose logs migrationsNależ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ę. Należy użyć samego numeru wersji: opublikowane tagi obrazów nie zawierają prefiksu v. Na dzień 1 listopada 2026 bieżące wydanie to v2.17.0, opublikowane 31 października 2026. Należy dodać je do tego samego pliku, a następnie użyć udokumentowanej ścieżki aktualizacji, aby działające piaskownice również przeszły na ten obraz.
echo 'ONECLI_VERSION=2.17.0' >> .env
cd ..
pnpm run setup --upgrade
cd dockerDostępny jest również instalator curl -fsSL https://onecli.sh/install | sh, który zapisuje konfigurację w ~/.onecli/.env i wykonuje analogiczne zadania. Ustawia on ONECLI_VERSION=latest dla własnego uruchomienia, co nadpisuje przypięcie przechowywane tylko w pliku .env. Ścieżka Compose pozwala na odczytanie każdego pliku przed uruchomieniem czegokolwiek i jest zalecana na serwerach, na których działają już inne stosy Compose. Powyższa konfiguracja checkoutu aktualizuje się za pomocą pnpm run setup --upgrade. Ta ścieżka wymaga Node.js oraz pnpm na hoście, a praca nad samym kodem dodaje mise oraz Rust dla bramy, więc jest odpowiednia dla osób zamierzających modyfikować OneCLI. W przypadku Kubernetes, wydanie v2.11.0 (8 października 2026) dodało wykres Helm; bieżący wykres uruchamia piaskownice agentów jako Jobs z trwałymi wolumenami, bez demona Docker, oraz dokumentuje wymagane sekrety, bazę danych i konfigurację routingu.
Dostęp do panelu sterowania 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 sterowania działa, ale jest niedostępny z zewnątrz. To ustawienie domyślne jest prawidłowe. Należy je zachować i użyć tunelu:
ssh -N -L 10254:127.0.0.1:10254 you@your-serverTeraz otwórz http://localhost:10254 na swoim laptopie. Ruch odbywa się przez połączenie SSH, dzięki czemu niezaszyfrowany panel nie jest wystawiony w publicznym Internecie i nie ma potrzeby otwierania dodatkowych portów w zaporze sieciowej.
Ustawienie ONECLI_BIND_HOST=0.0.0.0 publikuje panel sterowania przez zwykły protokół HTTP, a wraz z nim bazę danych PostgreSQL z domyślnym hasłem z pliku compose wynoszącym onecli, chyba że zdefiniowano POSTGRES_PASSWORD. Powoduje to również wystawienie bramy SSH na porcie 10257, czyli usługi montującej gniazdo Docker. Jeśli z panelu ma korzystać więcej osób, należy umieścić przed nim reverse proxy z obsługą TLS (transport layer security) i pozostawić adres powiązania bez zmian. Ustaw ONECLI_EXTERNAL_URL na adres URL HTTPS i użyj konfiguracji reverse proxy dostarczonej przez producenta, która kieruje ścieżki panelu, API oraz bramy do odpowiednich usług. Samo proxy nie chroni przed niepowołanymi osobami. Dokumentacja self-hosting wskazuje, że rejestracja jest otwarta z założenia i nie posiada przełącznika umożliwiającego jej wyłączenie: każdy, kto uzyska dostęp do panelu, może utworzyć konto, które otrzymuje własną organizację, a zaproszenie jest wymagane jedynie do dołączenia do Twojej organizacji. Zaleca się utrzymywanie panelu za granicą sieciową. Jeśli to proxy obsługuje już inne Twoje aplikacje, przekierowanie uwierzytelniania przez własną warstwę single sign-on umieszcza panel za logowaniem, z którego korzysta już Twój zespół, dzięki czemu usunięcie użytkownika w jednym miejscu zamyka dostęp również tutaj.
Utworzenie pierwszego konta i przyznanie klucza modelu
Otwórz pulpit nawigacyjny i niezwłocznie utwórz konto. Każde nowe konto otrzymuje własną organizację, a współpracownicy dołączają do niej poprzez zaproszenie. Rejestracja pozostaje otwarta, co stanowi kolejny powód, dla którego pulpit nawigacyjny powinien znajdować się za tunelem lub uwierzytelnionym proxy. W przypadku aktualizacji z wersji wydanej przed wprowadzeniem logowania, należy zarejestrować się natychmiast: dokumentacja self-hosting wskazuje, że istniejące dane zostaną przypisane do pierwszego zarejestrowanego konta, więc na dostępnym publicznie hoście należy zadbać, aby to konto należało do administratora.
Następnie zapisz klucz modelu przed utworzeniem agenta. Hostowany agent wymaga przyznanego klucza modelu, a kolejność działań ma znaczenie: zapisz klucz w pulpicie nawigacyjnym, przyznaj go agentowi, a dopiero potem rozpocznij konwersację. Pominięcie przyznania uprawnień spowoduje, że piaskownica nie zostanie uruchomiona; agent odpowie w wątku, wyjaśniając, że wymaga klucza modelu.
Przyznawaj uprawnienia w sposób ograniczony. Każdy agent otrzymuje tylko to, co zostało mu przydzielone, a brama wymusza to przy każdym żądaniu, więc agent mający dostęp do jednego repozytorium nie ma ścieżki dostępu do klucza dostawcy płatności. Ta sama lista uprawnień stanowi narzędzie kontroli wydatków. Agent przypisany do osoby, który może wywoływać dowolny posiadany model, generuje indywidualne koszty, dlatego warto zapoznać się z informacjami o tym, jak ograniczyć wydatki agenta na wywołania modeli, zanim przydzieli się ich dziesięć.
W jaki sposób gateway chroni klucze przed agentami
Gateway to proxy HTTPS napisane w języku Rust, nasłuchujące na porcie 10255. Klient HTTP agenta jest skierowany na ten port, a agent używa symbolu zastępczego zamiast rzeczywistych danych uwierzytelniających. Gateway dopasowuje żądanie wychodzące do uprawnień danego agenta, odszyfrowuje właściwy sekret, wstawia go do żądania i przesyła dalej. Sekrety są przechowywane w PostgreSQL, zaszyfrowane za pomocą AES-256-GCM (Advanced Encryption Standard, 256-bit, Galois/Counter Mode) i odszyfrowywane wyłącznie w momencie żądania. Każde wywołanie jest logowane 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 wielu użytkowników.
O wdrożeniu decydują dwa mechanizmy.
- Przechwytywanie HTTPS to działanie typu man-in-the-middle. Gateway generuje lokalny urząd certyfikacji (CA), agent darzy go zaufaniem, a gateway 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 gatewaya, zgłasza błąd weryfikacji certyfikatu, a nie błąd uwierzytelniania.
- Agent identyfikuje się za pomocą nagłówka
Proxy-Authorization. Na pojedynczej maszynie, gdzie agenci i gateway współdzielą wewnętrzną sieć Docker, nagłówek ten nigdy nie opuszcza sieci, którą zarządzasz. W przypadku agenta spoza maszyny, skierowanego na gateway, należy zabezpieczyć połączenie za pomocą VPN lub transportu TLS, ponieważ nagłówek ten jest tokenem typu bearer; producent zaleca użycie VPN dla surowego portu proxy CONNECT.
Uczciwy kompromis: gateway z założenia odczytuje każde żądanie wysyłane przez agentów w postaci jawnej. Jest to najbardziej wrażliwy proces na maszynie. Traktuj hosta z odpowiednią starannością i ogranicz liczbę osób z dostępem do logowania, stosując zasadę najmniejszych uprawnień dla 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, więc 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 architektura sprawdza się w sieci piaskownicy (sandbox). Plik compose definiuje drugą sieć oznaczoną internal: true, co w Docker oznacza brak łączności z siecią zewnętrzną. Piaskownice dołączają do niej. Brama (gateway) posiada interfejsy w obu sieciach, więc stanowi jedyną drogę wyjścia. Dokumentacja runnera jasno określa ten punkt: „sieć internal z bramą posiadającą interfejsy w obu sieciach sprawia, że ruch wychodzący ograniczony do bramy jest wymuszony, a nie tylko sugerowany”. Agent nie może ominąć bramy poprzez otwarcie bezpośredniego połączenia z adresem zewnętrznym; polityka bramy nadal decyduje o tym, które żądania są dozwolone.
Zweryfikuj to na własnym serwerze, zamiast polegać wyłącznie na powyższym opisie.
docker network ls
docker network inspect onecli-sandboxes | grep -i internalPowinieneś zobaczyć "Internal": true. Jeśli wynik to false, kontrola ruchu wychodzącego jest wyłączona i brama ponownie pełni jedynie rolę sugestii. Użyj nazwy sieci piaskownicy, którą wyświetla docker network ls, ponieważ onecli-sandboxes to tylko wartość domyślna.
Jak silny jest sandbox OneCLI?
Przeczytaj tę sekcję powoli, ponieważ termin „sandboxed” ma duże znaczenie w opisie projektu, podczas gdy sam mechanizm jest udokumentowany w dokumentacji runnera oraz w kodzie backendu.
README podaje, że każdy agent otrzymuje „własny odizolowany sandbox, z systemem plików i powłoką” oraz wskazuje Sandbox Supervisor jako komponent, który „działa wewnątrz każdego sandboxa, komunikując się za pomocą 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 sandbox to kontener Docker z limitem pamięci, limitem CPU, limitem procesów oraz podłączony do sieci wewnętrznej. Kod zawiera interfejs dla innych backendów. Obecny kod runnera implementuje również backend Kubernetes, z którego wykres Helm korzysta w przypadku zadań (Jobs) sandboxa i trwałych wolumenów. W instalacji Compose opisanej w tym przewodniku sandbox jest kontenerem Docker.
Dokumentacja runnera opisuje teraz granice Dockera: agent działa jako node, z no-new-privileges, wszystkimi uprawnieniami Linux capabilities odrzuconymi oraz domyślnym profilem seccomp Dockera. Backend montuje w sandboxie wyłącznie trwały katalog domowy agenta. Należy zatem przyjąć zawężoną interpretację. Limity dotyczą zasobów. Sieć wewnętrzna stanowi rzeczywistą kontrolę ruchu wychodzącego. Izolacja między agentem a hostem opiera się na tych mechanizmach kontenerowych, a kontener współdzieli jądro systemu hosta.
Należy wziąć pod uwagę drugi fakt. Usługa runnera montuje /var/run/docker.sock, ponieważ w ten sposób tworzy sandboxy. Dostęp do gniazda (socket) demona Docker działającego z uprawnieniami roota jest równoważny z posiadaniem uprawnień roota 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. Dostarczony runner oparty na Dockerze korzysta z tego gniazda. Konsekwencją jest to, że proces runnera jest równie wrażliwy jak gateway. Terminator SSH montuje to samo gniazdo, aby móc wykonywać polecenia wewnątrz kontenerów sandboxa, a komentarze w pliku compose określają to montowanie jako równoważne z dostępem roota na hoście, więc port 10257 powinien pozostać na interfejsie loopback, chyba że istnieje powód, by go otworzyć.
Traktuj granicę współdzielonego jądra konserwatywnie. W praktyce oznacza to trzy nawyki.
- Uruchamiaj OneCLI na maszynie, która nie wykonuje żadnych innych zadań. Żadnych niezwiązanych usług produkcyjnych, żadnych współdzielonych baz danych, żadnych danych innych zespołów.
- Zakładaj, że agent, który uzyska możliwość wykonania dowolnego kodu wewnątrz swojego sandboxa, może uzyskać dostęp do hosta, i spraw, aby taki scenariusz był możliwy do przetrwania dzięki kopiom zapasowym przechowywanym poza maszyną.
- Przeczytaj
apps/runner/srclub zapytaj twórców projektu, zanim poinformujesz współpracownika, że agent jest odizolowany.
Aby uzyskać obraz tego, jak wygląda udokumentowana granica bezpieczeństwa oraz jakie pytania warto zadać twórcom projektu, porównaj to z tym, jak wygląda rzeczywista granica sandboxa agenta. Pytanie brzmi, czy udokumentowany mechanizm obejmuje zagrożenia, przed którymi chcesz się zabezpieczyć.
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 muszą odświeżyć obrazy usługi oraz oddzielny obraz agenta, a następnie zrestartować działające piaskownice (sandboxy). Usługa migracji typu one-shot uruchamia się przed API przy każdej 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.
Jeden krok łatwo pominąć. Dokumentacja self-hosting ostrzega przed aktualizacją za pomocą samego docker compose pull && docker compose up -d, ponieważ obraz piaskownicy agenta nie jest usługą Compose. Jest to wartość RUNNER_AGENT_IMAGE na runnerze, więc docker compose pull nigdy jej nie widzi, a hostowane agenty mogą pozostać na starym obrazie piaskownicy bez żadnego ostrzeżenia. Zaktualizuj checkout, przenieś przypięcie (pin) i uruchom udokumentowane narzędzie aktualizacji, które pobierze obraz piaskownicy i zrestartuje działające piaskownice.
cd onecli
git pull
sed -i 's/^ONECLI_VERSION=.*/ONECLI_VERSION=2.17.0/' docker/.env
pnpm install
pnpm run setup --upgrade
cd docker
docker compose logs migrationsZastąp 2.17.0 wydaniem, na które przechodzisz. Restart piaskownic przerywa trwające zadania; trwały obszar roboczy każdego agenta pozostaje nienaruszony.
Jeśli instalacja została przeprowadzona za pomocą skryptu instalacyjnego, uruchom go ponownie zamiast ręcznego pobierania obrazów. Dzięki temu plik compose pozostanie zgodny z obrazami, do których się odwołuje. Wyeksportuj ONECLI_VERSION przed uruchomieniem, jeśli wymagasz konkretnego wydania, ponieważ skrypt nadpisuje przypięcie przechowywane jedynie w jego pliku .env.
Wykonaj kopię zapasową bazy danych, konfiguracji oraz wolumenów obszarów roboczych agentów. PostgreSQL przechowuje dane agentów, konwersacje, pamięć oraz zaszyfrowane sekrety. Plik docker/.env zawiera SECRET_ENCRYPTION_KEY. Bez tego klucza zaszyfrowane sekrety są niemożliwe do odczytania, nawet jeśli reszta bazy danych zostanie przywrócona. Każdy /workspace agenta znajduje się na oddzielnym trwałym wolumenie i wymaga własnej kopii zapasowej.
cd onecli/docker
docker compose exec -T postgres pg_dump -U onecli onecli | gzip > ~/onecli-db.sql.gz
install -m 600 .env ~/onecli-env.backupPrzechowuj te kopie oraz kopie zapasowe obszarów roboczych poza serwerem. Procedura jest taka sama, jak w przypadku każdego stosu Compose przechowującego stan. Jeśli już wykonujesz kopie zapasowe i aktualizujesz stos Docker Compose zgodnie z harmonogramem, dodaj do niego bazę danych, konfigurację oraz wolumeny obszarów roboczych i nie martw się o to więcej.
Gdy rozwiązanie nie działa
- Stos nie osiąga stanu gotowości, a
docker compose up -d --waitkończy działanie z kodem wyjścia innym niż zero. W pierwszej kolejności należy zapoznać się zdocker compose logs migrations, ponieważ API celowo oczekuje na tę usługę. - Agent pozostaje w stanie bezczynności i nie pojawia się żadne środowisko izolowane (sandbox). Należy sprawdzić, czy
COMPOSE_PROFILES=runnerznajduje się wdocker/.envoraz czydocker compose pswyświetla uruchomiony proces (runner). Następnie należy zweryfikować, czy agent posiada przyznany klucz modelu, ponieważ środowiska izolowane nie uruchamiają się bez niego. - Brak dostępnych slotów. Wartość
RUNNER_MAX_SANDBOXESdomyślnie wynosi 4, a środowisko izolowane z działającym procesem w tle zajmuje slot do momentu jego zwolnienia przez mechanizm limitów. Poleceniedocker pspokazuje rzeczywisty stan aktywnych procesów. - Stos nie uruchamia się, a Docker zgłasza, że port jest już używany. Przy włączonym profilu
runner, brama SSH wymaga portu10257oraz czterech pozostałych portów. - Kontenery znikają lub host działa bardzo wolno. Należy sprawdzić, czy nie doszło do wyczerpania pamięci za pomocą
dmesg -T | grep -i oom; domyślny limit pamięci pozwala pojedynczemu środowisku izolowanemu na wykorzystanie do 2048 MB. - Połączenia HTTPS agenta kończą się błędami weryfikacji certyfikatu, a nie błędami uwierzytelniania. Klient HTTP agenta nie ufa urzędowi certyfikacji bramy.
- Stare kontenery lub wolumeny pozostają po usunięciu agenta. Proces runnera synchronizuje stan co 60 sekund i usuwa osierocone elementy starsze niż
RUNNER_ORPHAN_GRACE_SECONDS, co domyślnie wynosi 3600 sekund, dlatego należy odczekać godzinę przed uznaniem tego za wyciek zasobów.
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.
W przypadku jednej osoby jest to rozbudowana infrastruktura bez rzeczywistej korzyści. Trzeba uruchomić PostgreSQL, control plane, gateway i runner, aby udostępnić sobie jednego agenta, a problem poświadczeń rozwiązywany przez gateway praktycznie nie występuje, gdy jedyną osobą posiadającą klucz jest użytkownik. Zamiast tego należy uruchomić pojedynczy harness na mniejszej maszynie: pojedynczy harness agenta na VPS zapewnia tę funkcję przy wykorzystaniu ułamka pamięci. Jeśli nie wybrano jeszcze żadnego kierunku, przegląd porównanie self-hosted agentów AI będzie tańszym pierwszym krokiem. Jeśli nieznane są przede wszystkim same agenty, a nie serwery, na których działają, należy najpierw przejść przez etapową ścieżkę nauki rzeczywistego działania agentów, ponieważ znajomość rzeczywistego działania wywołania narzędzia i magazynu pamięci wskazuje, jakie uprawnienia powinien otrzymać agent każdej osoby.
FAQ
Jakie są minimalne wymagania serwerowe do samodzielnego hostowania OneCLI?
Docker z wtyczką Compose w wersji 2.24.0 lub nowszej, Node.js oraz pnpm dla użytego tutaj kreatora konfiguracji, a także odpowiednia ilość pamięci RAM. PostgreSQL jest dostarczany wraz z plikiem compose, więc nie ma potrzeby instalowania go osobno. Pamięć RAM decyduje o planie: runner domyślnie ogranicza każdą piaskownicę agenta do 2048 MB, a dokumentacja zaleca około 10 GiB wolnego miejsca poza bazowym stosem, aby obsłużyć domyślny limit czterech piaskownic. Przy założonym budżecie 2 GB na stos bazowy, serwer 4 GB pozwala na uruchomienie jednej piaskownicy z pełnym limitem, a serwer 16 GB pokrywa domyślny limit współbieżności. Są to wartości szacunkowe, a nie zmierzone wymagania minimalne czy sztywne przydziały pamięci.
Czy OneCLI wymaga PostgreSQL, czy może korzystać z SQLite?
Wymaga PostgreSQL. DATABASE_URL jest udokumentowane jako ciąg połączenia PostgreSQL, dostarczony plik compose uruchamia postgres:18-alpine z wolumenem pgdata, a osobna usługa migracji nakłada schemat przed uruchomieniem API. Opcja SQLite nie jest udokumentowana. W przypadku zewnętrznego serwera PostgreSQL należy skonfigurować zarówno API, jak i usługę migracji, aby z niego korzystały; dostarczony plik compose ustawia ich ciągi połączenia na dołączoną usługę PostgreSQL.
Czy piaskownica agenta OneCLI stanowi realną barierę bezpieczeństwa?
Udokumentowany mechanizm Compose to kontener Docker z limitami pamięci, procesora i procesów, podłączony do sieci oznaczonej jako internal: true, dzięki czemu ruch zewnętrzny przechodzi przez bramę. Kontrola ruchu wychodzącego jest rzeczywista i można ją zweryfikować za pomocą docker network inspect. Agent działa jako node, z no-new-privileges, z usuniętymi wszystkimi uprawnieniami Linux capabilities oraz domyślnym profilem seccomp Dockera, współdzieląc jednocześnie jądro systemu hosta. Runner oraz terminator SSH montują /var/run/docker.sock, co jest równoważne z dostępem root na hoście używającym demona Docker z uprawnieniami root. OneCLI należy uruchamiać na dedykowanej maszynie i przechowywać kopie zapasowe poza nią.
Czy muszę otwierać jakiekolwiek porty przychodzące dla OneCLI?
Nie. Runner działa wyłącznie w trybie wychodzącym i nie nasłuchuje na żadnych portach dostępnych z zewnątrz, więc działa za NAT bez konieczności używania tuneli. Plik compose domyślnie wiąże pulpit nawigacyjny, bramę, API, PostgreSQL oraz, w profilu runner, wejście SSH na porcie 10257 z 127.0.0.1. Dostęp do pulpitu nawigacyjnego można uzyskać przez tunel SSH lub używając konfiguracji reverse proxy z TLS i wymaganymi trasami dla pulpitu, API i bramy, jeśli dostęp ma mieć kilka osób, pamiętając, że rejestracja pozostaje otwarta dla każdego, kto ma do niej dostęp. Brama na porcie 10255 służy agentom, a na pojedynczej maszynie agenci łączą się z nią przez 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/ są objęte licencją 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 wykrywalnego przez GitHub pliku licencji Apache-2.0, dlatego przed zbudowaniem workflow na jakiejkolwiek funkcji należy sprawdzić LICENSE oraz katalogi ee/ w konkretnej wersji (tagu), którą wdrażasz.