weisser.dev (Deutsch)

Ein KI-Agent betreibt mein Homelab – und warum das nichts Besonderes ist

2026-10-02T00:00:00+00:00

Mein Homelab hat jetzt Agenten. Einer liest Logs und erklärt, was schiefgelaufen ist. Einer läuft alle 15 Minuten, prüft, ob alles gesund ist – und versucht, Probleme zu beheben. Einer schaut sich die Ergebnisse von CVE-Scans an und aktualisiert verwundbare Abhängigkeiten in meinen eigenen Projekten. Alle sind Claude Code im Headless-Modus (claude -p), gestartet aus meinem selbstgebauten Dashboard.

Die naheliegende Frage: Ist es nicht verrückt, ein LLM auf einen Server loszulassen? Meine Antwort: Wäre es – wenn man ihm eine Root-Shell gibt und weggeht. Aber so betreibt man keine Automatisierung, und so betreibe ich auch diese nicht.

Der Aufbau in einem Absatz

Ein kleiner Dienst (agentd, rund 300 Zeilen Node, keine Abhängigkeiten) läuft neben dem Docker-Host. Mein Dashboard spricht ihn per HTTP mit einem Bearer-Token an; das Dashboard selbst liegt hinter einem Login. agentd startet Agenten-Läufe, verwaltet Zeitpläne und speichert jeden Lauf auf der Platte. Jeder Agent ist in einer kleinen JSON-Datei beschrieben: Name, Standardauftrag, ob er nur lesen darf, und ein gemeinsames Regelwerk. Das ist die ganze Architektur.

Ebene 1: Eine enge, aufgeschriebene Aufgabe

Jeder Agent hat genau eine Aufgabe. Der Log-Agent bekommt: Hol die Logs dieses Containers, gruppiere die Fehler nach Ursache, bewerte sie, schlage Fixes vor – ändere nichts. Der Reparatur-Agent bekommt: Prüfe Container, aktuelle Fehler, Speicherplatz und öffentliche Endpunkte; wenn alles passt, sag das in drei Zeilen, sonst finde die Ursache und behebe sie.

Dazu bekommt jeder Lauf denselben angehängten System-Prompt mit den Hausregeln:

Änderungen an Apps, Compose-Dateien, Proxy-Konfiguration oder Workflows nur über Git: klonen, ändern, committen, pushen – der CI-Runner deployt. Nie direkt auf dem Server editieren.
Ohne Git erlaubt: Logs und Status lesen, einen einzelnen Container neu starten.
Verboten: Daten löschen, Force-Push, Secrets ausgeben, öffentliche Erreichbarkeit ändern, Hosts neu starten, Pakete installieren.
Wenn ein Fix riskant oder unklar ist: nichts ändern, berichten.
Jeder Lauf endet mit denselben drei Abschnitten: Befund, Maßnahmen (mit Commit-Links), Offen.

Weil der Agent in einem Arbeitsverzeichnis unterhalb meines Home-Ordners läuft, lädt er außerdem automatisch dieselbe AGENTS.md, die ich für jeden anderen Assistenten pflege. Er weiß, wie die Infrastruktur aufgebaut ist, wo was liegt und wie hier Änderungen gemacht werden – dasselbe Onboarding, das auch eine neue Kollegin bekäme.

Ein Prompt ist aber keine Sicherheitsgrenze. Er ist die Stellenbeschreibung. Deshalb gibt es weitere Ebenen.

Ebene 2: Jede Aktion wird vor der Ausführung geprüft

Die Agenten laufen im Auto-Berechtigungsmodus von Claude Code. Dabei schaut sich ein separater Sicherheits-Classifier jede Aktion an, bevor sie ausgeführt wird, und blockiert alles, was destruktiv, unumkehrbar oder außerhalb des Auftrags ist. Das habe ich nicht einfach geglaubt: Beim Aufbau dieses Setups wollte meine eigene interaktive Session einen Dienst per API-Aufruf von privat auf öffentlich schalten – und wurde gestoppt, weil das Ändern der öffentlichen Erreichbarkeit genau die Art Entscheidung ist, die bei einem Menschen bleiben sollte. Genau dieses Verhalten will ich auch bei einem unbeaufsichtigten Agenten.

Ebene 3: Eine harte Sperrliste

Der Classifier ist schlau; eine Sperrliste ist dumm und damit berechenbar. Jeder Lauf startet mit --disallowedTools für Befehle, die nie nötig sein sollten: rm -rf, Docker-Volumes löschen oder prunen, git push --force, Reboot und Shutdown, Container auf Hypervisor-Ebene zerstören oder stoppen, mkfs, dd, Paketmanager. Agenten, die nur lesen dürfen, verlieren zusätzlich das Bearbeiten von Dateien, Committen und Pushen. Der Log-Agent kann alles ansehen und nichts anfassen.

Ebene 4: Git ist der einzige Weg hinein

Das ist die wichtigste Ebene, und sie hat mit KI gar nichts zu tun. Meine Regel für mich selbst lautet: Auf dem Server wird nichts von Hand geändert – jede Änderung ist ein Commit, und ein selbst gehosteter Runner deployt sie. Die Agenten folgen derselben Regel.

Damit bekomme ich alles, was ich mir von einem Änderungsprozess wünsche, gratis:

Eine Nachvollziehbarkeit: Jede Änderung ist ein Commit mit einem Trailer, der sie als Agenten-Änderung kennzeichnet.
Einen Diff, den ich hinterher lesen kann.
Ein Rollback mit einem Befehl: git revert, pushen, fertig.
Denselben Deploy-Weg wie für menschliche Änderungen – es gibt keinen „Nur-für-Agenten“-Weg in die Produktion.

Ebene 5: Begrenzter Schadensradius

Höchstens zwei Agenten laufen gleichzeitig, ein geplanter Agent überlappt nie mit sich selbst, und jeder Lauf lässt sich aus dem Dashboard abbrechen. Secrets werden dem Modell nie als Text übergeben. Wenn der CVE-Scanner GitHub-Zugriff braucht, um private Repositories zu prüfen, wird der Token nur für die Dauer dieses einen Scans in eine temporäre Datei geschrieben und danach gelöscht.

Die zusätzliche Überwachung: das Dashboard selbst

Agenten berichten, was sie getan haben. Darauf allein verlasse ich mich nicht.

Jeder Lauf wird vollständig aufgezeichnet. agentd speichert den kompletten Ereignisstrom: jeden Tool-Aufruf, jeden Befehl, jede Ausgabe. Das Dashboard zeigt das live, während der Agent arbeitet, und danach als lesbaren Verlauf. Wenn ein Agent behauptet „Container neu gestartet“, sehe ich den exakten Befehl.
Das Dashboard ist unabhängig von den Agenten. Container-Zustand, Neustarts, Abstürze der letzten 24 Stunden, Speicherplatz, CVE-Zahlen und Erreichbarkeit kommen direkt aus Docker und den Scannern, nicht aus der Zusammenfassung des Agenten. Meldet der Reparatur-Agent „alles gut“, während ein Container in einer Neustart-Schleife hängt, zeigt das Dashboard den Widerspruch.
GitHub ist die zweite Aufzeichnung. Alles, was ein Agent geändert hat, ist ein Commit in einem Repository – sichtbar in der normalen Historie, auf einem anderen System als dem, auf dem der Agent arbeitet.

Warum das nichts Besonderes ist

Nimm das Etikett „KI“ weg und schau, was tatsächlich da ist:

Ein Bot-Account mit enger Aufgabe – wie Dependabot oder Renovate.
Ein Runbook, dem er folgt – wie jede Bereitschafts-Automatisierung.
Minimale Rechte – eine Nur-Lesen-Rolle für Analysen, eine eingeschränkte Rolle für Fixes.
Änderungen über Versionskontrolle und CI – wie jede Deployment-Pipeline der letzten zehn Jahre.
Audit-Logs, ein Not-Aus und ein begrenzter Schadensradius – wie bei jedem Cronjob, den man an Produktion heranlässt.

Keine dieser Ideen ist neu. Wir lassen seit Jahren Skripte, CI-Pipelines und Bots auf Produktionssystemen arbeiten, und das Vorgehen, das sicher zu machen, ist bekannt. Ein Agent ist ein fähigeres Skript, das sich zusätzlich selbst erklärt. Er verdient dieselbe Behandlung wie jede andere Automatisierung: klarer Auftrag, begrenzte Rechte, jede Änderung nachvollziehbar und umkehrbar. Kein blindes Vertrauen, keine Panik.

Was (noch) nicht perfekt ist

Ehrlich zum aktuellen Stand:

