---
title: AI Agent
description: Let customers administer their Linux VMs by describing a task in plain language — how the Agent connects over SSH, what it may run on its own, and what you must have in place.
url: https://nexcmp.com/docs/ai/ai-agent/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# 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](https://nexcmp.com/docs/ai/ai-providers/). 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:

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

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

   ```bash
   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](https://nexcmp.com/docs/ai/ai-providers/): 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](https://nexcmp.com/docs/customers/login-as/)).
- **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**. |