Operational graph
Reticle starts with an intentionally authored infrastructure diagram. The YAML defines the systems, relationships, notes, checks, and known actions that belong in the operating model. Current observations connect that model to real systems.
The shared core assembles the configured topology and current observations into one graph snapshot. The canvas is the primary interface; JSON and read-only MCP provide machine-readable views of the same data.
For a walkthrough of the UI, start with checks and named actions.
Snapshot schema#
Every snapshot contains:
nodes: normalized infrastructure entities with stable IDs and display dataedges: directed relationships between nodessignals: timestamped observations associated with nodescollectors: collector state, detail, duration, and collection timeactions: non-executable names, kinds, validated targets, and policy for server-resolved named actionsgeneratedAt: when this snapshot was assembled
schemaVersion describes the graph contract; version comes from the topology.
nodes, edges, signals, and actions are ID-keyed objects; collectors is an
array. Generated observation timestamps use Unix seconds. Group health rollups
are a frontend presentation and are not additional signals in this response.
Executable scripts, interpreters, custom command text, and arbitrary
arguments are never included in graph snapshots. Legacy node-level actions
and crons are intentionally omitted.
Configuration#
The first topology collector reads the local YAML file. Reticle supports HTTP
checks and two fixed, read-only SSH probes: host.uptime and
service.status. SSH uses the local OpenSSH configuration and non-interactive
authentication, but the remote account should still be restricted to the
minimum commands it needs.
Reticle can additionally permit persisted remote ssh.command and local
shell.command checks. New UI definitions default to enabled and viewer-visible;
Desktop uses one global privileged toggle for the active workspace, with no
per-check acknowledgment, while Team requires the daemon
operator's --allow-custom-commands flag and editor authorization. This
privileged mode can turn precise shell diagnostics into repeatable graph signals,
but the commands are arbitrary and cannot be guaranteed read-only. Restricted
SSH principals and a dedicated, least-privileged Reticle OS account are the
actual security boundaries.
version: 1
nodes:
api:
kind: app
title: API
x: 80
y: 80
spec: { host: api.internal, port: 22, user: reticle-probe }
edges: {}
collectors:
- id: api-http
nodeId: api
name: API health endpoint
kind: http
url: https://api.internal/healthz
status: 2xx
jq: '.status == "ok"'
timeoutSeconds: 8
- id: api-service
nodeId: api
name: API systemd unit
kind: ssh
probe: service.status
service: api.service
timeoutSeconds: 10
# WARNING: arbitrary remote command; restrict the SSH principal.
- id: api-release-check
nodeId: api
name: Verify deployed release
kind: ssh
probe: ssh.command
command: /usr/local/libexec/reticle-check release
enabled: false
publishOutput: false
timeoutSeconds: 10
# WARNING: runs on the Reticle host with its OS permissions and environment.
- id: api-json-check
nodeId: api
name: Verify API response
kind: local
probe: shell.command
command: curl -fsS https://api.internal/healthz | jq -e '.status == "ok"'
enabled: false
publishOutput: false
timeoutSeconds: 10
actions:
- id: diagnose-api
nodeId: api
name: Diagnose API
kind: ssh.command
command: curl -fsS http://127.0.0.1:8080/healthz | jq -e '.status == "ok"'
requiresSignal: api-service
requiresState: err
requiresApproval: true
timeoutSeconds: 20Named actions support persisted ssh.command and local shell.command
definitions. Timeouts default to 20 seconds and must stay within 1–120 seconds.
Optional precondition signals are collected again before execution, approval is
required by default, and daemon attempts are
written to the configured audit log. Team callers submit only an action ID,
expected configuration revision, and approval decision; command text remains in
persisted configuration.
Before a custom check executes, Team validates its persisted definition and
bounds its timeout. Remote SSH commands receive no PTY or stdin. Local commands
run through non-interactive Bash with pipefail, so curl -fsS ... | jq -e ...
reports failure when either side fails. Viewers cannot see command text, manage
definitions, or run checks; command text is omitted from graph responses and
audit logs. Custom checks are never viewer-graph API, MCP, chat, or one-off
ad-hoc tools.
API#
Desktop and WebSocket clients call get_operational_graph. The OSS desktop can
also expose the same snapshot over an opt-in loopback server:
RETICLE_DESKTOP_HTTP_PORT=8786 go tool wails3 task dev
curl http://127.0.0.1:8786/api/graphThe listener is disabled when the environment variable is absent, always binds
127.0.0.1, limits request bodies and concurrent collections, follows desktop
workspace switches, and has no mutation or action route. It has no token
authentication; local processes with access to that port can read the graph.
Desktop API and MCP reads collect fixed checks with custom commands disabled, regardless of workspace trust. They can therefore differ from a trusted Desktop window's custom signals and action availability. Team API and MCP reads use the daemon cache, including any custom results collected under daemon policy.
The paid Team Daemon serves the shared snapshot at
GET /api/graph:
curl --header "Authorization: Bearer $RETICLE_VIEW_TOKEN" \
https://reticle.example.com/api/graphAuthentication follows the daemon role rules. Both viewer and editor roles may read the graph. Only editors may request a named action.
MCP#
Desktop and daemon expose a JSON-RPC request/response endpoint at POST /mcp.
They advertise MCP protocol version 2025-03-26. This is a minimal HTTP
implementation: JSON responses, no SSE stream, sessions, resources, or prompts.
Use a client that supports this transport subset. Both expose read-only tools:
reticle_get_graphreticle_get_nodewith anidargument
The daemon additionally provides reticle_get_signal_history. The desktop
does not retain history because its lifecycle belongs to one local session.
To list tools on an enabled Desktop server:
curl --header 'Content-Type: application/json' \
--data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
http://127.0.0.1:8786/mcpFor Team, use the daemon's /mcp URL and a bearer header. reticle_get_node
requires an id. Team's reticle_get_signal_history requires signalId and
optionally accepts since (Unix seconds) and limit (1–1,000, default 100).
The HTTP history route additionally supports a nodeId filter.
There is deliberately no MCP action tool. MCP can inspect topology and signals, but action execution remains an explicit human workflow. Custom command checks are never MCP tools.
Optional chat lens#
The optional in-app chat panel reads the current graph and cannot change it. It
supports OpenAI's official chat-completions endpoint and
Ollama on localhost or a literal loopback IP. Its only tools are
reticle_get_graph, reticle_get_node, and, on the daemon,
reticle_get_signal_history. It has no action, command, shell, save, or MCP
mutation tool. Requests have bounded time and tool rounds, and HTTP redirects
are disabled.
Provider credentials and endpoints are request-scoped and never written to configuration or logs. With OpenAI, the provider receives the question and any graph data returned by a tool call. Ollama requests remain on the machine running Reticle: the desktop host for the desktop app and the daemon host for the Team Daemon. Optional daemon chat requires the editor role; audit records contain only provider and model, not prompts, answers, credentials, graph data, or signal history. It provides no arbitrary shell access. See optional chat for setup and the per-question context model.
Current limits#
Reticle does not automatically enumerate the environment or import every runtime resource, and it is not an autonomous remediation system. Desktop checks run when its graph is requested; the app window does so at startup and every 30 seconds while running. The daemon collects immediately and on a 30-second schedule, keeps a bounded transient in-memory observation ring, and invalidates its cache after topology changes. Unchanged signals are deduplicated. Observations reset when the daemon restarts or editable operations are saved and are not durable history. Reticle complements metrics and tracing systems; it does not replace them.