Die Agenten laufen auf dem Hypervisor-Host, weil Claude Code dort angemeldet ist, und erben die Rechte dieses Benutzers. Die Ebenen oben begrenzen, was sie tun; eine Sandbox sind sie nicht. Nächster Schritt: ein eigener Systembenutzer mit einer expliziten Liste erlaubter Befehle.
Bei allem, was nicht trivial ist, sollten die Agenten auf einen Branch pushen und einen Pull Request öffnen, statt direkt auf main zu pushen. Kleine, mechanische Fixes (ein Dependency-Update mit grünem Build) dürfen direkt landen. Ein Refactoring nicht.
Es gibt noch kein hartes Zeit- oder Schrittlimit pro Lauf. Ein hängender Lauf muss von Hand abgebrochen werden.

Nichts davon blockiert ein Homelab. Es sind dieselben Backlog-Punkte, die man für jede neue Automatisierung aufschreiben würde – und genau darum geht es.

Mein eigenes Portainer – samt Agenten – an einem Tag mit KI gebaut

2026-10-02T00:00:00+00:00

Mein Homelab besteht aus einem Proxmox-Host, einem Docker-Host und einem wachsenden Haufen Container: ein paar Dienste, die ich selbst baue, viele öffentliche Images, statische Seiten, ein Datenbank-Cluster. Portainer zeigte mir Container an, wusste aber nichts über mein Setup – welcher Hostname öffentlich ist und welcher nur im LAN, welcher Container zu welchem Git-Repo gehört, wann zuletzt deployt wurde, ob ein Backend gerade überhaupt gebraucht wird.

Also habe ich mir das Dashboard gebaut, das ich eigentlich wollte. Der erste Commit entstand mittags; abends lief es produktiv, mit rund 6.700 Zeilen JavaScript, CSS und HTML, 26 Tests und ohne Datenbank. Den Code habe ich fast nicht selbst geschrieben – ich habe Ergebnisse beschrieben, die KI hat sie gebaut und geprüft, und mehrere KI-Agenten haben parallel gearbeitet. Dieser Beitrag zeigt, was dabei herausgekommen ist, wie die Arbeit ablief und was unterwegs schiefging. (Alle Screenshots stammen aus einem Demo-Modus mit erfundenen Daten – keine meiner echten Anwendungen ist darauf zu sehen.)

Was es kann

Ein Dashboard, das den Host kennt. CPU, Arbeitsspeicher, Platten (schnell und langsam), GPU und alles, was in den letzten 24 Stunden abgestürzt ist – auf einen Blick und live aktualisiert.

Stacks und Container, sortiert danach, wie sie gepflegt werden. Selbst Gebautes ist von öffentlichen Images getrennt. Öffentliche Images bekommen einen Auto-Update-Schalter pro Image (ein nächtlicher Job bittet Watchtower, genau die Images zu aktualisieren, die ich aktiviert habe). Jeder Stack verlinkt sein Git-Repo und zeigt, wann zuletzt deployt wurde. Start, Stop, Neustart und ein 48-Stunden-Log-Viewer mit Export sind einen Klick entfernt.

Echtzeit-Zahlen, ohne dafür zu bezahlen. Der naheliegende Weg zu CPU und Speicher pro Container ist docker stats – und der ist erstaunlich teuer: Jeder Aufruf dauert ein bis zwei Sekunden pro Container und hält den Docker-Daemon beschäftigt. Das Dashboard liest stattdessen die cgroup-Zähler direkt aus dem Dateisystem – eine Handvoll winziger Dateizugriffe pro Container – und schickt alle zwei Sekunden Updates per Server-Sent Events an den Browser, aber nur, solange jemand zuschaut.

Ein Ort für „was ist erreichbar“. Docker-Apps hinter dem Reverse Proxy, statische Seiten, externe Seiten, interne Dienste – jeweils mit Typ, öffentlich oder nur LAN, Zugriffsweg, Repo und letztem Deploy. Öffentlich/privat ist ein Schalter; nach dem Umlegen fragt das Dashboard von außen so lange nach, bis der neue Zustand bestätigt ist, statt nur darauf zu hoffen.

Backends, die schlafen, bis sie gebraucht werden. Ein Backend aus mehreren Diensten, das ein paar Mal am Tag benutzt wird, muss nicht den ganzen Tag Speicher und CPU belegen. Ein kleiner Proxy im Dashboard nimmt die Anfragen entgegen, startet den Stack, falls er schläft, hält die Anfrage fest, bis die Dienste antworten, und leitet sie dann weiter – ohne Timeouts, WebSockets inklusive. Nach einer einstellbaren Leerlaufzeit schläft der Stack wieder ein. Ich habe einen Kaltstart von etwa 34 Sekunden für fünf Java-Dienste gemessen; die erste Anfrage wartet einfach so lange und gelingt. Wichtige Details: Health-Checks externer Monitore zählen nicht als Aktivität (und der Proxy beantwortet sie, solange der Stack schläft), und ein Aktivitätsschutz hält einen Stack wach, solange seine Container arbeiten – auch ohne HTTP-Verkehr.

Eine Login-Schranke für Apps ohne Login. Manche Werkzeuge (eine Konverter-Oberfläche, ein Download-Client) haben gar keine Authentifizierung. Ein einziger Reverse-Proxy-Baustein – forward_auth gegen das Dashboard – stellt sie hinter einen gemeinsamen Login, domainweit und mit sicherer Weiterleitung zurück dorthin, wo man herkam.

Agenten, die Logs lesen und CVEs jagen. Das ist der Teil, der mir am besten gefällt:

Der Log-Agent kann Logs analysieren, nach Anomalien suchen (im Vergleich mit den Stunden davor) oder die Docker-Compose-Dateien anhand echter Messwerte feintunen und Änderungen als Pull Request vorschlagen.
Der CVE-Agent arbeitet mit Trivy-Scan-Ergebnissen und hat vier Modi: nur finden, Triage (wird das verwundbare Paket zur Laufzeit überhaupt genutzt?), als Pull Request beheben oder direkt auf den Standard-Branch beheben nach grünem Build. Vor einem Modus, der etwas ändert, prüft er, ob GitHub erreichbar und beschreibbar ist – andernfalls wird der Lauf still auf „nur lesen“ herabgestuft.
Alles ist in der Oberfläche konfigurierbar: Modi, Modell, Zeitlimit, Aufträge (Vorlagen mit Platzhaltern), Repositories, Zeitpläne und sogar das Befehls-Präfix, mit dem Docker erreicht wird – damit dasselbe Setup auf einem anderen Rechner läuft.

Ein echtes Beispiel, warum der Triage-Modus sich lohnt: Bei einer älteren React-Seite meldete der Scanner 79 kritische und hohe Befunde, drei davon kritisch. Der Agent las den Code und das Build-Setup und stufte fast alle als Build- oder Dev-Werkzeug ein, das nie in einen Browser ausgeliefert wird – Gesamtrisiko gering – und nannte die wenigen Fixes, auf die es wirklich ankommt. Genau diesen Bericht hätte ich mir von einem Kollegen gewünscht – geliefert in Minuten.

(Wie ich solche Agenten in ihrer Spur halte, behandelt der vorige Beitrag.)

Einstellungen für alles. Aktualisierungsintervalle, Live-Metriken, Auto-Update-Uhrzeit, Schlaf-Vorgaben, Agentenverhalten – eine Seite, keine Code-Änderungen.

Wie ich mit der KI gearbeitet habe

Für das Dashboard habe ich kaum einen Editor angefasst. Der Ablauf sah so aus:

Das Ergebnis in normalen Sätzen beschreiben, auch die lästigen Teile („es darf nicht in einen Timeout laufen, während das Backend startet“), und die KI zuerst eine kurze Spezifikation in die AGENTS.md des Repos schreiben lassen.
Die KI in kleinen Schritten bauen lassen – committen, pushen, per CI deployen und dann live verifizieren: mit curl einloggen, die neuen Endpunkte aufrufen, die Antwortform prüfen, die Tests laufen lassen. „Es kompiliert“ galt nie als fertig.
Parallele Agenten für unabhängige Arbeit. Für die größere Sitzung hinter diesem Beitrag liefen sechs Sub-Agenten gleichzeitig – Speicher und Migrationen, CVE-Fixes, der Reverse Proxy, die Blog-Struktur, Hosting-Schalter, eine Medien-Pipeline –, jeder mit derselben Briefing-Datei (den Regeln: alles über Git, keine Geheimnisse in Ausgaben, vor dem Melden verifizieren) und eigenem Code-Bereich.
Eine einzige Quelle für Kontext: eine AGENTS.md, die jeder Agent lädt. Sie ist langweilig, und sie ist der Grund, warum die Agenten nicht dieselben Erkenntnisse immer wieder neu entdecken.

Was schiefging (und was ich gelernt habe)

