For AI assistants: this page as plain markdown is at https://docs.voicelogica.ai/raw/telephony/edge-device.md, and https://docs.voicelogica.ai/llms.txt lists the docs by topic, one file each, small enough to read whole. Read those rather than this HTML page.
Edge device
An edge device is a small connector you install inside the customer’s network. It lets Voice Logica reach a phone system (PBX) that has no public address - an on-premise PBX at 192.168.x.x, 10.x.x.x or 172.16-31.x.x.
It only makes outbound connections. Nobody opens a port, forwards anything, or gives the PBX a public IP.
Do you need one
Section titled “Do you need one”| The PBX or carrier is… | What to use |
|---|---|
| On the office LAN, private IP only | Edge device (this page), then a Local IP PBX trunk |
| Reachable from the internet (public IP or hostname) | Your own carrier - Public IP PBX |
| A SIP carrier (Yuboto, Telnyx, Twilio…) | Your own carrier - VOIP provider |
| Registers to us (the PBX dials out) | Your own carrier - Incoming PBX |
If you type a private address into a Public IP PBX trunk, the drawer blocks it and offers switch to Local IP PBX. That is the signal you need a device.
How it works
Section titled “How it works”- The device keeps a control connection to
calls.voicelogica.aiover TCP 443 (secure WebSocket). - It brings up WireGuard tunnels to the three Voice Logica media servers over UDP 51820. SIP and call audio travel inside those tunnels, and calls are spread across the three servers.
- On the LAN side it talks to the PBX like any other SIP phone or trunk.
Both connections start from inside the network. The device cannot be reached from the internet, cannot run arbitrary commands, and cannot reach the rest of your network.
Network requirements
Section titled “Network requirements”Send this list to whoever runs the site firewall before install day.
- An always-on machine on the same network as the PBX: a Windows PC, a Linux box, a Raspberry Pi, a spare PC started from a USB stick, or a virtual machine. Not a laptop that sleeps or leaves the office.
- Outbound TCP 443 to
calls.voicelogica.ai. The name must resolve - DNS filtering that blocks our domain stops enrollment. - Outbound UDP 51820 to all three Voice Logica media servers:
65.21.125.239,65.109.51.21and213.133.102.213. Without it the device shows online, and calls have no audio. With only the first address allowed, calls still work, relayed through that one server, so every call depends on it. - All UDP both ways between the device and the PBX. A rule for port 5060 alone is not enough - audio uses changing ports. If the firewall needs exact ports, allow the PBX’s SIP port (usually 5060) and UDP 10000-46000 to the device.
- No inbound ports, no port forwarding, no public IP.
| From | To | Ports | For |
|---|---|---|---|
| Device | calls.voicelogica.ai | TCP 443 | Control connection |
| Device | 65.21.125.239, 65.109.51.21 and 213.133.102.213 | UDP 51820 | Call tunnels, one per media server |
| PBX | Device (on the LAN) | SIP port, UDP 10000-46000 | Signalling and call audio |
Call audio reaches the device on a fixed block of ports per media server: 40000-46000, 30000-36000 and 20000-26000. The rest of 10000-46000 is kept for a fourth server (10000-16000) and for router audio ports (10000-10020), so one rule for the whole range does not need changing later.
Full network sheet for IT: network requirements.
Pick the machine
Section titled “Pick the machine”Start from what is already in the office, next to the PBX:
| You have… | Use |
|---|---|
| A Windows PC that stays on | Windows |
| A Linux machine with Docker | Linux |
| A spare PC or mini-PC with no operating system, or one whose disk may be erased | PC (install on disk) |
| A spare PC whose disk must stay as it is | PC (USB stick) |
| A Raspberry Pi 4 or 5 | Raspberry Pi |
| A server that runs VirtualBox, VMware or Proxmox | Virtual machine |
A spare PC needs no Windows or Linux. The installer stick erases the PC’s disk and puts the connector on it, so the PC then runs without the stick. If the disk must not be touched, the PC can run the connector from a USB stick instead, with the stick left in.
Install the device
Section titled “Install the device”You can start from two places. Both produce the same device:
- Telephony - Trunks - + Add Trunk - Local IP PBX. The drawer shows Download the connector with Windows, Linux, Raspberry Pi, PC (USB stick) and VM image, then waits for the device. Use this when you are connecting a PBX right now.
- PBX Edge Devices (
app.voicelogica.ai/phones/edge-devices) - Add Edge Device. Use this to prepare a device ahead of time, or to Email the steps to the customer when someone else is on site.
In Add Edge Device, give it a Site label (the office name, for example “HQ Office”), then answer two questions:
- Where will the edge device run? On a computer that is already in use, On a spare PC or On a Raspberry Pi.
- For a computer in use, What does that computer run? Windows, Linux with Docker or A virtualization server. For a spare PC, What should happen to the PC’s disk? Install on its disk (erases it) or Run from a USB stick.
Your answer shows at the top with Change to go back. Then choose I’ll set it up now or Email the steps to the customer. The main button changes to match.
- Choose On a computer that is already in use - Windows and click Download installer. The
.exeis built for your company - the token is inside, nothing to type. - Copy it to the always-on Windows PC next to the PBX. Run it and accept the prompts.
- It installs WireGuard and the connector as a service and connects by itself. It starts again after a reboot.
The download link is valid for 4 hours. After that, download a fresh one (Redownload Windows in the trunk drawer).
If antivirus or a browser policy blocks the .exe, run the PowerShell one-liner instead in an Administrator PowerShell:
$env:EDGE_TOKEN='<token>'; irm https://calls.voicelogica.ai/install.ps1 | iexClaude or ChatGPT hands you this line with the token already filled in - see Or let Claude do it.
-
Choose On a computer that is already in use - Linux with Docker and click Get install command.
-
Copy the line and run it on the Linux machine:
Terminal window curl -fsSL https://calls.voicelogica.ai/install.sh | sudo bash -s -- --token <token> -
It needs
curlandsudo. It uses Docker and installs it if it is missing.
At the end the script runs a short preflight - DNS, TCP 443 and the local firewall - and prints a block to send to IT if anything fails. Read it before you leave the machine.
The token in the command is valid for 72 hours.
For a spare PC or mini-PC with no operating system, or one whose disk may be erased. The installer puts the connector on the PC’s own disk; afterwards the PC runs without the stick.
You need a USB stick of 8 GB or more (it is erased), a network cable to the same network as the PBX, and a computer to prepare the stick on.
- In Add Edge Device, choose On a spare PC - Install on its disk (erases it) - Download the installer, or download voicelogica-edge-pc-installer.img.xz (about 920 MB).
- Unzip it with 7-Zip to get the
.imgfile. - Write the
.imgto the stick with Rufus: pick the stick, SELECT the.img, START, and choose DD Image mode if asked. - Plug the stick and the network cable into the PC. Turn it on and press the boot menu key (usually F12, F11 or Esc) to start from the USB stick.
- The installer shows the disk it will erase (the PC’s largest internal disk) and counts down 15 seconds. Pull the stick out during the countdown to cancel. It installs in 1 to 5 minutes and switches the PC off.
- Remove the stick and turn the PC on. After about 3 minutes its screen shows a Claim code. Enter it under Claim code in Add Edge Device and click Claim device, or give it to Claude or ChatGPT.
There is no setup file and no token on the installer stick, so the same stick sets up any number of PCs. Each one shows its own claim code, which works for 24 hours after the PC first starts.
For a spare PC or mini-PC whose disk must stay as it is: nothing is installed. The PC starts from the stick and runs the connector from it.
You need a USB stick of 8 GB or more (it is erased), a network cable to the same network as the PBX, and a computer to prepare the stick on.
- In the trunk drawer, under PC (USB stick), download the image voicelogica-edge-pc.img.xz (about 460 MB).
- Unzip it with 7-Zip to get the
.imgfile. - Write the
.imgto the stick with Rufus: pick the stick, SELECT the.img, START, and choose DD Image mode if asked. balenaEtcher also works but often fails on Windows: see Etcher fails. - Click Download voicelogica.txt and copy the file onto the stick’s VLSETUP drive. If the drive does not appear, unplug the stick and plug it back in. The file ties the PC to your company.
- Plug the stick and the network cable into the PC. Turn it on and press the boot menu key (usually F12, F11 or Esc) to start from the USB stick.
- Leave it running with the stick in. The first start takes about 3 minutes, then the device shows Live in the drawer.
- In the PC’s BIOS, put USB first in the boot order, so the PC starts from the stick again by itself after a power cut.
No setup file? Connect a screen to the PC: it shows a Claim code. Enter it under PBX Edge Devices - Add Edge Device - Claim code, or give it to Claude or ChatGPT, as for the virtual machine.
The token in the setup file is valid for 72 hours. If the PC starts later than that, download a new voicelogica.txt and copy it over the old one.
For a Raspberry Pi 4 or 5. Wi-Fi is not used: the Pi needs a network cable.
- Download the image voicelogica-edge-pi.img.xz (about 1 GB). Do not unzip it.
- Write it to a microSD card of 16 GB or more with Raspberry Pi Imager: choose Raspberry Pi 4 or 5, Use custom, pick the file, then the card, and press Write.
- Click Download voicelogica.txt and copy the file onto the card’s bootfs drive. If the drive does not appear, unplug the card and plug it back in.
- Put the card in the Pi, connect the network cable and plug in the power. The first start takes about 3 minutes.
Without the setup file, the Pi shows a Claim code on a screen connected over HDMI; claim it as for the virtual machine. The token in the file is valid for 72 hours.
Or let your AI assistant prepare the card. If you have connected Claude or ChatGPT to Voice Logica, put the microSD card in your computer and say “I want a Raspberry Pi edge device.”
- The assistant settles which company the Pi is for. If you have one company, it uses that one. A reseller with several client companies is asked which one. Otherwise it suggests the company you are working in, and you confirm or change it. You can set up a Pi for your own companies; resellers also for their client companies, and account managers for the companies they have been given access to. The site is named after the company unless you give another name, e.g. “site Athens office”.
- It gets the image and your company’s voicelogica.txt.
- If the assistant can run commands on your computer (for example Claude Code or the Claude desktop app), it writes the card itself. It only writes an external, removable card of 8 to 256 GB that is not your computer’s own disk. It tells you which card it found and waits for your yes before erasing it, and if more than one card is plugged in it asks which one. Your computer asks for your password in its own window: type it there. The assistant never asks for your password in the chat. Then it copies voicelogica.txt onto the card and ejects it.
- If it cannot run commands (for example Claude on the web, or ChatGPT), it gives you the download link, the Raspberry Pi Imager steps above, and the line to save as voicelogica.txt.
- Put the card in the Pi, connect the network cable and plug in the power. A few minutes later the assistant checks that the device is online.
The setup file holds the token that ties the Pi to your company, so do not share it or paste it anywhere else. If the Pi starts more than 72 hours later, ask the assistant for a new setup file: only the file has to be copied again, not the whole card.
- Choose On a computer that is already in use - A virtualization server and click Download appliance.
- The appliance page has the image for VirtualBox, VMware or Proxmox and the steps to import it.
- Give the VM a network adapter bridged onto the PBX network, not NAT, so it gets an address on the same LAN.
- Start the VM. Within a minute its console screen shows Claim code followed by a code like
7K2M-9QXR. - On PBX Edge Devices, click Add Edge Device, enter the code under Claim code and click Claim device. Or give the code to Claude or ChatGPT: “Claim my edge device, the code is 7K2M-9QXR.”
The VM downloads without a company inside it, so the code is how it joins yours. It works for 24 hours after the VM first starts. Once the device is claimed, the code disappears from the screen.
Wait until it is online
Section titled “Wait until it is online”The token ties the device to your company. The first device of a company on a network is approved automatically. A second one shows Pending until a company admin approves it: on PBX Edge Devices, click Approve device (the check mark) on its row. It connects within a minute. A virtual machine is approved when you claim it with its code. Watch it on PBX Edge Devices (the list refreshes on its own) or in the trunk drawer:
In the trunk drawer the pill changes from Not connected to Live, and Next steps appears. Refresh devices checks now.
Connect the PBX
Section titled “Connect the PBX”-
Telephony - Trunks - + Add Trunk - Local IP PBX
Name the trunk after the site. If the device is already Live, the form unlocks right away.
-
Pick the PBX
Under Suggested PBXs on this LAN, click Find PBXs. The device scans its subnets for SIP hosts. Click a suggestion, or type the PBX’s LAN IP yourself.
-
Set the SIP port if it is not 5060
Advanced - Port. Some PBXs listen elsewhere - Alcatel OXO commonly uses 5059. Ask the PBX admin if unsure.
-
Test now
Sends SIP OPTIONS to the PBX through the device. Any answer - including 401/407 (wants credentials) - means SIP is flowing. No SIP response means wrong IP or port, or something between the device and the PBX drops SIP.
-
Credentials
The extension (or SIP trunk account) the PBX created for Voice Logica: Username, Password, and Login (Authorization ID) if the PBX uses a separate one.
-
Destination, then Create Trunk
Point unrouted calls at your AI agent. Create Trunk. Registration should show online within a minute.
-
Send calls to the agent and dial in
Route a number or a PBX queue / extension to the new trunk on the PBX side, connect it to the agent under Channels - Telephony, and call it from a real phone. Check Calls. See Your own carrier for numbers and default destination.
To change the PBX address on an existing device later, use the slider icon (Configure PBX settings) on its row in PBX Edge Devices - PBX IP address and SIP port, then Save. Pushing new settings restarts the device’s SIP relay, so do it outside a live call.
Router audio ports
Section titled “Router audio ports”Some routers let call audio back in only on a fixed range of UDP ports that is forwarded to one computer. This is common when a carrier line runs over the carrier’s own router (for example Vodafone). Calls then ring and connect, but nobody hears anything: the device sends audio out, and nothing comes back.
The fix is to tell the device which ports the router forwards, so it uses exactly those for call audio.
- Forward the ports on the router. In the router’s settings (usually Firewall → Port Forward), forward UDP 10000-10020 to the computer running the device (its LAN address, e.g.
192.168.1.3). If the router already forwards a range to that computer, use that range instead. - Set the same range. Telephony → Trunks → open the trunk → Router audio ports → type
10000-10020→ Apply. Or ask Claude: “set the edge device audio ports to 10000-10020”. - Close other phone apps on that computer (softphones such as MicroSIP). Two programs cannot use the same ports.
- Make a test call. Both sides should hear each other right away.
Each call uses two ports, so 10000-10020 carries 10 calls at the same time. To go back to the device’s own ports, clear the field and press Apply. The setting belongs to the device: every trunk on it uses it. It needs device version 1.1.39 or newer, which installs itself.
Prefer help? If you connected Claude or ChatGPT, say “my calls have no audio”. It reads the device’s audio counters, tells you what to forward and sets the ports for you.
Pause a device
Section titled “Pause a device”Pausing takes a device out of service without uninstalling it. While it is paused, Voice Logica passes none of its calls: no line registers through it and no call goes in or out through it. The machine stays installed and online, and resuming switches it straight back. Use it to test with only one device, or to take an old device out before you uninstall it.
There is no button for it in the app yet. If you have connected Claude or ChatGPT:
- Pause: say “pause the edge device on the old PC” (or name its site). It lists the devices and pauses the one you mean.
- Resume: say “resume the edge device on the old PC”. A line through it registers again within a few minutes.
- Check: “show my edge devices” shows a paused device as paused, with who paused it and when.
A call that is already connected keeps its audio until it ends. A line that goes only through the paused device stops working until you resume it, so pause at a quiet time or only a device whose lines have another way in.
Two devices with the same line. A line always goes through the device its trunk is set up on. If an old device still has the same line configured, calls can ring on the wrong phones or have no audio: pause the old device (or uninstall it) so the phone system is reached through one device only.
Or let Claude do it
Section titled “Or let Claude do it”If you have connected Claude or ChatGPT to Voice Logica, say “connect my PBX”. The assistant gives you the Windows download link (or the Linux command) with the token inside, watches the device come online, asks for the PBX IP, SIP port and extension login, and creates the trunk through the device. Walkthrough: Connect your PBX from Claude.
For a Raspberry Pi, put the microSD card in your computer and say “I want a Raspberry Pi edge device”: the assistant prepares the card, or tells you how, as described under Raspberry Pi.
Troubleshooting
Section titled “Troubleshooting”Why do calls have no audio when my edge device shows online?
The tunnel is down. The site firewall must allow outbound UDP 51820 to the three media servers (65.21.125.239, 65.109.51.21 and 213.133.102.213). The trunk drawer says Connected, but the tunnel is down (UDP 51820); Claude reports tunnelUp: false.
If the tunnel is up and audio is still silent both ways:
- The firewall between the device and the PBX passes all UDP, not only 5060. If it lists ports, it must include UDP 10000-46000 to the device: a rule for 40000-46000 alone drops the calls that run on the second and third media server.
- On Linux, a default-deny host firewall drops audio. Run
ufw allow in on wg0on the device.
Why does the agent speak but never hear the caller on calls through my edge device?
The tunnel is fine and the call is up, but no audio comes back from the carrier or PBX. The device reports it: Telephony → Edge devices shows a No call audio warning with the likely cause, and Claude sees toServer: 0 in the device media.
- The router forwards only a fixed UDP range to this computer: set Router audio ports.
- SIP ALG is off on the router, if you can reach that setting.
- No other phone app on the same computer is registered with the same number.
Why does my edge device never come online?
- The installer finished and the machine is on (not asleep).
- Outbound TCP 443 to
calls.voicelogica.aiis allowed. - The name resolves - DNS / web filtering often blocks new domains. Allowlist
calls.voicelogica.aiandvoicelogica.ai. - The Windows link (4 hours) or install token (72 hours) had not expired. If in doubt, generate a new one.
Why does Test now on my edge device say No SIP response?
The PBX’s IP or port is wrong, or the PBX ignores the edge device. Confirm the PBX’s SIP port - it is not always 5060 (Alcatel OXO: 5059) - and set it under Advanced - Port. A 403 Forbidden means SIP arrives but the PBX rejects this source: allow the device’s LAN address in the PBX’s SIP / trunk settings.
Why does Claude say my PBX is not reachable when the edge device test works?
PBX reachable is a ping from the edge device. Many networks and PBXs block ping while SIP works fine. Trust Test now and the trunk’s registration, not the ping.
balenaEtcher stops with 'The writer process ended unexpectedly'. What now?
The image itself is fine; the write fails on the computer preparing the stick.
- Use a stick of 8 GB or more. The image unpacks to 6.5 GB, and some cheap “8 GB” sticks are slightly smaller: try another stick.
- Close Etcher, right-click it - Run as administrator and accept the Windows prompt. Antivirus or Controlled folder access can also block the write: allow Etcher, or pause it while flashing.
- Still failing: unzip the file first with 7-Zip (right-click - 7-Zip - Extract here) to get voicelogica-edge-pc.img, and write that with Rufus: pick the stick, SELECT the .img file, START, and choose DD Image mode if Rufus asks.
- Then copy voicelogica.txt to the VLSETUP drive as usual.
Why does the PC not start from the USB stick?
- Press the boot menu key right after power-on: F12 on Dell and Lenovo, F11 on MSI, Esc or F9 on HP. Pick the entry with the stick’s name or USB.
- The stick does not appear in the list: in the BIOS, turn on USB boot, and turn off Secure Boot if the PC refuses the stick.
- It starts, but the device never shows up: check the network cable, and that voicelogica.txt is on the VLSETUP drive. Without the file, read the Claim code on the PC’s screen and claim it.
Why does my Raspberry Pi not show up?
- Look at the lights. A steady red light and a green light that never flickers mean the Pi is not reading the card. Push the card fully into the slot under the board (contacts facing the board). A Pi 1, Pi 2 or the original Pi Zero cannot run the image: use a Pi 4 or 5.
- Check the cable. The Pi needs a network cable to a LAN port of the router or switch, not the WAN/Internet port. Wi-Fi is not used. The socket’s lights come on when the cable is connected.
- Wait 5 minutes. On the first start the Pi downloads the Voice Logica agent, and on a slow line that takes a few minutes. It keeps retrying until the network is there.
- Check the card. Put the card back in your computer. If voicelogica.txt is still on the bootfs drive, the Pi never started from the card: write it again, or try another card. If the file is gone, the Pi started and read it, so the network is the problem: the site must allow outbound TCP 443 to
calls.voicelogica.ai. - It shows Pending: approve it, as described under Wait until it is online.
Can one edge device serve two PBXs on different networks?
No. One edge device serves one PBX target at a time. Install a second device next to the second PBX, then create a second Local IP PBX trunk through it.
Why do callers reach nothing when my trunk through the edge device is registered?
Either the PBX is not sending those calls to the trunk, or the number is not on this agent. Check the routing on the PBX first, then the trunk’s default destination and the agent’s Channels - Telephony, as described in Your own carrier.
