cortex v1.0.8 AGPL-3.0-only + Komercyjna

Cortex

Lokalny agent AI z wywoływaniem narzędzi, napędzany Ollama. Każdy fork zostaje otwarty.

Zobacz na GitHub → Szybki start Architektura Changelog

Przegląd

Cortex to lokalny agent AI z prawdziwym wywoływaniem narzędzi. Czyta pliki, wykonuje komendy shell, edytuje kod, odpytuje sieć — na Twoim sprzęcie, z modelami z Twojej Ollamy, bez rachunków za API.

W przeciwieństwie do alternatyw z permisywnymi licencjami, Cortex jest na AGPL-3.0-only. Każdy fork zostaje otwarty; każde wdrożenie SaaS musi udostępnić kod; żadna korporacja nie wchłonie Cortexa do zamkniętego produktu. Twoja inwestycja w projekt — i społeczności — jest chroniona prawnie.

Zobacz w działaniu

Prawdziwa sesja Cortex CLI, od góry do dołu: banner pokazuje załadowany model i potwierdza, że Policy Engine (12 narzędzi), Recovery Engine i Context Compactor są aktywne. Następnie /model gemma4:26b zmienia model w trakcie sesji na większy. /model (bez argumentu) listuje wszystkie dostępne modele na hoście. /think włącza tryb rozumowania. Użytkownik pyta "wyjaśnij SSH" po polsku — a model odpowiada po polsku, z nagłówkami markdown i pogrubieniem zachowanym w terminalu.

Sesja Cortex CLI: banner, /model gemma4:26b switch, /think mode ON, prompt 'wyjaśnij SSH', odpowiedź modelu po polsku wyjaśniająca bezpieczeństwo SSH
Cortex działający lokalnie na stacji z GPU, odpowiadający przez gemma4:26b. Pokazana lokalizacja polska — prompt, odpowiedź i komunikaty UI są po polsku; angielska to ustawienie domyślne.

Możliwości

  • 10 wbudowanych narzędzi — bash, read / write / edit plików, grep, glob, list_dir, plus opcjonalna integracja z Consciousness Server dla wspólnych notatek, zadań i semantic search.
  • Policy Engine — reguły deny / ask / allow oparte o regex, stosowane do każdego wywołania narzędzia. Odmawia niebezpiecznych komend niezależnie od tego, kto je zlecił: człowiek, halucynacja modelu czy prompt injection.
  • Recovery Engine — automatyczne ponowienia po tymczasowych błędach, opcjonalny fallback do hostowanego API LLM, gdy lokalny model nie radzi sobie z konkretnym zadaniem.
  • Kompresja kontekstu — automatyczne sumaryzowanie starszych wiadomości, gdy kontekst się zapełnia. Długie sesje zachowują spójność bez eksplozji kosztu tokenów.
  • Trzy tryby działania — interaktywny CLI, UI w przeglądarce ze streamingiem WebSocket, oraz autonomiczny worker pobierający zadania z task servera w tle.
  • Zmiana modelu w trakcie sesji — wpisz /model gemma4:26b i kontynuuj tę samą rozmowę z innym modelem. Pełna historia w sekcji niżej.
  • System pluginów — wrzuć plik Python do katalogu plugins/ z PLUGIN_TOOLS i execute_tool(); aktywuj przez --mode NAME. Bez rejestru, bez kroku instalacji.
  • Niezmienniki bezpieczeństwa wymuszane na CI — walker AST plus runtime sentinel check. Wyłączenie testów niezmienników unieważnia gwarancje bezpieczeństwa licencji komercyjnej.

Wiele modeli — trzy warstwy

Cortex jest jednym z niewielu samodzielnie hostowanych agentów zaprojektowanych z założenia, że pojedynczy LLM rzadko wystarczy. Różne zadania pasują do różnych modeli; różne maszyny mają różną pojemność; czasem lokalny model potrzebuje pomocy. Wsparcie dla wielu modeli rozciąga się na trzy warstwy, każdą używalną niezależnie.

1. Zmiana modelu w trakcie sesji

W ramach jednej rozmowy wpisz /model aby zobaczyć co jest dostępne, potem /model NAZWA aby przełączyć. Konwersacja kontynuuje z nowym modelem od następnej tury. Krótki, szybki model do eksploracji; duży model do trudnej części — ten sam kontekst, bez restartu.

cortex CLI 
> /model
Aktualny: gemma4:e4b
Dostępne: gemma4:e4b, gemma4:26b, qwen3:14b, mistral-small:24b

> /model gemma4:26b
Przełączono na gemma4:26b. Konwersacja kontynuuje.

