Install 3CX AI Server on macOS or Debian (with NVIDIA)
- Introduction
- General Requirements
- macOS Requirements
- Debian Requirements
- Confirm your Mac's suitability
- Preparing your Linux Host
- Update the operating system
- Install the base tools
- Installing the 3CX AI Server
- PBX Side
- AI Server Side
- Confirm the 3CX AI Server works
- Multiple PBXs using the same AI Server
- Managing the 3CX AI Server
- Managing macOS 3CX AI Services
- Managing Debian 3CX AI Services
- Uninstall the AI Server
- Managing Connected PBXs
- Troubleshooting
- See Also
Introduction
This guide explains how to install 3CX AI Server for a 3CX PBX Version 20 Update 10 onwards on a supported Apple Silicon Mac such as a Mac Mini. The 3CX AI Server will transcribe PBX calls and perform call analysis.
General Requirements
- You need access to the 3CX Admin Console and shell or terminal access on the machine (macOS or Debian) that will run 3CX AI Server
- You will need local administrator rights (to elevate using sudo).
- Make sure the 3CX AI Server can reach the PBX on its main SSL port, usually 443 or 5001, and can reach the 3CX download servers.
- If the 3CX AI Server option is not shown in the PBX, confirm that you’re using the correct 3CX Build and 3CX license and check again under Admin > Integrations > Transcription > 3CX AI Server.
macOS Requirements
- Only Apple Silicon Macs are supported. Intel-based Macs are not supported.
- Minimum memory is 16 GB RAM. The recommended target is 24 GB RAM, and Mac Mini class hardware is the expected starting practical deployment path.
Debian Requirements
- Use a Debian 12 or Debian 13 with a supported NVIDIA GPU, preferably with pre-installed NVIDIA drivers and CUDA libraries.
- Minimum hardware is 16 GB RAM, 20 GB free disk space and 16 GB VRAM. The recommended target is 24 GB RAM and a 24 GB RTX-class GPU.
Confirm your Mac's suitability
Use an Apple Silicon Mac with enough free disk space and memory for the expected transcription and analysis load.
uname -m ; system_profiler SPHardwareDataType | egrep 'Chip|Memory'
A healthy result will show Apple Silicon hardware and the expected memory size. For example:
arm64
2026-07-10 16:35:56.134 system_profiler[2278:79797] hw.cpufamily: 0x17d5b93a
Chip: Apple M4 Pro
Memory: 24 GB
If the Mac reports Intel hardware, does not expose Apple Silicon, or shows too little memory, stop and move the install to a supported Mac rather than forcing the deployment onto unsupported hardware.
Preparing your Linux Host
Update the operating system
Perform a package update and upgrade before installing 3CX AI Server:
sudo apt-get update
sudo apt-get upgrade
Reboot the machine to ensure that the running kernel and installed headers match:
sudo reboot
Install the base tools
Install the packages required by the installer:
sudo apt -y install curl apt-transport-https gnupg gpg wget
Check if Nvidia drivers and CUDA are installed:
nvidia-smi
If the drivers are installed correctly, you would get output similar to the following:
user@aiserver:~$ nvidia-smi
Mon Jan 26 09:04:40 2026
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 590.48.01 Driver Version: 590.48.01 CUDA Version: 13.1 |
+-----------------------------------------+------------------------+----------------------+
| GPU Name Persistence-M | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+========================+======================|
| 0 NVIDIA L4 On | 00000000:00:03.0 Off | 0 |
| N/A 40C P8 12W / 72W | 0MiB / 23034MiB | 0% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
+-----------------------------------------------------------------------------------------+
| Processes: |
| GPU GI CI PID Type Process name GPU Memory |
| ID ID Usage |
|=========================================================================================|
| No running processes found |
+-----------------------------------------------------------------------------------------+
If you do not see the correct output for nvidia-smi, elevate to the root user, and ensure nvidia-smi is installed with the required dependencies:
apt -y install linux-headers-$(uname -r)
DEB_VERSION=$(VERSION_ID=; . /etc/os-release; echo "$VERSION_ID")
wget "https://developer.download.nvidia.com/compute/cuda/repos/debian${DEB_VERSION}/x86_64/cuda-keyring_1.1-1_all.deb"
dpkg -i cuda-keyring_1.1-1_all.deb
apt update
apt -y install nvidia-open
apt -y install nvidia-driver-cuda nvidia-kernel-open-dkms
reboot
After the reboot, confirm the stack is running successfully with nvidia-smi.
Installing the 3CX AI Server
PBX Side
- In the PBX, go to Admin > Integrations > Transcription.
- From the dropdown, select 3CX AI Server and click the + Add AI Server button.
- Copy the generated installation command using the provided copy button.
AI Server Side
curl -fsSL https://wmr-cdn.3cx.net/templates/install.sh | sudo bash -s -- mypbx.example.com 22334455-6677-8899-aabb-ccddeeff0011
- In your terminal, paste and run the command previously copied from the PBX.
- On Debian:
- If you are using an enterprise level GPU like an Nvidia L4 on a cloud provider with 22GB, you may be asked if you want to disable ECC on the GPU. If you accept (type “y”) this will disable ECC, thus reclaiming 2GB of memory that would otherwise be unused. Note that disabling ECC will immediately trigger a reboot, and you will have to go back to the first step after the reboot.
- The installer will then ask you if you want to install and whether you agree to terms and conditions; accept to continue:
- The installer downloads the required components, creates the configuration, installs the services, and registers the AI Server to the PBX.
Confirm the 3CX AI Server works
- Return to Admin > Integrations > Transcription and confirm that the new AI Server status appears as green and not red.
- You can make some test calls to confirm correct functionality; when recordings are being processed, the Admin Console will show queue and activity information.
Multiple PBXs using the same AI Server
You may also allow the use of the same AI server by multiple PBXs. To do this simply follow the installation guide above again for the new PBX.
For example, you would have to go to the new PBX under Admin > Integrations > Transcription, and click on "Add AI Server", then go to your AI server and paste the command and press enter. Since the AI Server is already installed on that host, the installation will skip already-installed components; this will effectively authorize the new PBX to also use the AI Server.
Managing the 3CX AI Server
The 3CX AI Server installs several services, including the converter, transcriber and Ollama service.
Managing macOS 3CX AI Services
Use launchctl to interact with the installed macOS services.
Stop (and unregister) the services:
sudo launchctl bootout system/com.3cx.converter
sudo launchctl bootout system/com.3cx.transcriber
sudo launchctl bootout system/com.3cx.logrotate
sudo launchctl bootout system/com.ollama.serve
Start (and register) the services:
sudo launchctl bootstrap system /Library/LaunchDaemons/com.3cx.converter.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.3cx.transcriber.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.3cx.logrotate.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/com.ollama.serve.plist
Managing Debian 3CX AI Services
For managing the running status of the 3CX services, use the following commands:
Check service status:
sudo systemctl status 3cxai-converter 3cxai-transcriber 3cxai-ollama
Restart the services:
sudo systemctl restart 3cxai-converter 3cxai-transcriber 3cxai-ollama
Stop the services:
sudo systemctl stop 3cxai-converter 3cxai-transcriber 3cxai-ollama
Start the services:
sudo systemctl start 3cxai-converter 3cxai-transcriber 3cxai-ollama
Uninstall the AI Server
To remove the AI Server package from the host, run the bundled uninstaller script from the setup directory:
sudo /opt/3cx/aiserver/setup/3cxai-uninstall.sh
Managing Connected PBXs
In order to manage connected PBXs, you can use the inbuilt connection manager script. With it you can inspect, disable, re-enable or delete stored PBX authorisations.
Show the built-in help first.
sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh --help
Identify and list all configured PBX connections & see their UUID
sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh
Disable a PBX connection without deleting it.
sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh --disable <UUID>
Re-enable a previously disabled PBX connection.
sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh --enable <UUID>
Delete a stored PBX connection permanently.
sudo /opt/3cx/aiserver/setup/3cxai-connection-manager.sh --delete <UUID>
Troubleshooting
The various PBX authorisations, configurations and other AI server settings are all saved in the following files:
/opt/3cx/aiserver/setup/connections.json
/opt/3cx/aiserver/setup/config.json
You may troubleshoot the server by checking the server logs located under the path below.
/var/opt/3cx/aiserver/logs
The AI Server package installs into these main paths.
/opt/3cx/aiserver
/var/opt/3cx/aiserver
- AI Server is down: Confirm the services are loaded and that the 3CX AI Server can reach the PBX over HTTPS.
- Install command doesn’t work - Avoid using an install command from a previous configuration; delete the entry for the 3CX AI Server from the PBX, create a new one and install using the install command for the newly generated 3CX AI Server entry.
- nvidia-smi fails (Debian only): Fix the NVIDIA driver or CUDA state before rerunning the installer.
- The PBX rejects the connection: Remove stale configuration and reinstall using a fresh UUID-backed command.
See Also
Last Updated
This document was last updated on 9 September 2026