Das Dashboard sagte „öffentlich“ bei etwas Privatem. Der Status wurde daraus abgeleitet, in welchem Ordner eine Konfigurationsdatei liegt – und ein Deploy aus Git legte die Datei still wieder zurück. Die Lösung: Maßgeblich ist die Tunnel-Regel, also das, was tatsächlich erreichbar ist, nicht das, was eine Datei behauptet. Zustand aus der Wirklichkeit ableiten.
„Das Dashboard ist langsam“ lag nicht am Dashboard. Drei Videokonvertierungen und mehrere parallele Builds hatten eine einzelne langsame Festplatte gesättigt (ein Plattentest zeigte etwa 8 dauerhafte Schreibvorgänge pro Sekunde gegenüber 444 auf der SSD). Die Lösungen: Datenbanken auf die SSD, schwere Jobs mit einer Sperre serialisiert, CPU-Deckel für den Konverter und Stale-while-revalidate-Caching mit Aufwärmen im Hintergrund, damit die Oberfläche nie auf eine teure Abfrage wartet.
Das Verschieben des Container-Speichers bei laufenden Containern ließ sie in den alten, gelöschten Pfad schreiben. Uploads scheiterten etwa eine Stunde lang; der Log-Agent brachte das Symptom ans Licht, und die Ursache war mein eigener Speicherumzug. Lehre: Nach einer Migration mit einem Schreibtest prüfen, nicht mit ls.
Selbst die Screenshots brauchten einen Umweg. Das --screenshot von Headless-Chrome lieferte bei einer Seite mit Live-Ereignisstrom leere Bilder; den Browser über sein DevTools-Protokoll zu steuern löste das – und lieferte als Bonus bessere Bilder in voller Höhe.

Was sich zum Abschauen lohnt

Keine Datenbank. JSON-Dateien neben dem Container reichen für Einstellungen und Schlafzustand und machen das Ganze trivial umziehbar.
Git ist die Quelle der Wahrheit für Konfiguration; die Wirklichkeit ist die Quelle der Wahrheit für Zustand.
Billig messen. Lesen, was der Kernel ohnehin zählt.
Würdevoll ausfallen. Ist GitHub nicht erreichbar, berichtet der Agent trotzdem; ist die Tunnel-API nicht erreichbar, sagt der Status „unbekannt“, statt zu lügen.
Die KI für die Verifikation einsetzen, nicht nur für den Code. Die wertvollsten Agentenläufe waren die, die andere Arbeit geprüft haben.

Das Dashboard ist (noch) nicht Open Source und stark auf mein eigenes Setup zugeschnitten. Aber die Bausteine – cgroup-basierte Metriken, ein Aufweck-Proxy, der Anfragen festhält, ein forward_auth-Gate, modusbasierte Agenten mit GitHub-Vorprüfung – sind klein genug, um sie an einem Nachmittag selbst zu bauen. Heute hat mich daran erinnert, wie kurz „ein Nachmittag“ geworden ist.

awesome-opencode: 108 Agents, 15 Skills, and a 2-Minute Setup for OpenCode

2026-03-27T00:00:00+00:00

Setting up OpenCode properly – agents, skills, model configuration, MCP servers, project rules – takes about 30 minutes if you read the docs and do it by hand. Or 2 minutes with one command:

npx @weisser-dev/awesome-opencode

awesome-opencode is an interactive CLI tool and template collection that analyzes your project, recommends the right configuration, and generates everything OpenCode needs to work well with your stack. 108 agents across 10 categories, 15 skills, 18 curated MCP servers, smart model detection, and an auto-generated AGENTS.md – all from a single npx command.

Why this exists

OpenCode is powerful, but the configuration surface is large. You need to decide which agents to install, how to write skill definitions, which MCP servers to connect, how to assign models to different agent tiers, and what project rules to define in AGENTS.md. Most of this requires reading multiple documentation pages, and the result is that many teams either skip configuration entirely or set up a minimal config that doesn’t take advantage of what OpenCode can do.

The specific problems I wanted to solve:

Agent discovery. With 108 available agents across 10 categories, knowing which ones are relevant to a Terraform-heavy infrastructure project versus a React frontend is not obvious. The tool scans your project files (.tf maps to Terraform, .rs to Rust, and so on for 28 language/technology mappings) and recommends agents with reason tags explaining why – (Terraform (IaC)), (Docker / Containers), (default).
Model optimization. Using the same frontier model for every agent is expensive and unnecessary. A code-writing agent needs Opus or GPT-5.2, but a context manager or documentation agent runs fine on Haiku or Flash. Configuring this per agent manually is tedious. The tool detects your existing models, benchmarks them, and assigns the right tier automatically.
MCP server fragmentation. MCP servers are scattered across mcp.so, GitHub repositories, and the official registry. The tool curates 18 servers filtered by your project languages, plus live search against the official MCP Registry API.
AGENTS.md. Project rules are one of the most impactful things you can configure, but writing them from scratch for every project is the kind of task that gets deferred forever.

How it works

The CLI follows a linear flow that takes about two minutes:

1. Language detection. Auto-detects languages by scanning file extensions in your project root. You can also select manually for fresh projects with no files yet.

2. Agent selection. Presents all 108 agents organized by category – Core Development, Language Specialists, Infrastructure, Quality & Security, Data & AI, Developer Experience, Specialized Domains, Business & Product, Meta & Orchestration, Research & Analysis. Agents recommended for your detected languages appear first with reason tags.

3. Skill selection. 15 skills covering common workflows: git-release, pr-review, migration, test-patterns, deploy, dependency-audit, incident-postmortem, docker-optimize, adr-write, api-contract, changelog-generate, ci-pipeline, env-setup, error-triage, performance-profile.

4. Model strategy. Reads your existing opencode.json, fingerprints every configured model (even through custom Bedrock or Azure provider prefixes like eu.anthropic.claude-opus-4-6-v1), shows coding benchmarks on a 0–100 scale and cost tiers from $ to $$$$$, then offers to auto-optimize: frontier models for code-writing agents, strong models for review agents, fast models for context and exploration.

5. MCP servers. Curated list filtered by your languages, plus an optional live search against registry.modelcontextprotocol.io to find and configure any registered server.

6. Step limits. Optional per-agent step limits for cost control – code-writing agents get unlimited steps, review agents get 10–15, fast agents get 5–10.

7. Generation. Writes .opencode/agents/*.md, .opencode/skills/*/SKILL.md, updates opencode.json, creates .opencode/advanced.json (state for re-runs), and generates AGENTS.md with project-specific rules.

On re-run, the tool detects the existing configuration and offers to start OpenCode directly or reconfigure.

Model fingerprinting

The part I find most technically interesting is the model detection. LLM provider IDs rarely follow a consistent naming convention. If you use Amazon Bedrock, your model ID might be abcd/eu.anthropic.claude-opus-4-6-v1. Azure has its own format. Self-hosted endpoints use whatever the operator decided. But the tool still needs to know that this is Claude Opus 4 so it can look up the benchmark score and assign the right agent tier.

The solution is 26 model fingerprints – regex patterns that extract the canonical model identity from any provider-prefixed ID. The fingerprinting covers Anthropic (Claude), OpenAI (GPT, o-series), Google (Gemini), DeepSeek, Meta (Llama), and Mistral. Each fingerprint maps to a tier (frontier, strong, fast), a cost bracket, and a coding benchmark score sourced from pricepertoken.com.

The auto-optimize strategy then maps agent types to tiers:

Agent type	Model tier	Step limit	Example
Code-writing, language specialists	Frontier	Unlimited	Opus, GPT-5.2, o3
Code review, architecture, security	Strong	10–15	Sonnet, GPT-5.1
Exploration, docs, context management	Fast	5–10	Haiku, Flash, mini

This means you can run 20+ agents without paying frontier prices for all of them, while the agents that actually write and review code still get the best models available.

The 108 agents

Every agent is a markdown file with YAML frontmatter defining the description, mode, model tier, temperature, permissions, and step limit. The categories:

Core Development (8) – API design, backend, frontend, fullstack, GraphQL, microservices, mobile, WebSocket
Language Specialists (22) – Angular through Vue, covering the major languages and frameworks with specialist knowledge
Infrastructure (13) – cloud architecture, Kubernetes, Terraform, Docker, SRE, incident response
Quality & Security (11) – code review, penetration testing, compliance, accessibility, chaos engineering
Data & AI (12) – data engineering, ML, LLM architecture, prompt engineering, NLP
Developer Experience (11) – build systems, CLI tools, documentation, refactoring, testing
Specialized Domains (8) – blockchain, embedded systems, fintech, game development, IoT
Business & Product (9) – product management, technical writing, UX research, scrum
Meta & Orchestration (7) – multi-agent coordination, context management, workflow automation
Research & Analysis (7) – competitive analysis, market research, trend forecasting

The agent collection is adapted from VoltAgent/awesome-claude-code-subagents, reworked for OpenCode’s markdown agent format with permissions, skill integration, and tier assignments.

