By Manny Fernandez

November 18, 2026

iTerm2 Orchestration Chat: Let AI Drive Every Terminal Without Handing Over the Keys

iTerm2 Orchestration Chat: Let AI Drive Every Terminal Without Handing Over the Keys

No fluff. Just the config that works.

iTerm2 3.7 added a new kind of AI chat that does not live inside one tab. An iTerm2 orchestration chat can see all of your sessions and workgroups and operate iTerm2 on your behalf. That is powerful when you have a FortiGate console, two jump hosts, and a packet capture open at once. It is also every security engineer’s least favorite sentence: an AI that can read every terminal you have open. This post breaks down the permission model, how to grant control one session at a time, and how to run the whole thing on a local model so screen contents stay on your LAN.

Executive Summary

Item Detail
Objective Understand and lock down iTerm2 orchestration chat permissions, grant scoped control with @-mentions, and back the chat with a local Ollama model reachable only from your Mac.
Target audience Security and network engineers who keep production SSH sessions open in iTerm2 and want AI help without uncontrolled access.
Time to complete About 30 minutes, including the Ollama host.
Outcome An orchestration chat that can read and summarize, asks before it types, and only talks to a model you control.

The Three Kinds of iTerm2 AI Chat

The iTerm2 AI Chat documentation defines three chat kinds. You choose one when you create the chat, and you can change it later from the info button menu in the chat toolbar.

Chat kind What it can see Typical use
Unlinked Nothing. A private conversation with no access to your sessions. General questions, writing a one-liner
Linked One terminal session, one browser session, or one of each. Explain this output, watch this job
Orchestration All sessions and workgroups. Can operate iTerm2 for you. “Which of my sessions has a failed command?”

Linked chats are where watches live. If that is what you are after, start with our companion post on iTerm2 AI Watches and iPhone alerts.

How iTerm2 Orchestration Chat Permissions Work

Two layers control what the AI can do: per-chat permission categories, and the approval rules that apply to orchestration chats.

Layer 1: permission states

Open the info button menu in the chat toolbar. A check mark means granted, a dash means ask before using, and no mark means always denied. Selecting an item rotates it: Never, Ask, Always, Never. The important detail is what Never does: the AI is not even offered the related functions, so it cannot try and fail, it simply does not know the tool exists.

Permission What it exposes Risk Recommended baseline
Check Terminal State Current directory, shell, current or last command and exit status, window size, SSH host, username Low to medium Ask
View Contents Command history, earlier output, the partially typed command line, the visible screen. Always attaches the screen to every message. High on sessions that show secrets Ask
Run Commands Executes commands for you High Ask
Control Terminal Sends keystrokes, erases the command line, restarts the session High Never
View Manpages Local manpages, and remote ones over SSH integration Low Always
Write to the Clipboard Writes to the clipboard Low to medium Ask
Write to the File System Writes files High Never
Act in Web Browser Views the current page in iTerm2 browser profiles Medium Never unless you use browser profiles

Layer 2: orchestration approval rules

  • By default an orchestration chat may read the contents of any session, but it must ask permission before typing into one.
  • To pre-approve, @-mention a session or workgroup in your message. That grants standing control of that target.
  • Each grant shows a Revoke button that puts the target back to asking.
  • Opening a new session always requires your approval, with or without grants.

Figure 1: Orchestration chat approval model with a local Ollama model on the LAN

iTerm2 orchestration chat approval model showing read access by default, typing behind approval, @-mention grants and Revoke

iTerm2 orchestration chat approval model showing read access by default, typing behind approval, @-mention grants and Revoke

Read is the default, not the exception. If the chat runs on a cloud model, anything on screen in any session can end up in a request to that provider. Treat an orchestration chat on a cloud model like screen-sharing every tab with a vendor. That is the main reason to run it locally.

Prerequisites and Architecture

Assumed knowledge

  • iTerm2 basics on macOS, plus SSH to network gear and Linux hosts.
  • Basic Linux service management (systemd, ufw).

