AI Agent

Where in the admin: System › Settings › AI provider (/settings/ai) — module switch and provider; System › Admin › License & updates (/license) — module switch. Where in the portal: AI Agent (/ai/agent) and the page /chat/agent, or mode Agent inside the chat.

What it does

The AI Agent connects to a customer's own Linux VM over SSH and carries out tasks described in plain language: "check system health", "install Docker", "find recent errors", "free up disk space". It shows every command it proposes and its output. Read-only commands can run automatically; anything that changes the server waits for the customer to press Run.

Requirements

Item	Requirement
AI module and provider	The AI module on and a working AI provider. The Agent also needs a model that supports tool calling.
openssh-client on the panel server	The Agent runs commands with the panel's own ssh program (/usr/bin/ssh). The installer installs openssh-client; check with ssh -V. Without it the Agent reports "ssh client is not installed on the panel server".
No separate SSH gateway	In the default installation the built-in SSH is used and the ssh-proxy web terminal is not needed. Only when the optional web SSH feature (feature_ssh_web) has been enabled and the ssh-proxy service installed does the Agent go through ssh-proxy instead.
Network	The panel server must reach the VM's IP on its SSH port (22 by default). Check firewalls and security groups between the panel and the guest network.
VM	Customer-owned, running, not locked, Linux (Windows VMs are refused), with a public or reachable IP address.
SSH credentials	The VM's login user and password stored by NexCMP (saved when the VM was created or its password was reset, encrypted), or the panel's operations key if one is installed. If neither exists the Agent says it cannot log in.

Prepare the infrastructure

1. Check the SSH client on the panel server:

   ssh -V
   sudo apt-get install -y openssh-client   # only if missing

2. Check the panel server can open SSH to a guest VM:

   nc -vz 198.51.100.10 22

   Replace the address with a test VM's IP. If this fails, fix the routing or firewall first.

3. Make sure the guest allows password login for the user NexCMP stored (some cloud images disable it), or that the panel's operations key is installed on the guest.

Connect in NexCMP

1. Complete AI provider: module on, provider saved, Test connection green.
2. Nothing else is configured on the admin side. The module switch makes the AI Agent entries appear in the customer portal.
3. As a customer: open AI Agent, choose a running server and click Choose server. The page first probes SSH with a fixed harmless command (no AI call is used) and shows SSH connected or the reason it failed.
4. Type a task or pick a quick start (Check system health, Install Docker, Install Nginx, Find recent errors, Security check, Free up disk space).

How it runs commands

• Where from: the panel server, with the system ssh client, one non-interactive command at a time. The target is always the VM's IP from the database, never from the request; only the owner's own running, unlocked VM can be reached.

• Authentication: the stored password is passed through a one-shot SSH_ASKPASS helper in the process environment — it is not written to disk or put on the command line. Host keys are not pinned (VMs are reinstalled with new keys). Output per command is limited to 200 KB and each command has a time limit (60 seconds).

• Agent loop: the AI proposes commands and reads the outputs; one turn ends after at most 10 steps.

• Modes:

  Mode	Behaviour
  Confirm	Every command waits for Run.
  Auto	Only commands that pass a strict read-only allow-list run by themselves (for example df -h, ps, journalctl). Anything else, and anything the parser cannot analyse with certainty (variables, command substitution, redirects to files), waits for Run.

• Risk labels: commands that overwrite or delete files, write to disks, change accounts or SSH keys, send data to an outside server, open raw network connections, run obfuscated code, download and run a script, shut down or restart the machine, or reach other servers always show Needs confirmation, even in Auto mode.

• Untrusted output: command output is shown to the model as untrusted data; instructions inside it are not followed.

Verify

1. Choose a running test VM. The page shows SSH connected.
2. Ask "Check CPU, RAM and disk". In Auto mode the read-only commands run and the answer summarises them.
3. Ask "Install Nginx". The install command appears with Run and Skip; nothing runs until you press Run.
4. The counter at the top shows the number of AI calls used today (for example 3/300).

Limits & notes

• Daily limit: 300 AI calls per customer per day (UTC); it resets at 00:00 UTC. When it is used up the Agent answers "Daily AI quota reached".
• Concurrency: at most 2 Agent runs per customer at the same time; a session runs one turn at a time.
• Sessions: up to 100 messages per session, 4,000 characters per message. A session belongs to one VM; if the VM is deleted or transferred, the old session becomes read-only.
• Locked or stopped VM, or Windows: the VM is shown as Locked, Stopped, Windows or No address and cannot be chosen.
• Impersonation: an administrator impersonating a customer cannot use the Agent's credential features (see Log in as a customer).
• Responsibility: the Agent can make mistakes. The portal tells customers to review commands before running them. Tell customers in your terms that they are responsible for commands they approve.
• Switching the AI module off removes the Agent entries and the routes answer 404 module_disabled.

Troubleshooting

Symptom	Cause	Fix
"ssh client is not installed on the panel server (apt install openssh-client)"	No ssh binary	sudo apt-get install -y openssh-client.
"The Agent could not log in" / ssh: no saved credentials for this VM	No stored password and no operations key	Reset the VM password in the portal so it is saved again, or install the operations key.
"The server did not answer in time"	Firewall, SSH not listening, VM busy	Test nc -vz <ip> 22 from the panel server; start sshd in the VM.
"Could not reach SSH on this server"	Routing or security group	Allow the panel server to reach the VM on port 22.
"VM not running" / "Forbidden"	VM stopped, locked, deleted or not the customer's	Start it, unlock it or pick another.
"Not available: N (stopped, locked or Windows)"	Reasons listed above	The VM must be Linux and running.
"The SSH gateway is temporarily unavailable"	Web SSH feature enabled but ssh-proxy is down	Start ssh-proxy, or turn the web SSH feature off to use the built-in SSH.
"The AI is responding too slowly (over 90 seconds)"	Provider slow	Use a faster model or a lower Reasoning effort.
"Daily AI quota reached"	300 calls used	Wait until 00:00 UTC.
"This session is still running"	Another turn in progress	Wait or press Stop.