Agentic-OS/docs/operator-guide.md

Operator Guide

This guide explains how an operator uses Agentic OS day to day.

Dashboard

The dashboard at / is the operations view. Use it to answer:

• What is running now?
• What needs approval or attention?
• Were recent tasks saved to memory and Obsidian?
• Are cloud model balances healthy?
• Are MCP servers loaded?

Main sections:

• Active Tasks: queued, running, and waiting approval tasks.
• Attention Needed: failed tasks, pending approvals, Obsidian push failures, and low/errored API balances.
• Recent Findings: compact summaries of completed reports.
• Budgets: OpenRouter, DeepSeek, and other configured cloud balances.
• Platform Readiness: MCP server status and tool counts.

Inventory

Inventory describes vessels and onboard devices.

1. Open /inventory.
2. Create or edit a vessel with public IP/site notes.
3. Enable device slots such as proxmox, pfsense, docker_vm, asterisk_geneseasx, fortigate, or fortiswitch.
4. Add address, port, username, and secret only when they differ from environment defaults.

Secrets are encrypted before being stored. Do not put plaintext credentials in vessel notes.

Creating a Task

1. Open /tasks.
2. Select New task.
3. Pick a quick template or enter a title and issue manually.
4. Select the vessel.
5. Review What will be checked.
6. Choose:
   • Create & watch live to go to the task page.
   • Run in background to return to the dashboard.

The preview is important: it shows which devices and check groups the agent will run. If the preview says no devices match, rewrite the issue with explicit device names or ask for a full stack health check.

Example issue text:

check status of proxmox and pfsense

Expected preview:

• Proxmox: VM/LXC status, guest configuration, host health.
• pfSense: system status, interfaces, gateways, firewall/NAT when requested.

Understanding Live Status

The task page shows the run as phases:

1. Context — searching prior memory and Obsidian notes.
2. Plan — deciding scope and diagnostic approach.
3. Connect — connecting to MCP/device targets.
4. Diagnose — running checks.
5. Analyze — reasoning about results.
6. Report — writing final report and artifacts.

The timeline is intentionally concise. Expand command or evidence details only when you need raw output.

Approvals

Some actions require approval:

• MCP source patches proposed by MCP development.
• Config-changing tool calls.
• Git pushes for generated MCP changes when auto-push is disabled.

When a task enters waiting_approval, open it and review the approval card. Approve only if the proposed change matches the intended fix and the risk is acceptable.

Reports

Reports are structured to be readable first and evidential second.

Default sections:

• Scope: what was requested and what was actually checked.
• Report: summary, scope checked, findings, recommendations.
• Evidence: collapsed per-tool output and formatted tables.
• Saved Artifacts: memory ID, Obsidian path, push status.
• Models & Cost: LLM routing and cost summary.
• Run History: follow-up runs on the same task.

Important rule: a report should not imply a device was checked if it was not in scope_checked or devices_checked.

Continuing or Restarting Tasks

Use Continue investigation when the first run is incomplete or you want targeted follow-up checks. The agent receives prior findings and your follow-up note.

Use Restart from scratch when you want to discard run history and rerun the original task.

Use Stop task for stuck or no-longer-needed queued/running tasks.

Memory and Obsidian

At task completion:

• Project memory receives a durable summary under MEMORY_TASK_PROJECT_ID.
• Obsidian receives a markdown note under OBSIDIAN_TASKS_FOLDER.
• The task report shows IDs/paths and push errors if any.

If Obsidian push fails, the note may still exist in the backend runtime vault clone. Fix git/reachability and rerun or inspect logs before assuming the report was lost.

Rules and Skills

Rules and skills guide the agent.

• /rules: controls device selection, priority, severity hints, and standard checklist hints.
• /skills: adds deeper procedures for known scenarios such as VoIP, DNS/captive portal, or safe pfSense changes.

Use rules for which devices to check. Use skills for how to investigate a class of problem.

MCP Page

Use /mcp to inspect MCP server health, tools, reload/upgrade servers, or trigger controlled development for MCP bugs.

If a tool fails because of infrastructure permissions, fix the target system. If a tool fails because the MCP is missing a capability or has a code exception, MCP development may propose a patch.