OctopOS Handbuch

1. Installation

Voraussetzungen

• Ubuntu 22.04 oder 24.04 LTS (amd64)
• Mindestens 4 GB RAM, 20 GB Disk
• Root-Zugriff
• Internetzugang für Download

Installer ausführen

git clone https://github.com/tilleulenspiegel/octopos.git
cd octopos
sudo bash installer/install.sh

Der Installer läuft vollautomatisch und richtet ein:

• conduwuit (Matrix-Homeserver)
• OctopOS Core (Python-Backend)
• OctopOS Console (React-Frontend via nginx)
• HTTPS mit self-signed Zertifikat
• Optional: Ollama (bei PROFILE=full)

HTTPS und Zertifikat

Nach der Installation ist die Konsole unter https://<IP> erreichbar. Browser zeigen eine Warnung wegen des self-signed Zertifikats — einmalig bestätigen.

Für ein echtes Zertifikat mit Let's Encrypt:

apt-get install -y certbot python3-certbot-nginx
certbot --nginx -d mein.domain.de

2. Erster Start — Setup-Wizard

Beim ersten Aufruf der Konsole erscheint der Setup-Wizard. Hier wird der Admin-Account angelegt.

• Benutzername: Nur a-z, 0-9, _, ., - erlaubt
• Passwort: Mindestens 8 Zeichen

Nach dem Anlegen erscheint die Login-Seite. Der Account funktioniert direkt.

3. Die Webkonsole

Die Konsole ist unter https://<IP> erreichbar. Alle Bereiche sind über die linke Sidebar zugänglich:

4. Agenten anlegen

Agenten sind KI-Persönlichkeiten die Aufgaben ausführen. Jeder Agent hat einen Typ, ein Sprachmodell und optional eine "Soul" (Persönlichkeitsbeschreibung).

Agent-Typen

Agent anlegen (Konsole)

1. 1Agenten → Neuer Agent
2. 2Felder ausfüllen: Agent-ID, Anzeigename, Typ, LLM-Modell, Tools, Soul
3. 3Agent anlegen klicken

Agent-Konfiguration (Datei)

Agenten liegen als Verzeichnisse unter /agents/<id>/:

/agents/steuer-agent/
├── agent.yaml       # Konfiguration
├── soul.md          # Persönlichkeit (optional)
└── skills/          # Skill-Dateien (optional)
    ├── steuerrecht.md
    └── buchhaltung.md

agent.yaml:

id: steuer-agent
type: specialist
identity: Steuerbert

llm:
  model: llama3.1:8b
  temperature: 0.7
  max_tokens: 4096

tools:
  - file_read
  - file_write

heartbeat:
  interval: 30s
  timeout: 90s
  on_failure: restart

Verfügbare Tools

5. Projekte anlegen

Ein Projekt ist ein isolierter Arbeitsbereich: eigener Linux-User, eigenes Verzeichnis, optionale Samba-Freigabe, optionaler Matrix-Room.

Projekt anlegen (Konsole)

1. 1Projekte → Neues Projekt
2. 2Projekt-ID, Name, Boss-Agent, Worker-Agenten und Samba-Option eintragen
3. 3Projekt anlegen klicken

OctopOS richtet automatisch ein:

• Linux-User proj_<id> mit eigenem Home-Verzeichnis
• Verzeichnis /projects/<id>/ für Agenten-Dateien
• Matrix-Room (wenn Matrix konfiguriert)
• Samba-Freigabe (wenn aktiviert)

Projekt-Konfiguration (Datei)

# /projects/buchhaltung/project.yaml
id: buchhaltung
version: "1.0.0"

identity:
  name: Buchhaltung GmbH
  description: Finanzagenten für die GmbH

agents:
  boss: finanz-boss
  workers:
    - steuer-agent
    - buchhalter

matrix:
  room: "!abc123:mein-server.de"    # leer → wird automatisch angelegt

filesystem:
  samba: true

chat:
  show_swarm: false    # true = Worker im Chat anzeigen

6. Chat verwenden

1. 1Projekte → Chat öffnen beim gewünschten Projekt
2. 2Nachricht eingeben und Enter drücken (oder Shift+Enter für Zeilenumbruch)
3. 3Die Antwort erscheint Token-für-Token (Streaming)

Swarm-Ansicht

Das Netzwerk-Symbol oben rechts im Chat schaltet die Swarm-Ansicht um. Bei aktivierter Ansicht wird unter jeder Antwort angezeigt welche Worker-Agenten beteiligt waren.

Chat-History

Die Nachrichten einer Session bleiben erhalten und werden beim nächsten Öffnen automatisch geladen.

7. LLM-Konfiguration

Ollama (lokal, kostenfrei)

Standardmäßig läuft Ollama lokal auf Port 11434. Modelle werden über LLM-Config → Ollama verwaltet.

Empfohlene Modelle:

• llama3.2:3b — schnell, wenig RAM (4 GB)
• llama3.1:8b — ausgewogen (8 GB RAM)
• mistral-nemo:12b — beste Qualität lokal (12 GB RAM)

Claude Max (OAuth)

Für Claude-Modelle via Claude Max Abonnement:

