The Knowledge Base

Portoser keeps a small, file-based knowledge base of every problem it has resolved. The KB lives at ~/.portoser/knowledge/ on the machine running the orchestrator (typically your control-plane host or laptop).

Reading the KB from the CLI: portoser learn summary, learn playbooks, and per-service learn insights.

Layout

~/.portoser/knowledge/
├── playbooks/                 # one Markdown file per recorded resolution
│   ├── port_conflict_2026-04-15.md
│   ├── stale_process_2026-04-22.md
│   └── ...
├── patterns_history/          # JSON event log of all solved problems
│   ├── 2026-04-15.jsonl
│   └── 2026-04-22.jsonl
└── problem_frequency.txt      # tally of fingerprint → count

This is intentionally not a database. Three reasons:

  1. You can grep it.
  2. You can put it in git if you want shared cluster memory across machines.
  3. There is no migration to do when Portoser upgrades.

How it gets populated

The standardize phase of the self-healing loop writes a playbook each time the solve phase succeeds. A playbook captures:

  • The problem fingerprint that matched
  • The observations that triggered it
  • The pattern that was applied
  • Whether the deploy succeeded after retry

How it gets used

Two places read the KB:

  • The solver — when a known fingerprint reappears, it tries the recorded pattern first.
  • The Knowledge Base UI (/knowledge in the web UI) — shows playbooks grouped by service, with a per-service insights panel.

Frequency map

problem_frequency.txt is a flat tally of fingerprint counts. It is the most valuable file in the KB — recurring entries usually mean a real configuration bug worth fixing, not a problem to keep auto-recovering from.

Read it with:

portoser knowledge playbooks --frequency

Sharing across hosts

For multi-operator clusters, commit the entire ~/.portoser/knowledge/ directory to a git repo and clone it on each operator's machine. Portoser does not enforce a sync mechanism — that's deliberate. Treat the KB as documentation, not a runtime dependency.

Privacy

Playbooks may contain hostnames, ports, and service names. They do not contain secret values; the solver redacts known secret-shaped strings before writing. Inspect a playbook before sharing it externally.