Lab requirements

  • iTerm2 3.7 or later with the iTerm2 AI Plugin installed (brew install --cask itermai).
  • An Ubuntu host with a GPU running Ollama at 10.0.10.50.
  • The Mac running iTerm2 at 10.0.10.20 on the same LAN.
  • Sessions to orchestrate: FortiGate CLI at 10.0.1.1, a Linux jump host at 10.0.20.10, and a local shell.
Component Address Role
Mac with iTerm2 3.7+ 10.0.10.20 Runs the orchestration chat and all sessions
Ollama host (Ubuntu) 10.0.10.50:11434 Serves the model over the OpenAI-compatible API, LAN only
FortiGate 10.0.1.1 SSH session the chat may read but never type into
Linux jump host 10.0.20.10 SSH session you grant control of with an @-mention

Step-by-Step Implementation

Step 1: Expose Ollama to the Mac, and only the Mac

Goal: Keep inference on hardware you own, reachable by one client.

Action: The Ollama FAQ notes that Ollama binds 127.0.0.1 port 11434 by default and that you change the bind address with the OLLAMA_HOST environment variable, set through a systemd override on Linux. Bind to the host’s LAN address rather than 0.0.0.0, then allow port 11434 from the Mac only. Ollama has no authentication of its own, so the host firewall is your access control. Allow SSH before you enable ufw or you will lock yourself out.

sudo systemctl edit ollama.service

# Add in the editor:
[Service]
Environment="OLLAMA_HOST=10.0.10.50:11434"

sudo systemctl daemon-reload
sudo systemctl restart ollama

# Keep SSH open first, allow only the Mac, then enable the firewall
sudo ufw allow OpenSSH
sudo ufw allow from 10.0.10.20 to any port 11434 proto tcp
sudo ufw deny 11434/tcp
sudo ufw enable

# Pull a model that supports tool calling
ollama pull <model-name>

GUI Verification: From the Mac, the model list comes back. From any other host, the connection is refused.

# On the Ollama host
ss -ltnp | grep 11434

# From the Mac (10.0.10.20)
curl -s http://10.0.10.50:11434/api/tags

Step 2: Add the local model in iTerm2

Goal: Make the local model the default for new chats.

Action: Open Settings > General > AI. The AI Chat docs say the manual model editor has presets for OpenAI-compatible providers, including Ollama, plus a Test Connection button, and that AI chat can connect to models on your LAN over plain HTTP. Add the model, test it, and mark it as the economy model too if you want background jobs (command-safety checks, screen-idle detection) to stay local.

Preset:    Ollama
URL:       http://10.0.10.50:11434/v1/chat/completions
Model:     <model-name>
API key:   <any placeholder, Ollama ignores it>
Economy:   leaf icon ON (optional)
Test:      Test Connection -> success
Chats are pinned to their provider. You can switch models within a provider, but moving to a different provider needs a new chat, and the toolbar model picker locks once the chat starts. Set the local model as the default before you create the orchestration chat.

GUI Verification: Test Connection succeeds, and a new chat shows the local model in the toolbar picker.

Step 3: Create the orchestration chat

Goal: One chat that can see your whole workspace.

Action: Choose Session > Open AI Chat. When iTerm2 offers Link or Enable Orchestration, choose Enable Orchestration. On an existing chat, use the info button menu and select Enable Orchestration (and Disable Orchestration to drop back).

GUI Verification: The info menu shows Disable Orchestration, which means orchestration is on.

Step 4: Apply the permission baseline

Goal: Read and summarize freely, change nothing without a human click.

Action: In the info button menu, set each permission from the baseline table above. The short version: Control Terminal and Write to the File System on Never, Run Commands and View Contents on Ask, View Manpages on Always. Watch for the prompt iTerm2 shows when you set Check Terminal State or View Contents to Always: it offers to send that data with every message. Decline it on production sessions.

GUI Verification: Control Terminal and Write to the File System show no mark, Run Commands and View Contents show a dash.

Step 5: Grant control one session at a time with @-mentions

Goal: Let the AI act on the jump host, never on the FortiGate.

Action: Read-only questions need no grant. When you do want action, @-mention only the target. Give your sessions clear names (for example prod-fgt-hq and lab-jump01) so a stray mention is obvious.

Look across all my sessions and list any command that exited non-zero
in the last 15 minutes. Do not type anything.