> A teraz refaktoryzuj moduł auth tym większym modelem.

2. Recovery fallback do hostowanego LLM

Ustaw ANTHROPIC_API_KEY w .env i Recovery Engine staje się siatką bezpieczeństwa. Gdy lokalny model zawodzi (zniekształcone wywołanie narzędzia, ucięta odpowiedź, zatrzymana generacja), Cortex próbuje ponownie lokalnie; jeśli ponowienia się wyczerpią, może opcjonalnie skierować ten sam prompt do hostowanego API jako fallback. Dwie warstwy w jednym agencie: najpierw lokalnie, w chmurę tylko gdy lokalnie nie wyszło.

Fallback jest opt-in. Bez ustawionego klucza API Cortex pozostaje w pełni lokalny i raportuje błąd — żadnego cichego przecieku Twoich promptów do chmury.

3. Orkiestracja floty przez Consciousness Server

Najmocniejszy wzorzec: uruchom kilka instancji Cortex na różnych maszynach, każda z modelem dopasowanym do swojego sprzętu, wszystkie dzielące stan przez Consciousness Server. Tryb workera (./run.sh worker) odpytuje CS o zadania; ten Cortex, który podejmie zadanie, używa swojego lokalnego modelu. Efektywnie dostajesz heterogeniczną flotę agentów:

  • Stacja robocza z GPU obsługująca Cortex z gemma4:26b bierze ciężkie wnioskowanie, code review, analizę dokumentów.
  • Host CPU-only obsługujący Cortex z gemma4:e4b robi szybką klasyfikację, sumaryzowanie, drobne narzędzia.
  • Raspberry Pi albo niski węzeł z gemma4:e4b bierze zadania o najniższym priorytecie w tle.
  • Laptop z Claude Code lub Cortex CLI orkiestruje, przydzielając zadania węzłowi z wolną mocą.

Każdy węzeł używa innego modelu; wszystkie widzą tę samą wspólną pamięć w CS; kanał czatu pozwala agentom się koordynować (@gpu-worker przeanalizuj to ponownie większym modelem). To jest produkcyjny setup, który autor uruchamia od połowy 2025 — weryfikowalny przez rejestr machines-server.

Roadmap — automatyczna orkiestracja modeli

Dziś routing jest jawny (model wybierasz przez /model albo przez to, który worker podejmie zadanie). Planowane na v1.2: automatyczna orkiestracja w jednym procesie, gdzie Cortex sam decyduje, który model wywołać per krok — mały szybki do parsowania, większy do wnioskowania, specjalistyczny do generacji kodu. Nie dostarczane dziś; flagowane uczciwie.

Instalacja

terminal 
# 1. Zainstaluj Ollamę
curl -fsSL https://ollama.com/install.sh | sh

# 2. Pobierz model wspierający tool-calling
ollama pull gemma4:e4b      # 3 GB, szybki na CPU
# albo
ollama pull gemma4:26b      # 17 GB, wymaga GPU

# 3. Uruchom Cortex
git clone https://github.com/build-on-ai/cortex.git
cd cortex
./run.sh agent              # interaktywny CLI
./run.sh web                # browser UI pod http://localhost:8080
./run.sh worker             # autonomiczny worker zadań

run.sh przy pierwszym uruchomieniu tworzy automatycznie Python venv i instaluje zależności. Zero zanieczyszczania globalnego Pythona. Działa na Linuksie i macOS; Windows przez WSL.

Tryby

Tryb Komenda Opis
CLI ./run.sh agent Interaktywny czat w terminalu z wywoływaniem narzędzi
Web ./run.sh web Interfejs przeglądarkowy ze streamingiem WebSocket pod http://localhost:8080
Worker ./run.sh worker Pollu Consciousness Server, wykonuje zadania, raportuje wyniki
One-shot ./run.sh worker --once Wykonuje jedno oczekujące zadanie i kończy
Plugin ./run.sh agent --mode NAME Aktywuje wybrany plugin po nazwie
Web UI Cortex: interfejs czatu, prompt 'ollama list', widoczny chain-of-thought, odpowiedź agenta z listą lokalnie zainstalowanych modeli Ollama, blok wykonania bash ollama list pod odpowiedzią
Tryb Web UI (./run.sh web) — ten sam agent, to samo wywoływanie narzędzi, ten sam Policy Engine, renderowane w przeglądarce. Chain-of-thought widoczny, gdy think jest włączony; wywołania narzędzi pokazują się jako rozwijalne bloki pod odpowiedzią.

Przetestowane modele