Technical details

The CLI is pure ESM Node.js – no TypeScript compilation, no build step. The core logic lives in a single setup.js file of about 1,800 lines. Agent and skill templates are plain markdown files stored in the repo’s templates/ directory, not embedded strings, which means they’re easy to review, edit, and contribute to.

Dependencies are minimal: @inquirer/prompts for interactive selection, chalk for terminal colors, ora for spinners. A prepublishOnly script syncs templates from the repo root into the npm package before publishing. CI validates that the agent count stays at 108+, the skill count at 15+, templates are in sync, and syntax is correct.

Getting started

npx @weisser-dev/awesome-opencode

That’s it. If you want to install globally instead:

npm install -g @weisser-dev/awesome-opencode
awesome-opencode

For manual setup without the CLI – copying individual agent and skill templates – see the README.

Contributing

The project is MIT-licensed and welcomes contributions. The most useful additions right now are new agent templates (add a markdown file to templates/agents/ and register it in AVAILABLE_AGENTS in setup.js), new skill definitions (add a SKILL.md to templates/skills/<name>/ and register in AVAILABLE_SKILLS), model fingerprints for new providers, and MCP server recommendations.

Credits

VoltAgent/awesome-claude-code-subagents – the 127+ agent collection that served as the primary inspiration, adapted for OpenCode’s format
darrenhinde/OpenAgentsControl – agent configuration patterns
OpenCode Docs – agents, skills, MCP, permissions, and configuration reference
pricepertoken.com – model benchmark rankings and pricing data
registry.modelcontextprotocol.io – official MCP server registry API
mcp.so – community MCP server directory

opencode-remote-telegram: Control OpenCode from Your Phone via Telegram

2026-03-25T00:00:00+00:00

opencode-remote-telegram is a Telegram bot that lets you control OpenCode from your phone. Pick a project, pick a model, type what you want — the agent works, you get the formatted result.

The origin story

The project was inspired by RoundTable02/remote-opencode, a Discord bot for remote OpenCode access. The goal: take the concept, build a clean Telegram-native version with proper UX. It turned into a full rewrite — per-instance auth, SSE event handling, inline keyboards, persistent state, and a system prompt that teaches the model to format its output for Telegram.

How it works

Your Phone (Telegram)
        │
        ▼
opencode-remote-telegram
        │  spawns per project, on demand
        │  per-instance random Basic Auth
        │  idle timeout: 10 min
        ▼
opencode serve  (HTTP API + SSE)
        │
        ▼
Your Codebase

The bot spawns opencode serve in your project directory when you start a coding session. Each instance gets a randomly generated password. Prompts are sent with a system prefix that instructs the model to format output for Telegram (no markdown tables, short paragraphs, code in fenced blocks). Responses are collected silently while witty loading messages rotate, then delivered as properly formatted HTML.

Install

npm install -g @weisser-dev/opencode-remote-telegram

Setup

opencode-remote-telegram setup

The wizard walks you through four steps:

1. Telegram Bot Token

Open Telegram → search for @BotFather → /newbot
Copy the token (looks like 1234567890:ABCdef…)

2. Access control

Message @userinfobot to find your Telegram user ID
Enter your ID to restrict access

3. Projects base directory

Point to your projects folder — subdirectories are auto-discovered
Example: ~/Projects → discovers ~/Projects/my-app, ~/Projects/api

4. OpenCode config

Recommended: use a single global opencode.json for all projects
Place it at ~/.config/opencode-remote-telegram/opencode.json
This prevents project-level configs from overriding credentials

Verify the setup

opencode-remote-telegram test

This checks: config loaded, projects found, models loaded, server starts, test prompt gets a response.

Start the bot

opencode-remote-telegram start

On first /start in Telegram, the bot shows an onboarding with inline buttons: pick a project, pick a model, start coding.

Commands

Projects

/list_projects — inline keyboard, tap to switch
/new_project — clone a GitHub repo interactively
/switch_project <alias> — switch by name

Models

/list_models — inline keyboard, tap to switch
/switch_model <name> — switch by name

Coding

/vibe_coding — start passthrough session
/stop_coding — stop session
/interrupt — interrupt running task
/diff — git diff --stat HEAD
/undo — revert last commit (soft reset, with confirmation)

Stats & History

/show_stats — token count, cost, duration after each response
/hide_stats — hide stats
/history — last 10 prompts with model and cost
/costs — daily and weekly cost summary

Queue

/queue_list — show queued prompts
/queue_clear — clear queue
/queue_settings — toggle continue-on-failure

Info

/status — project, model, queue, settings
/clear — reset everything
/help — all commands

The user experience

When you send a message while vibe coding is inactive (e.g. after a server restart), the bot offers three options:

Start & send this message — activates vibe coding and immediately sends your text as the first prompt
Just start coding — activates vibe coding, waits for the next message
No — shows project/model/help buttons instead

While the agent is working (reading files, running tools), witty loading messages rotate every 4 seconds. The final response is delivered as a single formatted message — no partial streaming output, no thinking text.

Configuration files

All config lives in ~/.config/opencode-remote-telegram/:

config.json — bot token, allowed users, project path
opencode.json — global OpenCode config (providers, models)
state.json — persisted state (project/model per chat, settings, history)
logs/ — daily log files

Debug mode

opencode-remote-telegram --debug start

Logs every incoming message, command, callback and outgoing reply with timestamps.

What this is a demo of

The entire project was built with OpenCode — including the architecture decisions, the SSE event mapping, and the Telegram formatting layer. It’s a live example of AI-assisted development: describe what you want, iterate on the output, ship it.

Inspired by RoundTable02/remote-opencode — if you want OpenCode via Discord instead of Telegram, check it out.

Accidentally Committed Credentials to a Public Repo?

2026-03-24T00:00:00+00:00

It happens. You paste terminal output into a blog post, commit a .env file, or an AI agent includes a real credential in generated content. The secret is now in a public repository. Here is what to do.

Step 1: Revoke the credential immediately (< 60 seconds)

This is the only step that actually stops the damage. Do it before anything else.

The credential is already compromised the moment it hits a public repo. Automated scanners like GitGuardian, truffleHog, and GitHub’s own secret scanning pick up new commits within seconds. Assume it has already been seen.

Credential type	How to revoke
Telegram Bot Token	`@BotFather` → `/mybots` → select bot → API Token → Revoke
GitHub Personal Access Token	Settings → Developer settings → Personal access tokens → Delete
OpenAI API Key	platform.openai.com → API keys → Delete
AWS Access Key	IAM → Users → Security credentials → Deactivate + Delete
Discord Bot Token	Developer Portal → Application → Bot → Reset Token
Generic API key	Check the provider’s dashboard — every service has a revoke/rotate option

After revoking, generate a new credential and store it properly (see Step 4).

Step 2: Remove it from the current content

Fix the file that contains the secret right now. Replace the real value with a placeholder:

# Before
OPENCODE_SERVER_PASSWORD=fd691649-311e-4418-98fa-6a0e21a2659b

# After
OPENCODE_SERVER_PASSWORD=<generated-uuid>

Commit and push the fix:

git add .
git commit -m "fix: replace leaked credential with placeholder"
git push

This does not remove it from history — but it removes it from the current state and shows intent.

Step 3: Wipe the Git history

Deleting a commit does not delete history. Anyone who cloned or forked the repo before the fix still has the secret. GitHub also caches commit content internally.

The cleanest option for a personal repo is an orphan reset — this replaces the entire history with a single new initial commit containing only the current (clean) state:

# 1. Create a new orphan branch (no history)
git checkout --orphan clean-start

# 2. Stage everything in its current clean state
git add -A

# 3. Create a single new initial commit
git commit -m "initial commit"

# 4. Delete the old main branch
git branch -D main

# 5. Rename the orphan to main
git branch -m main

# 6. Force push to overwrite the remote history
git push --force origin main

After this, git log shows exactly one commit.

For repositories with collaborators or forks, the orphan approach is still the fastest path. Inform anyone who has a local clone — they will need to re-clone:

git clone https://github.com/you/your-repo.git

They cannot git pull after a force push that rewrites history — a fresh clone is required.

Alternative: BFG Repo Cleaner

If you want to keep the full history but surgically remove only the secret, BFG Repo Cleaner is faster than git filter-branch:

# Install (macOS)
brew install bfg

# Create a file listing the secret strings to remove
echo "fd691649-311e-4418-98fa-6a0e21a2659b" > secrets.txt

# Run BFG against a bare clone
git clone --mirror https://github.com/you/your-repo.git repo-mirror.git
bfg --replace-text secrets.txt repo-mirror.git

# Clean up and force push
cd repo-mirror.git
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git push --force

BFG rewrites every commit that contains the string, replacing it with ***REMOVED***. History is preserved but the secret is gone.

