AI Terminal Assistant

Overview

The AI Terminal Assistant is an optional chat panel inside PatchMon's Web SSH Terminal. Operators open it alongside the terminal to ask questions about what they are seeing ("why did apt fail?", "how do I restart this service?", "explain this stack trace") and get answers from an LLM of their choice. The assistant can also turn code snippets in its replies into paste-to-terminal actions, so you stay inside a single window.

The assistant uses PatchMon as a proxy to a supported third-party AI provider (OpenRouter, Anthropic, OpenAI, or Google Gemini). The provider, model, and API key are configured once at the system level; individual operators don't have to set anything up.

Web SSH shipped in 1.4.0, and the AI assistant in the same release.

Supported providers

Four providers are supported in 2.0, each with a curated list of models:

Pick one provider per PatchMon deployment. To change providers, edit the AI settings. The API key is cleared automatically when you switch, and you'll be asked to enter a new one for the new provider.

Module gate

The AI assistant is part of the ai capability module (also referred to as ai_assist in some settings). If your subscription does not include the AI module, the settings page is visible but cannot be enabled. Ask your account administrator if the AI features are missing entirely from your instance.

Permissions

There is no separate per-user toggle. If AI is enabled at the system level and you have terminal access, the assistant is available to you.

Configuring a provider

Go to Settings → AI Terminal Assistant.

1. Pick your provider

Use the Provider dropdown. The Model dropdown below it repopulates with that provider's models and auto-selects the provider's default. Changing the provider immediately clears the stored API key (because keys belong to one provider each).

2. Enter your API key

Each provider issues its own key:

Paste the key into the API Key field and click Save. PatchMon encrypts the key with your instance's SESSION_SECRET before writing it to the database. The key is never returned to the browser after saving; only a boolean "is set" flag is exposed via the API.

API Key Needs to be Re-entered. If PatchMon later fails to decrypt the stored key (for example, because SESSION_SECRET was rotated or was inconsistent across restarts), the settings page shows a yellow banner. Re-enter the key to clear it.

3. Test the connection

Click Test Connection. The server sends a one-sentence round-trip to the configured provider and checks the response. A green check plus "AI connection test successful" confirms everything works; a red error means the key is wrong, the model is unavailable, or the provider is unreachable from the PatchMon server.

4. Enable the assistant

Flip the Enable AI Assistant toggle at the top of the page. Until this is on, the chat panel inside the SSH terminal is hidden for everyone.

Using the assistant in a terminal

1. Open a web SSH terminal to any host (see Web SSH Terminal).
2. Click the robot icon in the terminal toolbar to open the assistant panel on the right.
3. Type a question and press Enter. Example questions:
   • "The systemctl status nginx output says (code=exited, status=1/FAILURE). What's wrong?"
   • "How do I check disk usage on this Ubuntu host?"
   • "Explain this error message."
4. The assistant replies inline. Code snippets (fenced with triple backticks or tagged as commands) get a Play and Copy button so you can paste the command into the terminal without typing.

The panel is a normal chat. You can keep asking follow-ups and the assistant keeps context.

What data is sent to the provider

Each request to /api/v1/ai/assist includes:

• The system prompt: hardcoded in PatchMon, positions the model as a terminal helper for Linux/Unix administration.
• The terminal context: the last ~3 000 characters of terminal output captured from the browser buffer, wrapped in Markdown fences, so the model can read what you're seeing. The server caps the uploaded context at 10 000 characters as a safety net.
• The conversation history: up to the last 10 messages (user + assistant) from the current chat session, each trimmed to 2 000 characters.
• The question: your current message, 1–2 000 characters.

The question is then proxied to the provider you configured (OpenRouter, Anthropic, OpenAI, or Gemini). PatchMon does not retain the request beyond the normal server access log.

Command-completion requests (when you pause while typing into the terminal, if completion is enabled) send:

• Up to 5 000 characters of context.
• The partial command you're typing (2–500 characters).
• A low-temperature prompt instructing the model to output only the completion.

Privacy considerations

• Terminal output you capture in the buffer is sent to the third-party provider as context. If you've just run a command that shows sensitive data (API keys, secrets, customer data), clear the terminal or don't ask the assistant about it.
• Your provider's terms of service govern what they may do with the request. Review the provider's data-processing policy before enabling on production hosts. OpenRouter, Anthropic, OpenAI, and Gemini all publish policies.
• API key secrecy: keys are encrypted at rest and never echoed back over the API. Admins with database access could still read the encrypted value; rotate SESSION_SECRET carefully.
• All provider traffic leaves the PatchMon server over HTTPS directly to the provider's endpoint. PatchMon does not route it through any intermediate service.

If these trade-offs are not acceptable for a particular environment, leave the assistant disabled. The normal SSH terminal works fine without it.

Rate limiting

Each user is limited to 30 AI requests per minute across assist and complete combined. The limit is enforced in Redis with a 60-second window. Exceeding the limit returns 429 Rate limit exceeded. Please wait a moment. The panel shows the error inline and you can retry after the window resets.

Rate limiting is per PatchMon user, not per IP. It exists to protect your provider spend, not to throttle normal interactive use. 30/min is plenty of headroom for a single operator, while catching runaway scripts.

Input and response limits

• Questions: 1–2 000 characters. Longer input is rejected with 400.
• Context: 10 000 characters max (server trims longer input).
• Conversation history: last 10 messages sent to the provider.
• Per-message trim: 2 000 characters.
• Completion input: 2–500 characters.
• Completion context: 5 000 characters.
• max_tokens per assistant reply: 1024.
• Assistant temperature: 0.7 (creative but focused).
• Completion temperature: 0.3 (conservative).

These values match the product defaults in internal/ai/service.go and are not currently configurable via the UI.

Enabling and disabling

• Per-deployment: the admin toggle in Settings → AI Terminal Assistant. Off = panel is hidden for everyone.
• Per-user (soft): any user can simply keep the panel closed. There is no per-user opt-out flag.
• Emergency off: clear the API key in Settings → AI Terminal Assistant. The server-side AI endpoints return 400 AI API key not configured and the panel surfaces that error.

Troubleshooting

Related pages

• Web SSH Terminal
• RDP via Guacamole