Host facts

Each time you connect, Gatesys SSH reads a fixed set of read-only facts about the host and tells you what changed since you were last there. Nothing is installed on the server, and no model is involved in reading or comparing.

What gets read #

About a second and a half after a connection’s first terminal opens, the app reads:

• OS, kernel, boot time, init system and package manager
• The versions of about thirty well-known packages, and recent package installs and upgrades
• Failed systemd units
• Listening TCP ports
• Disk use
• Docker containers: the running ones and up to 20 stopped, with their image, state, compose project, published ports, restart count and health
• Files under /etc changed in the last two weeks
• Crontab checksums
• Recent out-of-memory kills
• With the service map on: the host’s own addresses and a count of its TCP connections

Login history (last) is deliberately not read.

How the read runs #

• A fixed list of read-only commands, each with the reason it runs. Nothing in it is ever built from a prompt, a model’s reply or anything the server sent.
• On its own channel, as env LC_ALL=C LANG=C sh -s with the script on standard input, so it is never typed into your shell or its history.
• As your own login, with no sudo.
• Bounded: each check has a 5-second limit and a 16 KB cap, the /etc walk runs under nice and ionice, and the whole read stops at 20 seconds or 256 KB.
• Visible to the server’s monitoring: session logs, auditd or an EDR will see a short sh -s process tree.

It never costs you a terminal: it waits behind the metrics sample on the same background channel, and on a server that allows only one session it hands the channel back as soon as a terminal needs it.

To see every command with its reason, click What runs? in the terminal’s facts strip, or open Settings › Hosts › Host facts › Show the exact probe commands.

When it does not run #

The read runs once per connect and at most every ten minutes per host. It does not run at all:

• With metrics polling off (Settings › Hosts › Monitoring › Metrics polling set to 0).
• On a server that refused the metrics sample a channel.
• On a host that opted out: host editor › Advanced › Remember facts about this host.
• With Settings › Hosts › Host facts › Remember host facts off.

On a production host, the strip asks once before the first read: Read facts on db-primary? with Read facts or Not on this host. Turn this off with Ask before reading a production host.

Meet this host and Since you were last here #

A slim strip between the terminal header and its tabs shows the result:

1. Reading host facts… while the read runs.
2. On a first visit, Meet this host: OS, init system, package manager, containers, ports and disk.
3. After a gap, Since you were last here: up to six chips of what changed, worst first. A failed unit is red.

Only notable changes raise the strip. A batch of library upgrades or your own upload waits on the Hosts card instead.

Click a chip to see the change’s before and after, when it happened and what said so. From there:

• Look closer offers read-only commands for that kind of change, from a fixed catalog. They reach the terminal only when you pick Insert or Run. There is no Look closer when the catalog has nothing that fits.
• Ask Farabi puts a question about the change in Farabi’s composer and opens the panel if it is folded (Pro).
• Dismiss hides it, and the app remembers.

How changes are compared #

Changes are compared section by section, with the noise taken out:

• Sixteen libraries from one unattended-upgrades run are one line.
• Ephemeral loopback ports, disk moves under five points and known churn under /etc are ignored.
• A different machine answering under the same name is reported as such.
• A check this login may not run (no docker group, no kernel log access) is reported as not visible, never as everything having gone.

What you did through the app since the last visit (uploads, external edits, snippets, Farabi runs) is joined in from the audit log, so you can tell your own changes from someone else’s.

The Host dossier #

In the Hosts view, a host that has been read gets a Host dossier card. Its header says how many facts are kept and when the host was read. Refresh reads it again now, and Forget this host deletes what is kept, after asking.

The card opens on an overview, with the facts behind it in sections below.

The overview #

First comes the system in one line: the OS, then the kernel, the architecture, the init system, the package manager and how long the host has been up. Under it, a row of tiles. Click one to open its section.

A tile turns amber or red when it needs a look, and says Attention, or High or Critical for the disk.

Sections #

Below the overview, the facts sit in six sections, one showing at a time: System, Services, Network, Storage, Containers and Notes. Each section’s tab shows how many rows it holds, and a dot when something in it needs attention. The card opens on the worst section, or on System when all is well. The arrow keys move between the tabs.

A check this login could not run is said as such, for example that docker is not visible to this login, never shown as an empty list.

Long lists #

A list never makes the page longer than it needs to be:

• It shows its seven most urgent rows first: failed, restarting or unhealthy first, then what is new since the read before, marked with a dot.
• Show all opens the rest in a scroll box under a header that stays in place. Show fewer closes it.
• A list of more than ten rows gets a filter, such as Filter 42 listeners.

The containers table #