1. 1LLM-Config → Claude Max
2. 2OAuth-Token einfügen (sk-ant-oat01-...)
3. 3Speichern

Der Token-Status wird mit Ablauf-Datum angezeigt. oat01-Tokens gelten ~30 Tage.

OpenAI / andere Anbieter

1. 1LLM-Config → Anbieter konfigurieren
2. 2API-Key und Modell eintragen

8. Skills — Agenten-Wissen erweitern

Skills sind Markdown-Dateien die dem Agenten zusätzliches Wissen geben. Sie werden automatisch in den System-Prompt geladen.

Skill anlegen (Konsole)

1. 1Agenten → Agent auswählen → Skills (Buch-Icon)
2. 2Neuer Skill
3. 3Dateiname, Skill-Name, Scope, Trigger-Keywords, Priority und Inhalt ausfüllen

Skill-Datei (direkt)

---
skill: Steuerrecht Grundlagen
version: "1.0"
scope: on-demand
triggers:
  - steuer
  - finanzamt
  - umsatzsteuer
priority: 10
---

## Steuerrecht Grundlagen

Umsatzsteuer (USt) beträgt in Deutschland standardmäßig 19%.
Ermäßigter Satz: 7% für Lebensmittel, Bücher, ÖPNV.

9. Webhooks

Webhooks ermöglichen externen Systemen OctopOS zu triggern — z.B. bei einem Git-Push automatisch einen Agenten starten.

Webhook anlegen (Konsole)

1. 1Projekte → Webhook-Icon beim Projekt
2. 2Neuer Webhook
3. 3URL, Name, Events und optional Secret eintragen

Verfügbare Events: message, agent_error, provision, agent_start, agent_stop

Externer Trigger (Wake-Endpoint)

curl -X POST https://<ip>/api/hooks/<projekt-id>/wake \
  -H "Content-Type: application/json" \
  -d '{"message": "Neuer Git-Push auf main — bitte Code-Review starten"}'

HMAC-Signierung

Wenn ein Secret gesetzt ist, wird jeder ausgehende Webhook-Request mit X-OctopOS-Signature: sha256=<hmac> signiert.

import hmac, hashlib
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
assert f"sha256={expected}" == request.headers["X-OctopOS-Signature"]

10. Benutzer verwalten

Unter Benutzer können weitere Admin-Accounts angelegt werden. Alle Benutzer haben aktuell Admin-Rechte.

• Neuer Benutzer: Benutzername + Passwort
• Passwort ändern: Stift-Symbol
• Löschen: Papierkorb-Symbol (eigener Account kann nicht gelöscht werden)

11. Audit-Log

Das Audit-Log protokolliert alle sicherheitsrelevanten Aktionen:

• Logins (erfolgreich und fehlgeschlagen)
• Benutzer anlegen/löschen
• Agenten anlegen/löschen
• Projekte anlegen/provisionieren
• Skills anlegen/ändern/löschen
• Webhooks anlegen/löschen/auslösen
• LLM-Token setzen

Gespeichert in /var/log/octopos/audit.jsonl — append-only, ein JSON-Objekt pro Zeile.

Filter: Nach Benutzer, Aktion, Projekt und Anzahl Einträge filterbar.

12. Matrix-Integration

OctopOS kann Nachrichten über Matrix (Element) empfangen und beantworten.

Element-Client verbinden

Matrix-Server läuft auf Port 8008 (nginx-Proxy → conduwuit auf 6167):

• Homeserver: https://<ip>:8008 oder http://<ip>:8008
• Benutzer: @admin:<hostname>
• Passwort: aus /etc/octopos/admin_credentials

Agenten-Bot im Room

Wenn ein Projekt einen Matrix-Room hat, lauscht der Boss-Agent dort automatisch. Nachrichten im Room werden wie Chat-Nachrichten behandelt.

13. Troubleshooting

Konsole nicht erreichbar

sudo systemctl status nginx
sudo nginx -t
sudo journalctl -u nginx -n 50

Core reagiert nicht

sudo systemctl status octopos-core
sudo journalctl -u octopos-core -n 100 --no-pager

Agent antwortet nicht

1. 1Agenten → Agent auswählen → Logs-Icon prüfen
2. 2Heartbeat-Status in der Agent-Liste prüfen (orange = Warnung)
3. 3LLM-Verbindung prüfen: LLM-Config → Status

Matrix-Bot antwortet nicht

sudo journalctl -u octopos-core -n 50 | grep -i matrix

Der Matrix-Watchdog startet den Bot automatisch neu. Bei dauerhaftem Fehler:

sudo systemctl restart octopos-core

OAuth-Token abgelaufen

LLM-Config → Claude Max → Token-Status prüfen. Neuen Token über claude setup holen und eintragen.

Login funktioniert nicht (429 Too Many Requests)

Rate-Limiting: max. 10 Versuche pro Minute. Nach 60 Sekunden warten.

Logs direkt auf dem Server

# Core-Logs
sudo journalctl -u octopos-core -f

# Audit-Log
sudo tail -f /var/log/octopos/audit.jsonl | python3 -m json.tool

# nginx-Logs
sudo tail -f /var/log/nginx/error.log