@lab-jump01 check disk usage on / and list files in /tmp older than
7 days. Show me the delete command before running it.

GUI Verification: The grant for lab-jump01 appears with a Revoke button. Click it when the task is done.

Step 6: Put guardrails in the prompt, and know their limits

Goal: Steer the model away from production, on top of the hard controls.

Action: Edit Settings > General > AI > Prompts. iTerm2 keeps separate prompts for unlinked chats, read-only and read-write terminals, linked browsers, and orchestration chats, so you can add rules to the orchestration prompt only.

Never type into or run commands in any session whose name starts
with "prod-". For those sessions, describe what you would do and stop.
Never print secrets, keys, or passwords back into the chat.
A prompt is a request, not an access control. Permissions and the ask-before-typing rule are what actually stop the model. Keep both.

Step 7: Use Explain Output during triage

Goal: Get a second opinion on dense output without granting anything new.

Action: Select output and choose Edit > Explain Output with AI. iTerm2 creates a new chat with the session linked and may annotate the terminal contents with explanations. Pair it with something verbose:

FGT # diagnose debug flow filter addr 198.18.0.10
FGT # diagnose debug flow trace start 20
FGT # diagnose debug enable

Verification and Validation

Test 1, typing requires approval. In the orchestration chat, without an @-mention, ask: “Run uptime on the jump host.” Expected: iTerm2 asks for permission before typing into the session.

Test 2, grant and revoke. Repeat with @lab-jump01 run uptime. Expected: it runs without a per-command prompt. Click Revoke, ask again, and the approval prompt is back.

Test 3, traffic stays on the LAN. Send a chat message while capturing on the Ollama host:

# On the Ollama host: expect only 10.0.10.20 as the client
sudo tcpdump -ni any tcp port 11434

# On the Mac: confirm the connection target
lsof -nP -iTCP:11434

Expected: connections between 10.0.10.20 and 10.0.10.50 only. A second machine trying curl -s http://10.0.10.50:11434/api/tags times out or is refused.

Troubleshooting and Gotchas

1. Test Connection fails against Ollama

Likely cause: Ollama is still on loopback, the override was saved without the [Service] header, or ufw is blocking the Mac.

ss -ltnp | grep 11434
systemctl show ollama.service -p Environment
sudo ufw status numbered

Fix: ss should show 10.0.10.50:11434, not 127.0.0.1:11434. Re-run systemctl edit, then daemon-reload and restart. Make sure the allow rule for 10.0.10.20 sits above the deny rule.

2. The chat talks but never acts

Likely cause: the model does not support tool calling well, or the relevant permission is on Never so the function was never offered. Fix: confirm the permission is on Ask, then try a model that supports tool or function calling. Small local models often answer in prose instead of calling tools.

3. You enabled orchestration on a cloud model with production sessions open

Likely cause: read access is the default, so screens may already have been sent. Fix: disable orchestration from the info menu, close or rename production sessions, move the chat to a local model (new chat, since chats are pinned to a provider), and for OpenAI organizations with Zero Data Retention enabled, turn on Settings > General > AI > Enable “zero data retention”. Note that with it on, iTerm2 resends the full conversation with each message. While you are cleaning up, keep secrets out of your shell history too.

Sources

InfoSecMonkey | No fluff. Just the config that works.

AI Primer: Models, RAG, MCP, Harnesses and Agents Explained

AI Primer: Models, RAG, MCP, Harnesses and Agents Explained

A plain-language AI primer: models, tokens, RAG, MCP, harnesses and agents explained with everyday analogies so you can follow any AI conversation.

Read More
iTerm2 AI Watches: Stop Babysitting Your Terminal and Get Alerts on Your iPhone

iTerm2 AI Watches: Stop Babysitting Your Terminal and Get Alerts on Your iPhone

Set up iTerm2 AI Watches so a linked AI chat tells you when a long job finishes or fails, then push the alert to...

Read More
Claude Code Spinner Verbs: What Combobulating Really Means

Claude Code Spinner Verbs: What Combobulating Really Means

Claude Code spinner verbs explained: what Combobulating really means, a translated field guide, and how to add your own with the spinnerVerbs setting.

Read More