The Containers section is a table: the name, the image (a long one is cut in the middle), the state, such as running, healthy, unhealthy, restarting or exited, the restart count and the published ports.

Opened with Show all, the table groups containers by compose project when at least two carry one. Groups with trouble come first; click a group’s name to fold it. Containers that compose did not start close the list, under Not in a compose project.

Pin, hide and notes #

• Each row says where the fact came from, probe, you or AI-confirmed, and how old it is. A measurement past its age limit reads stale.
• Pin a fact to the top of its list. Hide a measured fact until its value changes. Delete a note of your own.

Since you were last here #

Beside the dossier, the Since you were last here card lists what changed, grouped by day, and marks what you did through the app. It shows the eight most notable changes, warnings first, with Show all for the rest. An amber dot in the host list marks a warning you have not seen, and Mark as seen clears it.

When the host is not connected, the dossier shows what the host was at its last read, marked Last known, instead of an empty card.

Explain changes #

With Pro and the assistant on, Explain ranks the changes against what you are seeing. Open it from the strip, from the starter prompt What changed since last visit?, or from the palette (Explain changes on db-primary).

1. Describe the symptom in one line. It is prefilled with a failing unit when there is one.
2. Explain ranks the changes, citing each one as its own chip.

The model gets the numbered list of changes and your one-line symptom, and nothing else: not the host facts, not the terminal. It may only answer in lines that cite those numbers, at most four. A line citing anything else is dropped and counted in the footer, and no command survives. With no model or no usable answer, the same list is ranked by timing instead, and the card says so: coincidence in time, not proof of cause.

Service map #

The service map shows which of your saved hosts talk to which. It comes from two more sections of the same read, with no extra channel, login or process pattern. Turn it on or off with Settings › Hosts › Host facts › Map connections between hosts.

What it runs #

The counting is one streaming awk pass on the server, so a host with forty thousand connections still prints at most 200 counts, busiest first. No process names, no sudo, no redirect. A host without ss is reported as not visible, never as quiet.

The Connections card #

In the Hosts view, the Connections card shows Talks to and Called by, grouped by port with one sentence each, for example 1 known host and 1 other address held connections to :6379. Called by shows its first five ports, with Show all for the rest. The card shows how recent each row is, and a footer says what was counted, when, and that it is TCP only: container, unix-socket and UDP traffic is not counted.

How addresses are matched #

• No DNS. A peer address is tied to a saved host by what Gatesys SSH knows (a host configured by IP, the address its own socket reached) and by what hosts said about themselves. A configured or dialled address beats a host’s own claim, and the card shows the conflict.
• Network zones. Private addresses count only inside the network the observer sits in, so two clouds’ 172.31.0.10 never mix. A match from another network is shown as a maybe and never counted.
• Your own traffic is taken off first: Gatesys SSH’s own session, the hops of chains through a host, and the tunnels it carries.
• A look checks itself. It counts only when it saw Gatesys SSH’s own connection among the sockets. A look that could not see every connection says so, and nothing is shown as gone because of it.

The map is also what lets Farabi say who a restart would cut off. See Farabi.

Where facts are kept #

• Host facts live in dossiers.v1 beside the app’s config, sealed as one AES-256-GCM blob under the same vault key as saved passwords, mode 0600. The machine id is kept only as a salted hash and cron only as checksums, with at most three snapshots per machine.
• The service map lives in topology.v1, sealed the same way, and forgets edges unseen for 30 days. No address of this computer or of an internet caller is kept; internet callers are one count per port.
• Forgetting: deleting a host deletes its facts. Forget this host on the dossier forgets one; Settings › Hosts › Host facts › Forget all host dossiers forgets every host’s.
• The record: every read is written to the audit log with how long it took and which checks were not visible.

Settings #

Facts in Farabi’s prompts #

With Send host context and Include host facts in prompts on, each question to Farabi carries a short Host facts block of about 300 tokens: OS, kernel, init system, package manager, notable versions, failed units, containers, listening port numbers, disk use, your own notes, and one line of what changed.

It is built from an allowlist. Machine and boot ids, bind addresses, hashes and /etc paths never go, measurements older than 14 days are dropped, and secrets are masked. Every server string in it is flattened onto one short line, and the block is labelled as data. When the prompt leaves this computer, IP addresses, emails and logins, fingerprints, host names and image registry hosts are removed too. The facts · N pill beside the model name shows the exact block.

With Include neighbours in prompts on as well, a short Neighbours block lists saved hosts’ names, port numbers, well-known service names and counts seen in the last day. It never includes a name a container chose, an internet address or a host that opted out of facts. A model off this computer gets no addresses and every host as a placeholder (‹H1›), swapped back before you read the answer. The neighbours · N pill shows the exact block.