Każdy model Ollamy z obsługą tool-calling działa. Lista poniżej to to, co zweryfikowaliśmy w sensie "działa rozsądnie z infrastrukturą tool-calling Cortex" — nie wielomiesięczny benchmark. Czasy CPU/GPU to przybliżona orientacja, nie obietnica.

Model Rozmiar CPU GPU Uwagi
gemma4:e4b 3 GB ~16s/turę ~3s/turę Szybki na CPU, dobra baza
gemma4:26b 17 GB wolno ~20s/turę Wnioskowanie produkcyjnej jakości, wymaga GPU
gemma4:31b 20 GB bardzo wolno ~25s/turę Maksymalna głębokość wnioskowania na pojedynczym GPU
qwen3:8b / 14b / 30b 4–17 GB różnie szybko Mocne tool-calling, wielojęzyczne
mistral-nemo:12b / mistral-small:24b 6–13 GB — szybko Solidny generalista, dobra obsługa kontekstu
Bielik / PLLuM różnie różnie różnie Polskie modele językowe, przetestowane integracje
WhiteRabbitNeo v1.5a 3 GB — szybko Uncensored model — sprawdza się z tool callingiem do badań security

Policy Engine

Output komendy /policy w Cortex: liczba reguł deny/ask/allow per narzędzie. bash ma 31 reguł deny, write_file 6, edit_file 5 deny + 2 allow
Output /policy z prawdziwej sesji Cortex — 12 zarejestrowanych narzędzi z licznikami deny / ask / allow per narzędzie. Dwa ostatnie wpisy (kali, ask_cyberpedia) pochodzą z customowego pluginu security załadowanego przy starcie; reszta to standardowe narzędzia.

Każde wywołanie narzędzia przechodzi przez Policy Engine przed wykonaniem. Trzy klasy reguł:

  • DENY (cicho odrzucone) — destrukcyjne komendy jak rm -rf /, mkfs, dd, fork bombs, curl | bash, shutdown.
  • ASK (wymaga potwierdzenia) — uprzywilejowane komendy jak sudo, instalacje pakietów (apt, pip, npm), force-pushe, kill procesów.
  • ALLOW (działa natychmiast) — komendy tylko-do-odczytu i inspekcyjne jak ls, cat, grep, git status, ps.

Reguły customowe trafiają do policy.json w roocie projektu:

policy.json 
# policy.json — przykład custom rule
{
  "deny": ["rm -rf /", "mkfs", "dd if=", "shutdown"],
  "ask":  ["sudo", "apt install", "pip install", "git push --force"],
  "allow": ["ls", "cat", "grep", "git status"]
}

Dlaczego to ważne: Policy Engine to także nasza strukturalna obrona przeciwko prompt injection. Skompromitowany prompt może poprosić model o usunięcie plików, ale policy odmawia niezależnie od tego, kto lub co o to poprosił. Pełen model zagrożeń na stronie profil bezpieczeństwa.

Pluginy

Wrzuć plik Python do katalogu plugins/ z trzema wpisami — PLUGIN_NAME, PLUGIN_TOOLS (definicje narzędzi w formacie Ollamy) i execute_tool(name, args). Aktywuj przez ./run.sh agent --mode NAZWA.

Bez rejestru paczek, bez komendy install, bez semantycznego wersjonowania API pluginów. Pliki w katalogu; Cortex znajduje je przy starcie. Dziś pluginy są trusted-by-design (Cortex dokumentuje to uczciwie w SECURITY.md); v1.2 przynosi prawdziwą izolację przez PEP 684 subinterpreters i otwiera drogę do publicznego marketplace pluginów społeczności.

Profil bezpieczeństwa

Cortex to lokalny, jednoużytkownikowy agent AI. Ufa operatorowi maszyny, lokalnej instancji Ollamy i każdemu pluginowi, który ładujesz. Dostęp do filesystemu i shella jest celowo bez sandboxa — myśl bash, nie przeglądarka.

Przed wdrożeniem poza pojedynczą stacją roboczą (host współdzielony, sieć narażona, niesprawdzone pluginy) przeczytaj SECURITY.md w repo. Dokumentuje model zagrożeń, decyzje projektowe wyglądające na luki, ale nimi niebędące, i jak zgłosić realne problemy.

  • 18 rund audytu bezpieczeństwa w developmencie.
  • 57 zielonych testów integracyjnych, w tym testy niezmienników security.
  • Strukturalne niezmienniki wymuszane na CI — walker AST waliduje gwarancje bezpieczeństwa przy każdym commicie; nieprzechodzący run blokuje release.
  • Auto-zbierana powierzchnia wyjątków — każdy escape hatch invariant: allow-... trafia do UNSAFE.md do review.

Dalsze kroki