Backend

Pipe v0.50.5

Backend agenta. Działa na serwerze (Docker, natywnie z systemd albo w Kubernetesie – deploy.md) i wystawia lokalny Unix socket i port TCP 127.0.0.1:7379 dla klientów.

Wymagania#

• Linux, Python 3.11+
• tryb docker: Docker 24+ z Compose v2 (instalator doinstaluje je z repozytorium dystrybucji)
• tryb native: systemd; tryb kubernetes: klaster z PVC

Moduly#

Konfiguracja#

Skonfiguruj providera LLM#

Z katalogu głównego repozytorium uruchom kreator (sam utworzy backend/.env z .env.example):

python3 -m backend.configure

Kreator:

1. pokaże listę providerów i zapyta o klucz API (z linkiem, gdzie go zdobyć),
2. pobierze aktualna listę modeli prosto z API providera – nowe modele są widoczne od razu, bez aktualizacji Pipe,
3. sprawdzi na żywo, czy wybrany model obsługuje tool calling (bez tego agent nie wykona żadnej komendy),
4. zapisze backend/.env (utworzy go z .env.example, jeśli nie istnieje; uprawnienia 600).

Kreator używa wyłącznie biblioteki standardowej Pythona – nie trzeba niczego instalować.

Przydatne tryby:

python3 -m backend.configure --check      # test obecnej konfiguracji (lista modeli + tool calling)
python3 -m backend.configure --models     # aktualne modele obecnego providera
python3 -m backend.configure --providers  # wszyscy dostepni providerzy

Wbudowani providerzy#

Wszyscy przez API zgodne z OpenAI Chat Completions. Adresy zweryfikowane we wrześniu 2026.

Domyślny model to tylko punkt startowy. Przy starcie backend sprawdza, czy skonfigurowany model nadal jest na liście providera, i wypisuje ostrzeżenie z propozycjami, jeśli został wycofany.

Prywatność: Pipe wysyła providerowi logi, konfiguracje i wyniki komend z serwera (sekrety redaguje). W darmowym tierze Gemini API Google może używać treści zapytań do ulepszania swoich usług i mogą je czytać ludzie. Kreator, pipe web i CLI ostrzegają o tym przy wyborze Gemini. Na serwerze produkcyjnym włącz płatności w Google AI Studio albo wybierz innego providera, np. lokalna Ollame.

Bez modelu (LLM_PROVIDER=none)#

Pipe może działać bez żadnego modelu. Wtedy nic nie wychodzi z serwera i nic nie kosztuje, a dalej działają: czuwanie i alerty, migawki i „co się zmieniło”, poranny raport, monitoring certyfikatów i stron, audyt bezpieczeństwa, dziennik i /cofnij, diagramy, webhooki (alert dociera, ale nikt go nie bada) oraz bramka MCP dla innych agentów (bez ask_pipe). Rozmowa, rutyny i badanie alertów odpowiadają komunikatem, że modelu nie ma. Gdy później dodasz providera w pipe web albo /providerzy, rozmowa włącza się bez restartu.

W kreatorze to ostatnia pozycja listy, a bez pytań: LLM_PROVIDER=none bash scripts/install-server.sh -y.

Ręczna konfiguracja .env#

Zamiast kreatora możesz edytować backend/.env ręcznie:

LLM_PROVIDER=openai
LLM_API_KEY=sk-...
LLM_MODEL=            # pusty = domyslny model providera

Zamiast LLM_API_KEY możesz ustawić zmienna specyficzna dla providera, np. OPENAI_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY – LLM_API_KEY ma pierwszeństwo.

Provider z .env jest bazowy – z nim backend startuje. Kolejnych można dodać bez restartu w pipe web (ekran wyboru providera, /provider): klucz trafia do DATA_DIR/llm_keys.json (0600), a przełącznik w rozmowie zmienia providera całego agenta. Zmienne presetów ustawione obok LLM_API_KEY (np. OPENAI_API_KEY, GROQ_API_KEY) też liczą się jako gotowi providerzy w przełączniku. WORKER_MODEL, LLM_REASONING_EFFORT i ceny LLM_PRICE_* dotyczą tylko providera bazowego.

Opcjonalnie:

LLM_BASE_URL=https://proxy.example.com/v1   # nadpisuje adres z presetu (np. proxy firmowe)
LLM_REASONING_EFFORT=low                     # dla modeli, ktore obsluguja ten parametr
LLM_TIMEOUT=120                              # limit czasu odpowiedzi LLM w sekundach

Stare pliki .env (tylko LLM_BASE_URL + LLM_API_KEY + LLM_MODEL, bez LLM_PROVIDER) działają dalej – provider jest rozpoznawany po adresie.

Własny provider#

Dowolny endpoint zgodny z OpenAI (vLLM, LM Studio, LiteLLM, firmowe proxy...) dodasz kreatorem – wybierz opcje Inny i podaj adres. Provider zostanie zapisany w backend/data/providers.json i od tej pory jest dostępny jak wbudowany (LLM_PROVIDER=<id>).

Możesz też edytować ten plik ręcznie:

{
  "providers": [
    {
      "id": "moj-vllm",
      "name": "Moj vLLM",
      "base_url": "http://192.168.1.10:8000/v1",
      "default_model": "qwen3",
      "requires_key": false
    }
  ]
}

