Deploying Open-Source AI Agents in a Virtualized Environment: A Step-by-Step Guide

Choosing the Right Deployment Environment: Why We Avoid Containerized Desktops

In home labs or small team infrastructures, NAS devices are ideal for hosting lightweight AI agent services due to their low power consumption and always-on nature. Many NAS vendors offer HDMI-based desktop output, allowing users to project a Linux desktop environment directly onto a monitor. This enables a single device to handle both NAS storage and desktop applications simultaneously. Some vendors go further by providing integrated desktop workstation solutions that support HDMI output for browsers, media players, and monitoring dashboards.

However, when the deployment target becomes an AI agent tool that needs to run reliably over long periods, these container-based desktop workstation approaches reveal significant drawbacks. A containerized desktop environment is essentially a session-based container designed for interactive use; its lifecycle management, resource isolation policies, and persistence mechanisms are not engineered for long-running background services. Specifically:

• Unpredictable Lifecycle: Container desktop sessions can be terminated due to timeouts, updates, or resource reclamation policies, leading to unexpected service interruptions.
• Resource Contention: The desktop environment itself consumes CPU and memory, competing with the agent service for resources.
• Complex Persistence: File system changes within the container may not be persisted automatically, risking the loss of configuration and data.

Therefore, a more pragmatic approach is to return to the virtual machine (VM) scenario. VMs provide full operating system-level isolation, independent resource allocation, and mature persistence mechanisms, ensuring that AI agent services run stably in a controlled environment for extended periods. The following sections detail the deployment process using a mainstream NAS platform’s built-in VM solution.

Creating the Virtual Machine and Installing the Operating System

Creating a VM on a NAS platform is typically done through its built-in virtualization suite, and the process is straightforward. Here are the key steps and considerations:

Resource Planning

For AI agent services, resource requirements depend on the specific workload. If you are only running a lightweight agent and API forwarding, 2 vCPU cores and 4GB of RAM are sufficient. For local model inference or high-frequency data processing, adjust the configuration accordingly. For storage, allocate at least 40GB of disk space to the VM, and prefer an SSD storage pool to improve I/O performance.

OS Installation

1. Download a mainstream Linux distribution’s desktop image (e.g., Ubuntu Desktop LTS version) and upload it to a shared folder on the NAS.
2. Create a Linux VM in the virtualization suite, using the uploaded image as the installation source.
3. Follow the wizard to complete the installation. It is strongly recommended to set the system language to Chinese during installation. This helps with quickly identifying prompts and error logs in the terminal later, reducing troubleshooting effort.

After installation, access the system desktop via the VNC console provided by the virtualization suite to prepare for remote management configuration.

Remote Management Setup: Enabling SSH and Installing Basic Tools

To avoid dependence on the VNC console and improve daily management efficiency, enable the SSH service in the VM and install essential command-line tools.

Switching to Root and Updating Repositories

Execute the following commands in the terminal to switch to the root user and update the package index:

sudo -i
apt update && apt install -y git curl wget vim ssh

These commands install the core tools needed for subsequent deployment: git for pulling code repositories, curl and wget for downloading scripts and files, vim as a text editor, and ssh for remote login services.

Configuring SSH

Edit the SSH configuration file to allow password authentication and root login (acceptable in a trusted internal network; for production environments, switch to key-based authentication):

nano /etc/ssh/sshd_config

Ensure the following three lines are not commented out and have the correct values:

Port 22
PermitRootLogin yes
PasswordAuthentication yes

Save and exit the editor (press Ctrl+O to save, confirm with Enter, then Ctrl+X to exit). Then restart the SSH service to apply the configuration:

systemctl restart ssh

From this point on, you can log into the VM remotely using any SSH client. Subsequent installation and configuration steps do not require root privileges; it is recommended to operate under a regular user account to minimize the risk of accidental system changes.

Runtime Environment Setup: Node.js Version Management and AI Agent Installation

AI agent tools are typically distributed as Node.js packages, so you need to set up a Node.js runtime environment first. To avoid conflicts with system-level Node.js versions, it is recommended to use a version manager for precise control.

Installing the Version Manager

Install Node Version Manager (nvm) via the official script:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

These commands download and execute the installation script, then reload the shell configuration to make the nvm command available.

Installing a Specific Node.js Version

AI agent tools typically require recent Node.js versions. The following commands install Node.js 22 and set it as the default:

nvm install 22
nvm use 22
nvm alias default 22

Installing the AI Agent Tool

Depending on your needs, you can install the original version or a community-maintained variant. The command names differ between them, allowing co-existence and switching:

# Install the original version; use the corresponding command name
npm install -g <original-package-name>@latest
# Install a localized variant; use the corresponding command name
npm install -g <localized-package-name>@latest

After installation, verify success with <command-name> --version. To update, simply re-run the same installation command.

Post-Deployment Stability Considerations

After the basic deployment, pay attention to the following aspects to ensure long-term stable operation of the AI agent service:

• Auto-Start on Boot: Use a systemd service unit or a @reboot entry in crontab to ensure the agent service starts automatically when the VM boots up.
• Log Management: Redirect the agent service’s standard output and error output to log files, and configure log rotation to prevent the disk from filling up.
• Resource Monitoring: Use the NAS’s built-in monitoring panel or a lightweight monitoring agent to continuously observe CPU, memory, and disk usage trends of the VM, allowing for timely scaling.
• Periodic Backups: Take regular snapshots or exports of the VM’s key configuration files and data directories to prevent unrecoverable service damage.
• Network Policies: If the agent service needs to expose APIs externally, configure firewall rules and a reverse proxy, and enable HTTPS encryption.

Conclusion

Deploying AI agent tools on a NAS device, the virtual machine approach offers significant advantages in stability and controllability compared to containerized desktop solutions. By carefully planning resources, installing a standard Linux system, configuring SSH remote management, and setting up a Node.js environment with a version manager, you can complete the installation and operation of the agent tool. The entire process does not rely on vendor-specific features, ensuring good portability. After deployment, combine it with operational practices such as auto-start, log management, and resource monitoring to build a reliable and maintainable AI agent runtime environment.