Farabi

Farabi is the assistant beside every terminal. It answers questions about the host you are connected to, using facts the app measured there, and suggests commands that reach your shell only when you click.

What makes Farabi different #

• Measured first. Hop Doctor’s checks, the host’s facts and what changed since your last visit come from fixed read-only commands, rules and diffs, with no model involved. They are the ground truth, and they work with the assistant off or no model installed.
• It cites its evidence. The model ranks, explains and phrases; it does not decide. The facts in its prompt are labelled as data measured on the server, with their ages. How risky a suggested command is gets rated on this computer, from its text, never by the model.
• Nothing is installed on the host. What the app learns, it reads over the SSH session you opened, as your own login. No agent, no daemon, no file written on the server.
• It works through the jump chain. A host reached through two bastions is understood as well as one on your desk.

Open Farabi #

1. Connect a model first. See AI providers.
2. Open a terminal. Farabi’s panel starts folded: a slim Farabi tab on the terminal’s right edge, with the terminal at full width.
3. Show the panel with ⌘I (CtrlI on Windows and Linux), the Farabi button in the terminal’s tab row, or the slim tab. It stands to the right of the shell, and the terminal refits to the width left.
4. Fold it again with the same keys, the Farabi button, or the hide button in the panel’s header.
5. Drag the panel’s left edge to resize it, between 360 and 520 px. Double-click the edge to reset it.

A few things to know about the panel:

• It remembers. It starts folded until you open it. From then on, its width and whether you left it open or folded carry across sessions and launches.
• Folding keeps the conversation, even an answer that is still streaming.
• On a narrow window, below about 1100 px, the panel opens as a drawer over the terminal instead of squeezing it.
• Ask Farabi on a change in the host brief opens a folded panel and puts the question in the composer.
• Ask Farabi on a metric, a Health signal or a process opens a folded panel and asks at once. See Server health.
• Without Pro, with the assistant on, the Farabi button carries a Pro tag and the panel shows what Farabi does, with Get Pro.

The panel header #

Under them, pills show what every question carries:

• facts · N: how many measured lines of the Host facts block go with each question. Click it to read the exact block the current model would receive.
• neighbours · N: the same for the Neighbours block from the service map.
• skills · N: how many skills this conversation’s questions carry. Click it to turn skills on or off for this conversation. See Pick skills for a conversation.
• shield · on: the Injection Shield checks terminal output before each question. After a question it says how much it removed, such as shield · 2 removed, or output left out when the output was too large to check.

Pick a model and effort #

Each conversation can run on its own model. The picker lists the models of every provider saved in Settings › Farabi › Model, grouped by provider, with the default provider marked.

1. Click the model name in the panel’s header.
2. Pick a model. A provider that cannot answer now says why under its name, for example a missing API key.
3. If the model takes effort levels, pick one from the effort control beside it. Only the levels that model takes are offered, such as low, medium and high, or think off and think on. Default leaves it to the provider.

The choice belongs to this session’s panel:

• It lasts as long as the session. Folding the panel or switching tabs keeps it; a new session starts on the Settings default.
• Changing it keeps the conversation. Every answer is labelled with the model and effort that wrote it, such as qwen3:8b · think off, and with the skills that shaped it.
• Use the Settings default in the picker’s menu goes back to the default, which then follows Settings as it changes.
• Everything else, including Explain, watch and setup drafts, Safe Change drafts and Test this model, uses the default model and effort from Settings.

Picking between providers needs more than one in the list, and more than one provider is part of Pro. Without Pro, the picker offers the default provider only. The gear at the foot of the menu opens Settings › Farabi › Model to add or remove providers. See AI providers.

Ask a question #

When the conversation is empty, starter prompts above the composer make the first question a click: Explain the last error, What’s using disk?, Check listening ports and Recent failures. On a host that changed since your last visit, the fourth becomes What changed since last visit? and opens Explain (see Host facts).

1. Type in the composer and press Enter to send. ShiftEnter adds a line.
2. The answer streams in as the model writes it. A reasoning model’s thinking is stripped rather than shown.
3. Ask follow-ups; earlier turns are kept.
4. To cancel, click Stop or press Esc in the composer. Closing the terminal cancels too.

What Farabi knows about the host #

Every question carries the host’s display name. With Settings › Farabi › Privacy › Send host context to the model on (the default), it also carries:

Each block goes inside a fenced data block that the prompt declares as evidence, not instructions. The facts · N and neighbours · N pills in the panel’s header show the exact blocks the current model would receive.

Before anything is sent, the Injection Shield removes text you could not see, and secrets are masked. For exactly what goes where, see What runs on the server.

Your instructions and skills #

Every question goes with Farabi’s system prompt. It starts with a safety core you cannot change: commands only in sh blocks, nothing invented about hosts, paths or credentials, server text treated as evidence, and no tools. Below the core go two layers of your own:

