# Topology File Reference

A Reticle topology is one YAML document. The desktop app edits the opened file
in place, and the daemon reads the file it was started with. Canvas saves update
the visual topology while preserving top-level operational configuration.

For graph snapshots, signal behavior, APIs, MCP, and runtime limits, see the
[Operational graph](operational-graph.md).

```yaml
version: 1

nodes:
  prod-vpc:
    kind: vpc
    title: Production
    x: 40
    y: 20
    w: 680
    h: 360
  db-primary:
    kind: database
    title: Database
    x: 420
    y: 80
    w: 220
    h: 180
    parentId: prod-vpc
  web-01:
    id: web-01
    kind: server
    title: web-01
    subtitle: "nginx · 10.0.1.4"
    x: 120
    y: 80
    w: 220
    h: 120
    parentId: prod-vpc
    spec: { host: 10.0.1.4, port: 22, user: reticle-probe }
    notes: "Public web entry point"
    addons:
      - { kind: ram, label: "64G" }

edges:
  e1:
    id: e1
    kind: tcp
    label: "5432"
    from: web-01
    to: db-primary

collectors:
  - id: web-http
    nodeId: web-01
    name: Web health endpoint
    kind: http
    url: https://web.example.com/healthz
    status: 2xx
    jq: '.status == "ok"'
    timeoutSeconds: 8
  - id: web-uptime
    nodeId: web-01
    name: Web host uptime
    kind: ssh
    probe: host.uptime
    timeoutSeconds: 10
  # WARNING: ssh.command is an arbitrary remote command, not a read-only probe.
  # Team also requires --allow-custom-commands and editor authorization. Restrict
  # the SSH principal or use a remote forced-command policy. The false values
  # below intentionally override the UI defaults of true.
  - id: web-release-check
    nodeId: web-01
    name: Verify deployed release
    kind: ssh
    probe: ssh.command
    command: /usr/local/libexec/reticle-check release
    enabled: false
    publishOutput: false
    timeoutSeconds: 10

actions:
  - id: diagnose-web
    nodeId: web-01
    name: Diagnose nginx
    kind: ssh.command
    command: curl -fsS http://127.0.0.1/health | jq -e '.status == "ok"'
    requiresSignal: web-http
    requiresState: err
    requiresApproval: true
    timeoutSeconds: 20

groups: []
layers: []
```

## Nodes

Nodes are keyed by stable ID. The persisted visual fields are:

| Field | Type | Notes |
|---|---|---|
| `id` | string | Stable node ID. When present, it should match the map key. |
| `kind` | string | Card or boundary kind. Defaults to `server`. |
| `title` | string | Primary card text. Defaults to the node ID. |
| `subtitle` | string | Secondary card text. |
| `x`, `y` | number | Position in canvas world units. |
| `w`, `h` | number | Size in canvas world units. |
| `parentId` | string or null | Containing group node. Moving a group moves all descendants; cycles are rejected by the editor. |
| `spec` | object | Structured endpoint, Kubernetes identity, or Page URL metadata. |
| `notes` | string | Free text; a `note` node renders it as the card body. |
| `addons` | list | Visual resource facts shown as chips. |

Health displayed on cards is projected from current graph signals and is not a
persisted visual field.

### Node kinds

| Category | Kinds |
|---|---|
| Compute | `server`, `container`, `vm`, `app` (Application), `host` (group) |
| Data | `database`, `cache`, `queue`, `object-store` |
| Network | `load-balancer`, `switch`, `router`, `firewall`, `vpn`, `bastion`, `dns`, `cdn` |
| Kubernetes | `pod`, `daemonset`, `statefulset`, `deployment`, `cluster`, `knode`, `service`, `ingress`, `gateway` |
| Cloud groups | `vpc`, `region`, `zone`, `subnet`, `security-group` |
| Network groups | `lan`, `wan` |
| Misc | `generic`, `note`, `page`, `box` (group) |

Group kinds (`host`, `vpc`, `region`, `zone`, `subnet`, `security-group`,
`lan`, `wan`, and `box`) render as boundaries and contain nodes through
`parentId`.