Step 4: Store secrets properly going forward

The root cause is almost always that a secret ended up somewhere it should not be — a blog post, a committed config file, a debug log. Here is the prevention stack:

Never commit secrets to Git

Use .gitignore from the start:

# .gitignore
.env
.env.local
*.config.json
*secret*
*credentials*

Use a local config file pattern

For project configs that contain tokens, keep the real file gitignored and commit only a template:

remote-opencode.config.json       # gitignored, contains real token
remote-opencode.config.example.json  # committed, contains placeholders

Use environment variables

export TELEGRAM_BOT_TOKEN="your-token"
# or in .env (gitignored):
TELEGRAM_BOT_TOKEN=your-token

Use a secret manager for teams

Enable GitHub secret scanning

In your repo settings: Security → Secret scanning → Enable. GitHub will alert you if a known secret pattern appears in a push before it causes damage.

Add pre-commit hooks

detect-secrets or gitleaks scan your staged changes before every commit:

# Install gitleaks (macOS)
brew install gitleaks

# Scan your repo
gitleaks detect --source .

# Add as pre-commit hook
gitleaks protect --staged

For AI agents: a note

If you are an AI agent writing documentation, blog posts, or code — never include real credential values, even when quoting terminal output or debugging logs. Always replace with placeholders like <your-token>, <generated-uuid>, or ***.

See AGENTS.md for the full rules.

Checklist

When you find a leaked credential:

Revoke the credential immediately
Fix the current file (replace with placeholder)
Commit and push the fix
Wipe Git history (orphan reset or BFG)
Force push
Notify anyone who may have cloned the repo
Generate a new credential and store it securely
Add .gitignore rules to prevent recurrence
Consider enabling GitHub secret scanning

My Typical Frontend Hosting Setup: Strato + Cloudflare + Pages

2026-03-24T00:00:00+00:00

Every frontend project I ship — agentic-ai.weisser.dev, scrumbuddy.org, cv.weisser.dev and others — follows the same hosting pattern: domain registered at Strato, DNS managed by Cloudflare, site deployed via Cloudflare Pages. It’s free, automatic, and takes about 10 minutes to set up the first time.

The stack

Strato — domain registrar. That’s all it does in this setup.
Cloudflare — DNS, SSL, CDN, and the actual hosting via Cloudflare Pages.
GitHub — source of truth. Every push triggers a build and deploy automatically.
Vite (or any static site generator) — the build tool. Output goes to dist/.

Step 1: Point your Strato domain to Cloudflare

Log in to Strato, go to your domain settings and change the nameservers to the two Cloudflare nameservers assigned to your account. They look like *.ns.cloudflare.com — you’ll find the exact values in your Cloudflare dashboard under DNS > Nameservers after adding the domain there.

In Cloudflare: Add a site → enter your domain → choose the free plan → Cloudflare scans your existing DNS records → you confirm and note down the two nameserver addresses → go back to Strato and enter them.

DNS propagation takes a few minutes to a few hours. Once it’s done, Cloudflare controls everything.

Step 2: Create a Cloudflare Pages project

Heads up: If you navigate to Workers & Pages in the Cloudflare dashboard and click Create, you’ll land on the Workers tab by default. Don’t start creating a Worker — look for the small link that says something like “Looking for Pages? Create a Pages project here” (or similar wording, Cloudflare changes this occasionally). Click that to get to the actual Pages setup. This trips up almost everyone the first time.

Go to pages.cloudflare.com → Create a project → Connect to Git → authorize Cloudflare to access your GitHub account → select the repository.

Configure the build settings:

Setting	Value
Branch	`main`
Build command	`npm run build`
Build output directory	`dist`

For plain HTML/CSS/JS with no build step, leave the build command empty and set the output directory to /.

Click Save and Deploy. Cloudflare clones the repo, runs the build, and publishes to a *.pages.dev URL in under a minute.

Step 3: Add your custom domain

In your Pages project, go to Custom domains → Set up a custom domain → enter your domain (e.g. agentic-ai.weisser.dev). Since your domain is already on Cloudflare, it creates the DNS record automatically and provisions SSL via Let’s Encrypt within minutes.

That’s it. The next git push to main will automatically trigger a new build and deploy. No CI pipeline to maintain, no server to manage, no bill at the end of the month.

Why this works well

The thing I like most about this setup is how little there is to think about once it’s running. Cloudflare handles SSL renewal, CDN caching, DDoS protection, and deployment all in one place. The free tier is genuinely generous for personal projects and small tools — unlimited bandwidth, 500 builds per month, custom domains included.

The only thing Strato does in this setup is hold the domain registration. If you’re registering a new domain, you could also register it directly in Cloudflare and skip the nameserver step entirely — but for domains you already have elsewhere, the nameserver delegation works just as well.

Why Cloudflare Pages over GitHub Pages

Both are free for static sites, but Cloudflare Pages has two advantages that matter in practice:

Private repos work for free. GitHub Pages requires a public repository on the free plan — if you want to deploy from a private repo, you need GitHub Pro or a GitHub Team/Enterprise plan. Cloudflare Pages deploys from private repos at no cost.
Every commit gets its own preview URL. Each push — not just to main, but to any branch or pull request — gets a unique <commit-hash>.pages.dev URL. This makes it trivial to review changes, share previews with others, or roll back to any previous deployment.

For public open-source sites where the source doesn’t need to be private, GitHub Pages works fine. For everything else — side projects, client work, internal tools — Cloudflare Pages is the better choice.

Reference

dilatchi/cloudflare-static-site-demo — a clean tutorial repo that walks through the same steps with screenshots
pages.cloudflare.com

Building an Interactive AI Agent Workshop with Vite and Vanilla JS

2026-03-23T00:00:00+00:00

A few weeks ago I set out to build a complete, interactive workshop about AI Agents, LLMs, and AI-assisted coding — something that could be used both as a live presentation and as a self-guided learning resource. The result is agentic-ai.weisser.dev, a bilingual (German/English) web application built entirely with Vite and Vanilla JavaScript. The interesting twist: the entire project was developed using OpenCode, an AI coding agent — which made it a kind of meta-exercise in the topic itself.

The application ships in two distinct modes. Presenter mode is designed for live workshops: it includes a full slide deck with keyboard navigation, a confetti cannon for celebratory moments, and a session timer to keep things on schedule. Slides are authored in plain HTML/JS with a custom layout system — no external presentation framework. Self-paced mode lets participants work through the material independently, complete with embedded quizzes, collapsible hints, and progress tracking stored in localStorage. Both modes share the same underlying content model, so updates to the material propagate everywhere automatically.

The design system is entirely custom — a dark-first palette with carefully chosen contrast ratios, consistent spacing tokens, and a set of utility classes that kept the CSS manageable without reaching for Tailwind or a component framework. Bilingual support was implemented as a simple key-value JSON structure with a language toggle. No i18n library was pulled in; given the scope, a few dozen strings per language, the overhead wasn’t justified.

What made this project technically interesting was the challenge of building a presentation tool without a framework. State management — tracking the current slide, quiz answers, timer state — had to be done intentionally rather than delegated to React or Vue conventions. It forced clarity about what actually needs to be stateful versus what can just be re-rendered from the DOM. The build pipeline with Vite made the development experience fast despite the lack of a framework, with instant HMR and a clean production bundle.

The meta-story here is just as interesting as the technical one. The project was built almost entirely through conversations with OpenCode, an AI coding agent running in the terminal. Features were described in natural language, the agent wrote the code, and I reviewed and iterated. This workflow is exactly what the workshop teaches, so the process of building it was itself a live demonstration of the concepts. The final codebase is clean, well-structured, and doesn’t show obvious signs of “AI-written spaghetti” — which I consider a meaningful data point about the maturity of agent-assisted development in 2026.

OpenPastebin: A Self-Hosted Pastebin with Automatic Expiration

2026-03-22T00:00:00+00:00

Every developer has reached for a pastebin at some point — to share a log snippet, pass a config file to a colleague, or dump some output during a debugging session. The existing options are either commercial services with opaque data retention policies, ad-supported with tracking, or old open-source projects that haven’t been touched in years. OpenPastebin is my attempt to fix that: a clean, modern, self-hosted pastebin you can run yourself in minutes.

The core feature set is deliberately minimal. Paste some text, set an expiration (minutes, hours, days, or never), get a short URL back. No accounts required. The paste expires and is deleted from storage automatically. That’s it. The API-first design means every action available in the UI is also available via a plain HTTP call, making it trivially easy to pipe data in from scripts or CI pipelines — curl -X POST https://your-instance/api/paste --data "content=hello" and you get a URL back.

Under the hood, the stack is Node.js with a straightforward REST API and a minimal frontend that doesn’t require a build step. Storage is handled by a simple key-value approach with TTL support — Redis works well here, but there’s also a file-based fallback for setups that don’t want to run an additional process. The expiration mechanism relies on the storage layer’s native TTL rather than a background cleanup job, which keeps the application code simple and the operations footprint small.

