# 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](checks-and-actions.md).

## 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](https://reticle.live/team/) 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](https://reticle.live/team/). 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](chat.md) 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.
