129 lines
4.7 KiB
Markdown
129 lines
4.7 KiB
Markdown
# 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:
|
|
|
|
```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.
|
|
|