Wpis o id wbudowanego providera nadpisuje go – tak poprawisz nieaktualny adres bez czekania na nową wersję Pipe. Katalog backend/data/ jest zamontowany w kontenerze, więc zmiany nie wymagają przebudowy obrazu – wystarczy docker-compose restart vps-agent.

Ollama (modele lokalne)#

Kontener widzi hosta pod adresem host.docker.internal (ustawione w docker-compose.yml). Ollama domyślnie nasłuchuje tylko na 127.0.0.1, więc musisz ją uruchomić z OLLAMA_HOST=0.0.0.0, żeby kontener ją widział. Model musi obsługiwać tool calling – kreator to sprawdzi.

Zabezpieczenie tokenem#

# Zabezpieczenie (Opcjonalne, ale bardzo zalecane)
# Jesli jest ustawione, kazde zadanie -- takze potwierdzenie operacji -- musi zawierac
# ten token. Chroni socket i interfejs TCP przed innymi procesami na serwerze.
# Ten sam token podaj klientom: CLI przez --token (lub zmienna AGENT_TOKEN),
# botowi Telegrama przez AGENT_TOKEN w clients/telegram/.env.
# Puste = brak wymogu tokenu.
AGENT_TOKEN=twoj-tajny-token

Pamięć agenta: SERVER.md i skille#

Agent ma kilka rodzajów trwałej pamięci: SERVER.md, skille (poniżej), a także DIRECTORY (mapa repozytoriów i katalogów) i VIBE (styl rozmowy) – te dwie opisuje features.md. Wszystko leży na hoście w backend/data/ (w kontenerze /app/data, zmienna DATA_DIR), przetrwa restart i przebudowe obrazu i nie trafia do gita. Tam są też targets.json, routines.json, reminders.json, watch_state.json i audit log.

SERVER.md#

Notatki agenta o serwerze – jak AGENTS.md, ale dla serwera. Agent aktualizuje je sam (narzędzie server_md), gdy pozna trwały fakt: usługi, kontenery, domeny, porty, ważne ścieżki, Twoje decyzje. Cały plik jest dołączany do system promptu każdej rozmowy (do 12 000 znaków; sam plik może mieć do 20 000).

Na start możesz poprosić: "zbadaj serwer i utwórz SERVER.md". Plik możesz też edytować ręcznie: backend/data/SERVER.md.

Skille#

Zapisane procedury wielokrotnego użytku, w formacie Agent Skills:

backend/data/skills/<nazwa>/SKILL.md

---
name: odnow-certyfikat
description: Odnowienie certyfikatu TLS dla nginx
---

1. `certbot renew`
2. `nginx -t && systemctl reload nginx`
3. Sprawdz date waznosci certyfikatu.

W system prompcie jest tylko lista skilli (nazwa i opis). Pełna treść agent wczytuje narzędziem skill_manage, gdy zadanie pasuje do opisu – dzięki temu wiele skilli nie zapycha kontekstu. Agent tworzy skill po wykonaniu wieloetapowej procedury, która się powtórzy, albo na Twoją prośbę.

Każdy skill ma też własną komendę w Telegramie i CLI: myślniki zamieniają się na _, a nazwa jest skracana do 32 znaków (limit Telegrama), np. odnow-certyfikat → /odnow_certyfikat. Skill o nazwie zajętej przez komendę wbudowana (status, server, skille, ...) nie dostaje komendy – uruchomisz go przez /skille albo zwykłym tekstem.

Bezpieczeństwo pamięci#

• Zapis do pamięci nie wymaga potwierdzenia – nie zmienia serwera, tylko notatki agenta. Każdy zapis trafia do audit logu (sama ścieżka, bez treści).
• Skille i SERVER.md nie omijają zasad bezpieczeństwa: każda komenda z nich nadal przechodzi klasyfikację i wymóg potwierdzenia.
• SERVER.md jest wysyłany do providera LLM z każdym zapytaniem, dlatego zapis oczywistych sekretów (klucze prywatne, klucze API, tokeny, haslo=...) jest odrzucany. Agent zapisuje, gdzie sekret jest przechowywany, a nie sam sekret.

Uruchomienie#

docker-compose up -d

Weryfikacja#

docker logs vps-agent --tail 20

Powinieneś zobaczyć:

[VPS Agent] Unix socket : /tmp/vps-agent.sock
[VPS Agent] TCP         : 0.0.0.0:7379 (tylko localhost)
[VPS Agent] Provider    : Google Gemini (https://generativelanguage.googleapis.com/v1beta/openai/)
[VPS Agent] Model       : gemini-3.8-flash
[VPS Agent] Runtime     : docker (host: /hostfs, proc: /hostproc)
[VPS Agent] Diagramy    : mermaidx
[VPS Agent] Czuwanie    : co 120 s
[VPS Agent] Serwer gotowy. Ctrl+C aby zatrzymac.

Narzędzia agenta#

Przy TOOLS_MODE=lazy (domyślnie) model dostaje na start tylko podstawowe narzędzia (komendy, pliki, git, stan systemu, Docker, sieć, historia serwera, project, load_tools). Grupy memory, security, schedule, fleet, web, diagram i update włączają się same, gdy wiadomość ich potrzebuje, albo przez load_tools.

Dodatkowe ustawienia .env#

Zatrzymanie#

docker-compose down          # tryb docker
systemctl stop pipe          # tryb native

Popraw tę stronę na GitHubie