Self-hosting matters for a tool like this more than it might seem. Paste content is often sensitive: API keys accidentally left in a snippet, internal configuration, stack traces with file paths. When you self-host, you control exactly who can read that data and for how long. For teams running their own infrastructure, deploying OpenPastebin behind an internal reverse proxy takes ten minutes and means sensitive paste content never leaves your network. The Docker image is available, configuration is environment variables, and there’s no database migration step — a fresh instance is ready to accept pastes immediately.

Building Custom Sub-Agents for AI-Assisted Workflows

2026-02-24T00:00:00+00:00

As AI coding agents have become part of my daily workflow, I’ve started building specialized sub-agents — focused, single-purpose agents that can be invoked by a parent orchestrator to handle specific tasks. The own-subagents project is a collection of these: Shell-based sub-agents designed for specific automation tasks that I run repeatedly in my development workflow.

The design philosophy for sub-agents is narrow scope and explicit I/O. A sub-agent should do one thing well: analyze a codebase for a specific pattern, generate a changelog from git history, validate a configuration file, or transform data from one format to another. The input is well-defined (usually JSON or plain text via stdin), the output is well-defined (JSON or formatted text to stdout), and the sub-agent has no side effects beyond what’s explicitly in its spec. This makes them composable — the orchestrator can chain sub-agents, pass outputs between them, and handle errors at the orchestration level.

Shell is a pragmatic choice for sub-agents that primarily orchestrate other command-line tools. A sub-agent that needs to run git commands, call the OpenCode CLI, manipulate files, and pass data between steps can do all of this in a shell script with no additional runtime dependencies. The Shell environment’s pipe-and-filter model aligns well with the sub-agent pattern: each tool in the pipeline is itself a form of sub-agent.

The most valuable thing I’ve learned from building multi-agent pipelines is that reliability depends on the quality of the handoffs between agents. An orchestrator that gives a sub-agent ambiguous instructions or an imprecise schema will get unpredictable results regardless of how capable the sub-agent is. Investing in precise, typed interfaces between agents — with validation at each handoff point — is the engineering work that makes multi-agent systems actually reliable rather than just theoretically possible.

OpenClaw Setup on VPS

2026-02-24T00:00:00+00:00

This guide walks you through installing OpenClaw on a VPS (Virtual Private Server) like Hetzner, DigitalOcean, or similar providers.

Prerequisites

VPS with Ubuntu 22.04+ or Debian 12+
Root or sudo access
Domain name (optional, for remote access)
At least 2GB RAM (4GB recommended for model inference)

Step 1: Install Node.js 22

OpenClaw requires Node.js 22 or newer.

# Using nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
nvm alias default 22

# Verify installation
node --version  # Should show v22.x.x
npm --version

Step 2: Install OpenClaw

# Install OpenClaw globally
npm install -g openclaw

# Verify installation
openclaw --version

Step 3: Run the Onboarding Wizard

openclaw onboard --install-daemon

The wizard will guide you through:

Gateway configuration (port, bind address, auth)
Model provider setup (OpenAI, Qwen, Anthropic, etc.)
Channel configuration (Telegram, Discord, WhatsApp, etc.)
Daemon installation (systemd service)

Step 4: Configure Gateway for Remote Access

Edit ~/.openclaw/openclaw.json:

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "0.0.0.0",
    "auth": {
      "mode": "token",
      "token": "your-secure-token-here"
    },
    "tailscale": {
      "mode": "off"
    }
  }
}

Step 5: Configure Firewall

# Allow OpenClaw gateway port
sudo ufw allow 18789/tcp
sudo ufw allow 22/tcp
sudo ufw enable

Step 6: Install and Configure Nginx (Optional, for HTTPS)

sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx

sudo nano /etc/nginx/sites-available/openclaw

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

# Get SSL certificate
sudo certbot --nginx -d your-domain.com

Step 7: Verify Gateway Status

openclaw gateway status
openclaw logs --follow
curl http://127.0.0.1:18789/health

Step 8: Connect Channels

After gateway is running, configure your channels:

# Telegram Bot
openclaw configure --section telegram

# Discord Bot
openclaw configure --section discord

Security Considerations

Use strong auth tokens – Generate with openssl rand -hex 32
Enable firewall – Only allow necessary ports
Use HTTPS – Always use reverse proxy with SSL for production
Regular updates – Run npm update -g openclaw periodically
Monitor logs – Check openclaw logs for suspicious activity

Troubleshooting

# Gateway won't start – check if port is in use
sudo lsof -i :18789

# Check logs
openclaw logs --tail 100

# Restart daemon
openclaw gateway restart

Next Steps

OpenClaw Subagents Guide

2026-02-24T00:00:00+00:00

Subagents allow you to spawn specialized AI agents for specific tasks, enabling better context management and task separation.

What are Subagents?

Subagents are isolated agent sessions with their own:

Workspace – Separate file context
Model – Can use different models than the main agent
Memory – Independent conversation history
Tools – Same tool access as main agent

When to Use Subagents

Scenario	Use Subagent?	Why
Quick question	No	Main agent is faster
Complex coding task (>20 min)	Yes	Isolated context, parallel execution
Multi-file refactoring	Yes	Focused workspace
Background monitoring	Yes	Runs independently
Specialized domain (e.g., food tracking)	Yes	Domain-specific knowledge

Recommended Project Structure

own-subagents/
├── global/                    # Reusable subagent definitions
│   ├── frontend-builder.md
│   ├── backend-builder.md
│   ├── test-writer.md
│   ├── code-reviewer.md
│   ├── security-reviewer.md
│   └── meal-screenshot-intake.md
├── runtime-workspaces/        # Active agent workspaces (auto-generated)
└── workspace/
    └── AGENTS.md

Creating Subagents

Via CLI

openclaw agents add backend-builder \
  --workspace /root/.openclaw/workspace/own-subagents/runtime-workspaces/backend-builder

Example Subagent Definition

# backend-builder

## Purpose
Implements API, data model, and business logic changes.

## Inputs
- Endpoint/feature description
- Data model constraints
- Security requirements

## Outputs
- Implementation + validation
- Tests/smoke checks
- Migration/compatibility notes

## Boundaries
- No secret exposure
- No destructive DB operations without approval

## Definition of Done
- Relevant tests green
- Input validation present
- Error cases handled sensibly

Routing Strategy

Task Classification Matrix

Task	Agent
Fix login bug in health-tracker	`backend-builder`
Write E2E tests	`test-writer`
Food screenshot intake	`meal-screenshot-intake`
Security review	`security-reviewer`

Using Subagents in Practice

# Spawn a backend subagent
openclaw sessions spawn \
  --agent-id backend-builder \
  --task "Implement user registration endpoint with email verification" \
  --mode session \
  --label "user-auth-feature"

# One-shot task (auto-terminates after completion)
openclaw sessions spawn \
  --agent-id code-reviewer \
  --task "Review PR #42 for security issues" \
  --mode run \
  --label "pr-42-review"

Managing Subagents

# List active subagents
openclaw sessions list --kinds subagent

# Send message to running subagent
openclaw sessions send --session-key <key> --message "Prioritize login endpoint"

# Kill subagent
openclaw subagents kill --target backend-builder

# View logs
openclaw logs --session <session-key> --follow

Subagent Lifecycle

Main Agent
    │ spawn
    ▼
Subagent (isolated)
    │ complete
    ▼
Result pushed to Main

Advanced: Orchestrator Pattern

User: "Build a complete user auth system"

Main Agent:
spawn product-owner      → Define requirements
spawn software-architect → Design architecture
spawn backend-builder    → Implement API
spawn test-writer        → Write tests
spawn security-reviewer  → Security audit
Synthesize → Present to user

Model Assignment per Subagent

{
  "agents": {
    "list": [
      {
        "id": "code-reviewer",
        "model": "openai-codex/gpt-5.3-codex"
      },
      {
        "id": "meal-screenshot-intake",
        "model": "qwen-portal/vision-model"
      }
    ]
  }
}

Best Practices

Clear task definitions – Be explicit about inputs, outputs and scope
Set explicit timeouts – --timeout-seconds 3600
Use labels for tracking – --label "feature-user-auth"
Clean up after completion – --cleanup delete
Match models to tasks – Vision tasks need vision models, code reviews benefit from high-quality models

Troubleshooting

# Subagent won't start – check if it exists
openclaw agents list

# Stuck subagent – kill and retry
openclaw subagents kill --target <agent-id>

# Results not returned – verify mode=run for one-shot tasks

Next Steps

OpenClaw with Qwen (Free Models)

2026-02-24T00:00:00+00:00