### `spec`

SSH collectors and guarded named actions resolve their target from the
node's endpoint metadata:

```yaml
spec:
  host: 10.0.1.4
  port: 22                 # optional; defaults to 22
  user: reticle-probe
```

Use a least-privilege account and non-interactive authentication configured
through OpenSSH. Kubernetes identity metadata can remain on visual nodes:

```yaml
spec:
  kubeContext: prod
  namespace: web
  name: web
```

A `page` node embeds an HTTP(S) website in a sandboxed, resizable card:

```yaml
kind: page
spec:
  url: https://status.example.com/
```

The target may refuse framing through `X-Frame-Options` or CSP
`frame-ancestors`. Embedded pages run without same-origin access, top-level
navigation, popups, downloads, or device permissions. Remote content is not
captured in PDF exports; the Page title and URL are rendered instead.

## Collectors

`collectors` is a top-level list. Each collector has a unique `id`, references
an existing `nodeId`, and produces a signal for that node. `name` is optional;
`timeoutSeconds` defaults to 10 and must be between 1 and 120.

### HTTP probe

An HTTP collector performs a fixed GET request. It accepts `url`, an optional
`status` expression, and an optional `jq` predicate over the response body.
An omitted status accepts 2xx responses. Status expressions can be exact
(`"200"`), a family (`2xx`), a range (`200-204`), or a comma-separated list.
Quote an exact status in YAML: the field is a string, not a number.
HTTP checks require system `curl`, follow redirects, and limit response size to
1 MiB. Predicates additionally require `jq` and are evaluated with `jq -e`.

```yaml
- id: api-http
  nodeId: api
  name: API health endpoint
  kind: http
  url: https://api.example.com/healthz
  status: 2xx
  jq: '.status == "ok"'
  timeoutSeconds: 8
```

### SSH probes

An SSH collector uses the referenced node's `spec.host`, `spec.port`, and
`spec.user`. Only two fixed probes are supported:

| Probe | Additional field | Observation |
|---|---|---|
| `host.uptime` | none | Runs the fixed uptime probe. |
| `service.status` | `service` | Checks whether the validated systemd unit is active. |

```yaml
- id: api-service
  nodeId: api
  name: API systemd unit
  kind: ssh
  probe: service.status
  service: api.service
  timeoutSeconds: 10
```

Collector success produces `ok`; failure produces `err`. Nodes without a
collector have no collector-derived health signal.

### Custom command checks (gated)

`ssh.command` and local `shell.command` are persisted custom collectors for cases
the fixed probes cannot cover. New definitions created through the UI/API default
to enabled and publish bounded output to viewers. On Team, the daemon operator
must also pass `--allow-custom-commands`.
Direct YAML writers are trusted operators; enabled definitions written to disk
may execute while that flag is active. Desktop additionally requires
one global privileged-mode toggle for all checks and actions in the active
workspace; there is no per-check acknowledgment. Trust is session-scoped to the
selected workspace. The process-wide
`RETICLE_ALLOW_CUSTOM_COMMANDS=1` override is available for managed environments.
Local Bash checks are available only when Reticle itself runs on a Unix host.

```yaml
# WARNING: This is an arbitrary remote command and is not guaranteed read-only.
# Restrict the SSH principal or enforce an allowed command on the remote host.
- 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: This runs on the Reticle host with its OS account and environment.
- id: api-json-check
  nodeId: api
  name: Verify API JSON
  kind: local
  probe: shell.command
  command: |
    curl -fsS https://api.internal/healthz |
      jq -e '.status == "ok"'
  enabled: false
  publishOutput: false
  timeoutSeconds: 10
```