• Your instructions: tone, level of detail and house rules, such as we use podman, not docker. You edit them in Settings › Farabi › Language and instructions, or in ~/.gatesys-ssh/farabi/system.md.
• Skills: guidance for one kind of work, such as Docker, nginx or a filling disk. Eleven are built in, and you can write your own. The host’s measured facts suggest the ones that fit.

See Instructions and skills.

Farabi’s language #

Farabi writes and asks in English, Türkçe (Turkish) or Português (Portuguese). Pick one in any of these places; they all change the same setting:

• The language chip in the panel’s header, which shows EN, TR or PT.
• Settings › Farabi › Language and instructions › Language.
• The Farabi step of the first-run setup.

Auto, the default, follows this computer’s language: Türkçe for a Turkish locale, Português for Brazilian or European Portuguese, and English otherwise. While the built-in Türkçe yanıt skill is on, Auto means Türkçe.

The language applies to everything a model writes for you: answers, Explain, Health insights and Safe Change summaries. It takes precedence over what your instructions say about language. The questions the app writes for you follow it too: the starter prompts, What changed since last visit? and Ask Farabi on a metric or a change. Commands, paths, flags, config keys and log lines stay exactly as they are, and Gatesys SSH’s own screens stay in English.

A small local model sometimes answers in English whatever it is told. When an answer is clearly in another language, a note under it says so, such as Answered in English, with Retry in Português. The app checks this by counting common words, never with a model, and it never holds the answer back.

In settings.json the setting is farabiLanguage: auto, en, tr or pt. See The settings file.

Insert vs Run #

Each suggested command is a card. A long command scrolls sideways rather than wrapping in the middle of a word, and the expand control shows it whole. The card carries its risk marker and these actions:

Insert and Run go through the main process, which accepts only a command Farabi itself produced, strips control characters from it, and writes it to the audit log with the host, the runtime and the model.

Neither types into a terminal that is showing a full-screen app such as vim, less or top. There every letter is a keystroke: in vim, ggdGZZ empties a file and saves it without any Return.

Command risk #

Every suggested command is rated on this computer, from its text, against a fixed set of rules, never by asking the model. A risky one carries a ! marker; hover it to see which rules matched, why, and a safer alternative.

A production host, a host two or more jumps away, or a root shell turns a danger into a critical. The rules read a command the way the shell would, through quotes, sudo, sh -c, ssh, docker exec and SQL inside psql or mysql, and rate hidden or fetched code at least danger. The main process rates the command again at Run and refuses one that was not confirmed.

Attacks such as reverse shells and the fork bomb show a Blocked pill instead of Run, Insert, Copy and + Snippet. Farabi never puts them in your shell.

Browse and test the rules, add your own and adjust the built-ins in Settings › Safety › Command risks. See Command safety.

Who a restart would cut off #

When Farabi suggests a command that stops or restarts a service (systemctl, service, docker stop, kill by name, a reboot, including through sudo, timeout, sh -c or ssh to a saved host), code works out the service’s ports and says who held connections to them at the last look, for example 3 known hosts held connections to :6379.

• When other hosts did so in the last day, Run asks first, in amber: Run anyway?
• Your yes is bound to that evidence. If the map has found another caller since, the app recomputes at Run and asks again.
• The model never writes, changes or hides this line. When code cannot tell, it says so: couldn’t tell which service this stops, or not visible from this login.

The line comes from the service map.

Commands that edit config files #

When Farabi suggests a command that edits a file under /etc in place (sed -i, tee, >), Open as Safe Change appears beside Run. The command is never run or interpreted. For an sshd file it opens Change with Farabi with the command as its sentence; for anything else it opens the editor with the command as a note. Run stays available. See Safe Change.

Tunnels in Farabi’s commands #

An ssh -L, -R or -D among Farabi’s commands gets a note: typed into this terminal it opens the tunnel on that server, not on this computer. Port forwarding › Describe a tunnel opens it here.

When Farabi cannot answer #

With no provider reachable, no model chosen or no API key saved, the panel says which and links to Settings. The terminal is unaffected. Embedding-only models are listed but cannot be picked as the chat model.

Turn the assistant off #

Settings › Farabi › Use the assistant is the master switch. Off:

• Farabi, both Explains, Ask Farabi on the host brief, the starter prompts, the palette entry, the instructions and skills cards and Test this model are hidden.
• Any model call in flight stops, and the main process refuses every model call, including the provider health check.
• Ask Farabi on a metric, a Health signal or a process opens the Health panel on the signals instead, with a note that they need no model.

These keep working, because they need no model: Hop Doctor’s checks and fixes, host facts and what changed, Look closer, Health’s signals and top processes, the command-risk rules, the service map’s Connections card, the terminal’s link and escape rules, watches and sentence-drafted tunnels and hosts (read by rules), and Safe Change without its Farabi parts. These are also the parts included in the Free plan. See Plans.