This guide shows you how to configure OpenClaw to use Qwen Portal’s free AI models – a cost-effective alternative to paid providers like OpenAI or Anthropic.

Why Qwen?

Free to use – No credit card required
Good code capabilities – Qwen Coder model optimized for programming
Large context window – 128k tokens
Vision support – Qwen Vision model for image analysis
OAuth authentication – Simple login flow

Prerequisites

OpenClaw installed (see VPS Setup)
Qwen Portal account (free at portal.qwen.ai)

Step 1: Install Qwen Portal Auth Skill

npm install -g openclaw  # already installed
openclaw plugins install @openclaw/qwen-portal-auth
openclaw plugins list

Step 2: Authenticate with Qwen Portal

openclaw configure --section qwen-portal

This opens a browser OAuth flow and stores the token in ~/.openclaw/agents/<agent>/auth-profiles.json.

Step 3: Configure Qwen Models

Edit ~/.openclaw/openclaw.json:

{
  "models": {
    "providers": {
      "qwen-portal": {
        "baseUrl": "https://portal.qwen.ai/v1",
        "apiKey": "qwen-oauth",
        "api": "openai-completions",
        "models": [
          {
            "id": "coder-model",
            "name": "Qwen Coder",
            "reasoning": false,
            "input": ["text"],
            "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
            "contextWindow": 128000,
            "maxTokens": 8192
          },
          {
            "id": "vision-model",
            "name": "Qwen Vision",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "qwen-portal/coder-model",
        "fallbacks": []
      }
    }
  }
}

Step 4: Test the Configuration

# Test text model
openclaw agent --model qwen --message "Write a Python function to calculate fibonacci"

# Test vision model
openclaw agent --model qwen-vision --message "What's in this image?" --image ./screenshot.png

Model Comparison

Model	Context	Max Tokens	Input Types	Best For
`coder-model`	128k	8k	Text	Code, general tasks
`vision-model`	128k	8k	Text + Image	Image analysis, OCR

Cost Comparison

Provider	Model	Cost per 1M tokens
Qwen Portal	Coder	Free
Qwen Portal	Vision	Free
OpenAI	GPT-4.1	~$10–20
Anthropic	Claude Sonnet	~$3–15

Using Qwen with Subagents

{
  "agents": {
    "list": [
      { "id": "main", "model": "qwen-portal/coder-model" },
      { "id": "code-reviewer", "model": "qwen-portal/coder-model" }
    ]
  }
}

Troubleshooting

# OAuth token expired – re-authenticate
openclaw configure --section qwen-portal

# Model not found – verify config
openclaw models list
cat ~/.openclaw/openclaw.json | jq '.models.providers.qwen-portal'

Next Steps

OpenClaw Model Fallback Configuration

2026-02-24T00:00:00+00:00

OpenClaw supports automatic model fallback when your primary model provider runs into issues (token exhaustion, rate limits, billing errors).

How Fallback Works

OpenClaw handles failures in two stages:

Stage 1: Auth Profile Rotation

Within the same provider, OpenClaw tries alternative auth profiles. Cooldown is applied to failed profiles (1 min – 1 h).

Stage 2: Model Fallback

When all profiles for a provider fail, OpenClaw switches to the next model in agents.defaults.model.fallbacks.

Basic Fallback Setup

Edit ~/.openclaw/openclaw.json:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai-codex/gpt-5.3-codex",
        "fallbacks": ["qwen-portal/coder-model"]
      }
    }
  }
}

Multiple Fallback Chain

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai-codex/gpt-5.3-codex",
        "fallbacks": [
          "openai-codex/gpt-4.1",
          "qwen-portal/coder-model",
          "anthropic/claude-sonnet"
        ]
      }
    }
  }
}

Fallback Triggers

Error Type	Behavior	Backoff
Billing/Credit Error	Profile disabled	5 h – 24 h
Rate Limit (429)	Cooldown	1 min – 1 h
Timeout	Cooldown	1 min – 1 h
Auth Error (401)	Cooldown	1 min – 1 h

Cooldown Progression

1st failure → 1 minute
2nd failure → 5 minutes
3rd failure → 25 minutes
4th+ failure → 1 hour (cap)

Billing errors are treated more seriously (5 h → 10 h → 24 h cap).

Manual Model Switching

# Use specific model for this session
openclaw agent --model qwen-portal/coder-model --message "Hello"

# Change default permanently
openclaw config set agents.defaults.model.primary qwen-portal/coder-model

# Check current setup
openclaw config get agents.defaults.model.primary
openclaw config get agents.defaults.model.fallbacks

Monitoring Fallback Events

# Check auth profile cooldown status
cat ~/.openclaw/agents/main/agent/auth-profiles.json | jq '.usageStats'

# Watch logs for fallback events
openclaw logs --follow | grep -i "fallback\|cooldown\|disabled"

Example Scenarios

Scenario 1: OpenAI Tokens Exhausted

OpenAI returns 402 Payment Required
OpenClaw disables OpenAI profile (5 h)
Automatically switches to Qwen
Continues using Qwen until OpenAI cooldown expires

Scenario 2: Temporary Rate Limit

OpenAI returns 429 Too Many Requests
OpenClaw applies 1-minute cooldown
Retries after cooldown → still rate-limited → falls back to Qwen

Scenario 3: Multi-Provider

OpenAI fails → try Anthropic
Anthropic fails → try Qwen
All fail → error returned to user

Per-Agent Overrides

{
  "agents": {
    "list": [
      {
        "id": "main",
        "model": {
          "primary": "openai-codex/gpt-5.3-codex",
          "fallbacks": ["qwen-portal/coder-model"]
        }
      },
      {
        "id": "code-reviewer",
        "model": {
          "primary": "openai-codex/gpt-5.3-codex",
          "fallbacks": []
        }
      },
      {
        "id": "meal-screenshot-intake",
        "model": {
          "primary": "qwen-portal/vision-model",
          "fallbacks": []
        }
      }
    ]
  }
}

Cost Optimization

Setup	Primary	Fallback	Est. Monthly
OpenAI only	GPT-5.3	None	~$50–200
OpenAI + Qwen	GPT-5.3	Qwen (free)	~$20–80
Qwen only	Qwen	None	$0

Use expensive models for critical tasks (security reviews, production code), free fallback for bulk/routine work.

Troubleshooting

# Fallback not working – verify config
openclaw config get agents.defaults.model.fallbacks

# Stuck on fallback – check cooldowns
cat ~/.openclaw/agents/main/agent/auth-profiles.json | jq '.usageStats'

# Force reset (restart gateway)
openclaw gateway restart

Next Steps

Extending the Health Tracker: Data Visualization and Trends

2026-02-23T00:00:00+00:00

Once you have a health data aggregation layer working, the next question is how to display it usefully. Raw numbers in a table answer “what happened” but don’t help you understand “is this good or bad” or “where is this heading.” The extension I built adds trend charts, weekly summaries, and goal tracking — the visualization layer that turns data into understanding.

For charting, I evaluated a few JavaScript libraries before settling on one that balanced bundle size, API quality, and customizability. The key requirements were: smooth animation on data updates, good mobile touch interaction for pinch-to-zoom on time series, the ability to draw custom annotations (personal records, goal thresholds, notable events), and a clean aesthetic that fits the overall app design. The library’s data model also needed to align reasonably well with the normalized health data schema to avoid excessive transformation on every render.

The weekly summary component is the most design-intensive part of the extension. The challenge is information density — there’s a lot to say about a week of health data, but a good summary should be scannable in thirty seconds. The design uses a combination of sparklines (tiny inline charts for trend direction), color coding (green/yellow/red for performance relative to goals), and a single highlighted “insight of the week” that calls out the most notable pattern. The ordering of the sections reflects decreasing importance: sleep and recovery first (because they affect everything else), then training load, then nutrition, then step count.

Goal tracking introduced an interesting data modeling question: what is a health goal, exactly? Goals have a target value, a metric, a time period, and a direction (higher is better, lower is better, or stay within a range). They might be weekly targets, monthly targets, or ongoing. And they need to coexist with historical data that was recorded before the goal existed. The schema I landed on treats goals as time-range annotations on metrics, which means the chart layer can shade goal periods differently and the summary layer can calculate progress correctly regardless of when the goal was set.

WW Food Tracker: Multimodal AI Agents for Nutrition Logging

2026-02-22T00:00:00+00:00

Manual food tracking is tedious. You have to look up every ingredient, estimate portion sizes, and enter everything by hand — which is exactly why most people stop doing it after a few days. The WW Food Tracker takes a different approach: take a screenshot of your meal (from a food delivery app, a recipe page, a restaurant menu, or even a photo of your plate), and let an AI agent do the analysis.