| Field | Type | Notes |
|---|---|---|
| `kind` | string | `ssh` executes remotely; `local` executes on the Reticle host. |
| `probe` | string | `ssh.command` for remote login-shell execution; `shell.command` for local Bash. |
| `command` | string | Required arbitrary command, up to 2048 bytes. Persisted in topology but omitted from graph responses and audit logs. |
| `enabled` | boolean | UI defaults to `true`. Omitted in YAML: `false` for custom checks, `true` for fixed checks. |
| `publishOutput` | boolean | UI defaults to `true` for custom checks. Omitted in YAML: `false`. Use `false` to keep stdout/stderr out of published signal detail. |
| `timeoutSeconds` | number | Defaults to 10; bounded from 1 through 120 seconds. |

The daemon validates the persisted definition before execution. `ssh.command`
runs on the node's SSH target without PTY or stdin. `shell.command` runs through
non-interactive Bash on the Reticle host with `pipefail`; this makes a pipeline
such as `curl -fsS URL | jq -e PREDICATE` fail for an HTTP, transport, or JSON
predicate error. One-off requests are not supported. Viewers cannot see command
text, manage definitions, or run custom checks on demand. Published results can
appear in Team graph API, MCP, and chat reads, but those reads do not execute a
custom check. Restricted SSH principals and a
dedicated, least-privileged Reticle OS account are the actual security boundaries.

## Guarded Actions

`actions` is a top-level list of persisted named commands. `ssh.command` runs
through the referenced node's SSH endpoint; `shell.command` runs through
non-interactive Bash on the Reticle host. Team requires
`--allow-custom-commands` before either kind can run.

| Field | Type | Notes |
|---|---|---|
| `id` | string | Unique action ID submitted by clients. |
| `nodeId` | string | Existing node that owns the action; also supplies the SSH endpoint for `ssh.command`. |
| `name` | string | Human-readable label. |
| `kind` | string | `ssh.command` or `shell.command`. |
| `command` | string | Required persisted command, up to 2048 bytes. Omitted from graph responses and audit logs. |
| `requiresSignal` | string | Optional collector signal precondition. |
| `requiresState` | string | Optional required state: `unknown`, `ok`, `warn`, or `err`. Defaults to `err` when `requiresSignal` is set. Requires `requiresSignal`. |
| `requiresApproval` | boolean | Defaults to `true`. |
| `timeoutSeconds` | number | Defaults to 20; must be between 1 and 120. |

When configured, the required signal is collected again before
the action runs. Team invocation requests contain only the action ID, expected
configuration revision, and approval decision, never command text. Approval
policy and daemon audit behavior are described in
[Operational graph](operational-graph.md).

The timeout bounds how long Reticle waits and collects output. A command that
deliberately detaches from its local process group or remote SSH session may
outlive that wait; production actions should use restricted wrappers, cgroups,
systemd scopes, containers, or equivalent server-side supervision when workload
termination must be guaranteed.

## Edges

Edges are keyed by stable ID and contain `id`, `kind`, optional `label`, and
`from`/`to` node IDs. An optional `port` value may carry additional display
metadata.

Edge kinds: `ethernet`, `tcp`, `udp`, `http`, `https`, `grpc`, `replication`,
`peering`, `tunnel`, `routes-to`, `mgmt`, `fanout`, `depends-on`, `custom`.

Each kind has a fixed visual style shared with the PDF export legend.

## Add-ons

Add-ons are visual facts attached to a node. They do not produce signals or
operations.

```yaml
addons:
  - { kind: gpu, label: "2x A100 80G" }
```

Kinds: `gpu`, `disk`, `ram`, `cpu`, `nic`, `ip`, `cert`, `ups`, `misc`.

`groups` and `layers` may remain at the document root for compatible visual
metadata. Current containment is represented by group-kind nodes and
`parentId`.

## Limits and round-tripping

Operational validation permits up to 256 collectors and 128 named actions. The
collector loop runs serially with a 120-second scheduling budget; slow or failed
checks can leave later collectors without a result in that pass. This is not a
guaranteed hard deadline for every subprocess or remote workload.

Canvas saves replace visual node/edge fields while preserving top-level
operational configuration. YAML comments and formatting are not preserved, and
unknown node/spec fields may be dropped after editing. Use supported fields for
data that must survive visual saves. See [workspaces](workspaces.md).
