Reticle/ Docs Get Desktop
Documentation/Connect and operate
On this page

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 data
  • edges: directed relationships between nodes
  • signals: timestamped observations associated with nodes
  • collectors: collector state, detail, duration, and collection time
  • actions: non-executable names, kinds, validated targets, and policy for server-resolved named actions
  • generatedAt: 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.

yaml
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: 20

Named 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:

sh
RETICLE_DESKTOP_HTTP_PORT=8786 go tool wails3 task dev
curl http://127.0.0.1:8786/api/graph

The 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:

sh
curl --header "Authorization: Bearer $RETICLE_VIEW_TOKEN" \
  https://reticle.example.com/api/graph

Authentication 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_graph
  • reticle_get_node with an id argument

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:

sh
curl --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  http://127.0.0.1:8786/mcp

For 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.

View Markdown Report a docs issue
Reticle documentationDraw intentionally. Operate with context.

↑ ↓ to move · Enter to open · Esc to close