The pipeline starts with a vision model that receives the screenshot and returns a structured description of what’s visible: ingredients, portion estimates, preparation method. This unstructured description is then passed through a second step that converts it to a normalized JSON schema: each food item, estimated quantity in grams, and macronutrient estimates. The JSON output is then fed into a skill runner — a lightweight executor that can apply domain-specific logic on top of the structured data, such as calculating Weight Watchers points, comparing against daily goals, or flagging items that exceed a user-defined threshold.

The skill pipeline pattern is what makes this more than a one-shot prompt. Each skill is a small, focused function that takes the normalized JSON and produces a specific output. Skills are composable: you can chain them, run them in parallel, or conditionally activate them based on the content of the previous step. This is a practical implementation of the “tool use” pattern that modern AI agents rely on, applied to a concrete domain.

What I find most interesting about this project from a technical standpoint is how much the quality of the JSON normalization step matters. Vision models are good at describing food, but the structured output needs to be consistent enough for downstream skills to process reliably. Small prompt engineering decisions — how you define the schema, what examples you provide, how you handle ambiguous cases — have a disproportionate effect on the end-to-end quality. Multimodal AI agents are powerful, but the data normalization layer is where most of the real engineering effort lives.

Building an AI-Powered Health Tracker

2026-02-22T00:00:00+00:00

Health data is everywhere and nowhere at the same time. Fitness apps track your workouts, step counters track your movement, nutrition apps track your food, sleep trackers track your recovery — and none of them talk to each other in any meaningful way. The AI health tracker I’ve been building is an attempt to aggregate all of this into a single view and then apply an LLM to generate insights that go beyond what any single data source can provide.

The architecture is a full-stack JavaScript application: a backend API that connects to various data sources, a normalization layer that translates heterogeneous health data into a consistent schema, a storage layer for historical data, and a frontend that displays aggregated metrics and surfaces AI-generated summaries. The data aggregation is the hardest part — every source has a different API, a different data model, and different refresh rates. Building adapters for each source while keeping the core data model stable requires careful interface design.

The LLM integration sits on top of the normalized data layer. Rather than dumping raw numbers into a prompt, the system pre-computes meaningful derived metrics — weekly trends, personal records, recovery load estimates — and provides those as structured context alongside the raw data. The model is then prompted to act as a knowledgeable fitness coach, synthesizing across all data dimensions to produce a weekly summary: what went well, what the data suggests about recovery and readiness, and specific recommendations for the coming week.

What I’ve found technically interesting is the challenge of making LLM outputs trustworthy for health applications. The model needs to be grounded in the actual data rather than generating plausible-sounding advice that doesn’t reflect the user’s real metrics. Prompt engineering for factual grounding — explicitly instructing the model to reference specific data points and not to make claims beyond what the data supports — makes a meaningful difference in output quality. The combination of good data aggregation and careful prompting produces recommendations that feel genuinely personalized rather than generic.

Agent Lyfta: An AI Personal Trainer Powered by Your Workout Data

2026-02-22T00:00:00+00:00

Lyfta is a solid workout tracking app, but like most fitness apps, it keeps your data locked behind a mobile UI. The moment I found out there was an API, I wanted to do something more interesting with the data than just look at charts in the app. The result is a small Python project that fetches workout history from the Lyfta API and feeds it into an AI agent acting as a personal trainer.

The data pipeline is straightforward: authenticate against the Lyfta API, fetch recent workout sessions, normalize the JSON response into a consistent structure (exercise name, sets, reps, weight, date), and hand it over to the agent. The agent receives the workout history as context and is prompted to act as an experienced personal trainer who has been following your progress. It can identify plateaus, note progressive overload patterns, flag imbalances between muscle groups, and suggest adjustments for the next session.

What makes this interesting architecturally is the difference between a simple API call and an actual agent. A naive implementation would just dump the JSON into a prompt and ask “what should I do next week?” The agent approach is more nuanced: it uses tool calls to query specific time ranges, compare current performance to historical bests, and cross-reference exercises that target similar muscle groups. The agent builds its answer iteratively rather than in a single pass, which produces noticeably more coherent recommendations.

The broader concept here — AI agents applied to personal health tracking — has real potential. Your health data already exists in various apps and wearables, but it’s fragmented and none of those apps have the reasoning capacity to synthesize it meaningfully. An agent layer that can pull from multiple data sources (workouts, steps, sleep, nutrition) and reason about them together would be genuinely useful. This project is a small proof of concept in that direction, scoped to just the workout side, but the pattern scales.

Forking OpenCode: How Terminal-Based AI Coding Agents Work

2026-02-13T00:00:00+00:00

OpenCode is an open-source AI coding agent that runs in your terminal. Unlike IDE plugins or browser-based tools, it operates directly on your filesystem, reads your code, and uses tool calls — file reads, writes, shell execution, grep — to complete tasks autonomously. When I discovered the project, I forked it to experiment with modifications and to better understand how it works from the inside.

The architecture of a terminal-based coding agent is worth understanding. At its core, it’s a loop: receive a task, reason about the next step, call a tool, observe the result, repeat until done. The “tools” are just functions the model is allowed to invoke — read a file, write a file, run a shell command, search for a pattern. The model decides which tools to call and in what order. The TypeScript codebase is clean and well-structured, which makes it a good project to learn from if you’re curious about agent implementation details.

What makes OpenCode interesting compared to similar tools is the focus on transparency and control. Every tool call is visible in the terminal, every file change is tracked, and the agent explains its reasoning as it works. This makes it much easier to catch mistakes and course-correct than tools that operate more opaquely. The conversation history also stays local — no data is sent to a third-party service beyond the API calls to the LLM provider you configure.

My fork is primarily a place to experiment — testing prompt modifications, adding tools, exploring how the agent handles edge cases. If you’re interested in AI agent internals or want a coding assistant that runs entirely in your terminal without a GUI, OpenCode is worth looking at. The TypeScript codebase is approachable and the project is actively developed.

Rebuilding My Personal Site as a Configurable Digital Card

2026-01-30T00:00:00+00:00

Personal websites have a tendency to get stale. You build something, it looks good for a while, and then a year later the tech stack feels dated, the content is out of sync with reality, and updating it feels like more work than it’s worth. I wanted to break that cycle by building something that’s genuinely easy to keep current — a digital business card for weisser.dev that’s configurable through a single JSON file.

The stack is TypeScript and React, deployed as a static site. The entire content model — name, tagline, links, skills, contact info — lives in a typed configuration object. Updating the site means editing JSON, not touching components. This might sound like over-engineering for a single-person site, but it’s made a real difference in practice: I’ve updated the content several times since launch without touching a single component file.

Multilingual support was a deliberate design decision. German and English content are both first-class, and the language toggle is persistent across sessions. For a developer based in Germany working on both local and international projects, having both languages available isn’t a vanity feature — it’s actually useful. The implementation uses a simple context-based i18n approach without a heavy library, since the vocabulary is small and the switching logic is trivial.

Dark mode is implemented via CSS custom properties that respond to the system preference, with a manual toggle that overrides it and saves to localStorage. The design system underneath is minimal: a handful of color tokens, a type scale, and a grid. Nothing that requires a build step to reason about. The result is a site that loads instantly, works without JavaScript for the basic content, and is trivially forkable if someone else wants to use it as a starting point — which is part of why it’s public.

A Multilingual, Configurable Resume App in TypeScript

2026-01-30T00:00:00+00:00

There’s a category of developer who has built their own resume app, and I’ve become one of them. The practical motivation was concrete: I work in a bilingual professional context, maintain separate German and English versions of my CV, and found the update-and-keep-in-sync workflow between two documents genuinely painful. A single TypeScript application with locale-switching solves the problem by making both languages first-class, not afterthoughts.

The content model is fully JSON-driven. Personal information, professional experience, education, skills, certifications, publications, and languages all live in a typed TypeScript configuration object. Each text field that differs between locales holds a locale map rather than a string. The React components are locale-aware: they receive the active locale from context and render the appropriate string. Adding a new locale is a matter of adding keys to the configuration — the component layer doesn’t need to change.

Automatic theme detection uses window.matchMedia('(prefers-color-scheme: dark)') with a listener that updates the theme when the system preference changes. A manual toggle overrides the automatic detection and stores the preference in localStorage. The CSS is custom properties-based — the entire theme is a handful of color tokens applied to the :root, and switching themes is a single class change on <html>. This approach is simpler and faster than a styled-components theme or a CSS-in-JS solution for a project with a clear, constrained color system.

The question of why build your own CV app rather than use a template is worth addressing directly. The answer isn’t that the technology is impressive (it isn’t) or that it takes less time than a Word document (it doesn’t, initially). The answer is maintainability over time. Once the app is built, updating the content is fast and reliable, the output is consistent across locales, the print stylesheet works, and adding a section or field takes minutes rather than reformatting a document. For a CV you intend to keep current for years, that ongoing maintenance cost difference is worth the upfront investment.