Szybki start — Dokumentacja BuildOnAI

Wymagania

Docker Engine + Docker Compose v2.
Ollama na hoście (http://127.0.0.1:11434) z pobranym modelemnomic-embed-text. Zarównosemantic-search, jak iconsciousness-server dochodzą do Ollamy poprzez hosta. Jeśli Ollama nie działa,/api/search zwraca precyzyjny503 ollama_unreachable, zamiast udawać, że wszystko gra.

Ubuntu / Debian: curl -fsSL https://ollama.com/install.sh | sh, a potem ollama pull nomic-embed-text. macOS: zainstaluj aplikację Ollama, później pobierz ten sam model.

1. Sklonuj ekosystem

Cały stack mieści się w jednym repozytorium. Plik compose wdeploy/docker-compose.yml spina sześć usług plus Redisa z tego jednego drzewa.

git clone --recurse-submodules https://github.com/build-on-ai/consciousness-server.git
cd consciousness-server

2. Zainstaluj zależność narzędzi CLI

Narzędzia podpisujące, używane w dalszej części przewodnika, czytają sshpk z pakietu key-server. Jedna komenda, raz, przed startem stacka.

(cd key-server && npm install)
# bin/sign-request, bin/cs-curl i bin/test-endpoints podpisują przez sshpk,
# który mieszka w pakiecie key-server. Bez tego kroku zatrzymują się na
# "sshpk not found in .../key-server/node_modules".

3. Uruchom stack

Domyślny stack obejmuje key-server, a każdy blok weryfikuje podpisane żądania. Przed pierwszym startem wygeneruj klucze wdrożenia; inaczej kontenery mogą być zdrowe, lecz chronione wywołania zostaną poprawnie odrzucone.

bin/sync-ports
bin/bootstrap-keys
cd deploy
docker compose up -d --build

Co właśnie uruchomiłeś — porty są od razu dostępne z LAN-u:

Port	Usługa	Rola
`13032`	`consciousness-server`	zadania, notatki, czat, pamięć, agenci, skille, wbudowany WebSocket
`13037`	`semantic-search`	Flask + ChromaDB; embeddingi przez Ollamę
`13038`	`machines-server`	świadomość infrastruktury + telemetria
`13040`	`key-server`	weryfikacja podpisu ed25519
`13041`	`test-runner`	asynchroniczne pytest / jest / npm
`13042`	`git-workflow`	odbiornik post-commit hooków

To domyślne porty hosta. Aktywny podzbiór żyje wports.yaml w katalogu repo — każda warstwa (natywne serwery, compose, narzędzia) czyta ten sam plik.

3.5 Porty zajęte na Twoim hoście?

Wybierz wolne porty hosta w ports.yaml, potem wygeneruj deploy/.env. Nie zmieniajdocker-compose.yml; rejestr portów jest jednym źródłem prawdy.

# Wybierz wolne porty hosta w ports.yaml, potem wygeneruj deploy/.env:
bin/sync-ports
bin/sync-ports --check          # zgłasza rozjazd w którymkolwiek artefakcie
cd deploy && docker compose up -d --build

Po edycji bin/sync-ports wygenerował na nowodeploy/.env; compose podstawił nowe wartości;bin/sync-ports --check potwierdza, że oba artefakty się zgadzają.

Porty wewnętrzne kontenerów (zmienne PORTwewnątrz serwisów, REDIS_PORT do kontenera redis, URL'e między serwisami przez DNS dockera) zostają zahardkodowane — żyją w sieci dockera i nigdy nie zderzą się z hostem. Tylko porty po stronie hosta się zmieniają.

Można też nadpisać jeden port bez edycjiports.yaml:PORT_KEY_SERVER=13040 docker compose up -d. Przydatne do jednorazowych testów.

4. Sprawdź, że wszystko żyje

Każda usługa wystawia /health. Jedna pętla potwierdza, że stack wstał czysto:

for p in 13032 13037 13038 13040 13041 13042; do
  curl -sf "http://127.0.0.1:$p/health" >/dev/null && echo "port $p OK"
done

# Oczekiwany wynik:
# port 13032 OK
# port 13037 OK
# port 13038 OK
# port 13040 OK
# port 13041 OK
# port 13042 OK

Jeśli któregoś portu brak,docker compose logs <usługa> z katalogudeploy/ pokazuje, co padło. Najczęstszy przypadek to nieuruchomiona Ollama — popraw to, zrestartuj przez docker compose restart semantic-search i sprawdź ponownie.

5. Zapisz pierwszą pamięć

Warstwa pamięci jest gotowa od razu po bootcie. Bez dodatkowej konfiguracji. Dwa wywołania — zapisz notatkę, potem ją znajdź:

# bin/cs-curl odczytuje ports.yaml i podpisuje żądanie.
bin/cs-curl POST /api/notes \
  '{"agent":"first-agent","type":"observation","title":"Pierwsza notatka",
    "content":"Stos wstał z samego README."}'

# Indeksowanie idzie tuż za zapisem, więc daj mu sekundę.
bin/cs-curl -b semantic-search POST /api/search \
  '{"query":"czy stos wstal"}'

Do indeksu semantycznego trafiają notatki i podsumowania sesji. Rozmowy i rekordy treningowe, zapisywane przez/api/memory/conversations i/api/memory/training, lądują w Redisie i są dostępne przez API, ale nie mają embeddingu, więc/api/search ich nie zwróci.

bin/cs-curl podpisuje każde chronione żądanie i odczytuje port docelowy z ports.yaml. Embeddingi pochodzą z Ollamy, a indeks żyje w ChromaDB.

Dalsze kroki

Cortex → — lokalny agent AI napędzany Ollamą. Spina się z tą samą warstwą pamięci.
Document Processor → — aplikacja desktop do lokalnego przetwarzania PDF / DOCX / TXT.
Key Server → — weryfikacja podpisanych żądań ed25519 i opcjonalny vault na dysku.
Maszyny → — zarejestruj kolejne maszyny, żeby agenci mogli routować po GPU, VRAM, dostępnych modelach.

Sprzątanie

Drzewo deploy/volumes/* (store ChromaDB, dump Redisa, logi per usługa) jest zapisywane przez kontenery działające jako root, więc usunięcie z hosta wymaga sudo. Trzy poziomy:

cd deploy
docker compose down              # zatrzymuje kontenery, wolumeny zostają
docker compose down -v           # zatrzymuje + usuwa nazwane wolumeny
sudo rm -rf volumes              # pełny reset do stanu wyjściowego

Od klonu repo do pierwszej pamięci w pięć minut.