# 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

| 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](https://docs.voicelogica.ai/telephony/your-own-carrier/) - **Public IP PBX** |
| A SIP carrier (Yuboto, Telnyx, Twilio...) | [Your own carrier](https://docs.voicelogica.ai/telephony/your-own-carrier/) - **VOIP provider** |
| Registers to us (the PBX dials out) | [Your own carrier](https://docs.voicelogica.ai/telephony/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

1. The device keeps a control connection to `calls.voicelogica.ai` over **TCP 443** (secure WebSocket).
2. It brings up a **WireGuard** tunnel to Voice Logica over **UDP 51820**. SIP and call audio travel inside that tunnel.
3. 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

Send this list to whoever runs the site firewall **before** install day.

1. An **always-on machine** on the same network as the PBX: a Windows PC, a Linux box or Raspberry Pi, or a virtual machine. Not a laptop that sleeps or leaves the office.
2. **Outbound TCP 443** to `calls.voicelogica.ai`. The name must resolve - DNS filtering that blocks our domain stops enrollment.
3. **Outbound UDP 51820** to `calls.voicelogica.ai`. Without it the device shows online, and calls have no audio.
4. **All UDP both ways** between the device and the PBX. A rule for port 5060 alone is not enough - audio uses changing ports.
5. **No inbound ports**, no port forwarding, no public IP.

Full network sheet for IT: [network requirements](https://voicelogica.s3.eu-north-1.amazonaws.com/edge/network-requirements.html).

## 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** 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.

  <ShotPlaceholder
    src="/assets/telephony/edge-devices.png"
    name="edge-devices"
    alt="PBX Edge Devices list with state, online and PBX columns"
    capture="PBX Edge Devices list."
  />

In **Add Edge Device**, give it a **Site label** (the office name, for example "HQ Office"), pick the **Platform**, then choose **I'll set it up now** or **Email the steps to the customer**. The main button changes to match.

<Tabs>
<TabItem label="Windows">

1. Pick **Windows** and click **Download installer**. The `.exe` is built for your company - the token is inside, nothing to type.
2. Copy it to the always-on Windows PC next to the PBX. Run it and accept the prompts.
3. 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:

```powershell
$env:EDGE_TOKEN='<token>'; irm https://calls.voicelogica.ai/install.ps1 | iex
```

Claude or ChatGPT hands you this line with the token already filled in - see [Or let Claude do it](#or-let-claude-do-it).

</TabItem>
<TabItem label="Linux / Raspberry Pi">

1. Pick **Linux / Raspberry Pi** and click **Get install command**.
2. Copy the line and run it on the Linux machine:

   ```bash
   curl -fsSL https://calls.voicelogica.ai/install.sh | sudo bash -s -- --token <token>
   ```

3. It needs `curl` and `sudo`. 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**.

</TabItem>
<TabItem label="Virtual machine">

1. Pick **Virtual machine** and click **Download appliance**.
2. The appliance page has the image for **VirtualBox**, **VMware** or **Proxmox** and the steps to import it.
3. Give the VM a network adapter **bridged** onto the PBX network, not NAT, so it gets an address on the same LAN.
4. Start the VM. Within a minute its console screen shows **Claim code** followed by a code like `7K2M-9QXR`.
5. On **PBX Edge Devices**, click **Add Edge Device**, pick **Virtual machine**, 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.

</TabItem>
</Tabs>

## Wait until it is online

The token ties the device to your company, so it is approved automatically. 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:

- **State** — **Pending** - just enrolled. **Approved** / **Active** - ready to use. **Revoked** - cannot be used; install a new one.
- **Online** — **Online** once the device holds its control connection.
- **PBX** — The PBX address the device is set to use, or **Not set**.

In the trunk drawer the pill changes from **Not connected** to **Live**, and **Next steps** appears. **Refresh devices** checks now.

> **Online is not the same as working:** **Online** only proves TCP 443. Audio needs the WireGuard tunnel on UDP 51820. When that port is blocked, the trunk drawer shows **Connected, but the tunnel is down (UDP 51820)**. Fix the firewall before you create the trunk.
## Connect the PBX

1. **Telephony - Trunks - + Add Trunk - Local IP PBX**

   Name the trunk after the site. If the device is already **Live**, the form unlocks right away.

2. **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.

3. **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.

4. **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.

5. **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.

6. **Destination, then Create Trunk**

   Point unrouted calls at your AI agent. **Create Trunk**. Registration should show online within a minute.

7. **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](https://docs.voicelogica.ai/telephony/your-own-carrier/) for numbers and default destination.

  <ShotPlaceholder
    src="/assets/telephony/edge-trunk.png"
    name="edge-trunk"
    alt="New SIP Trunk drawer, Local IP PBX with the connector Live and suggested PBXs"
    capture="Trunk drawer Local IP PBX, connector Live."
  />

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.

## Or let Claude do it

If you have [connected Claude or ChatGPT to Voice Logica](https://docs.voicelogica.ai/integrations/claude-chatgpt/), 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](https://docs.voicelogica.ai/integrations/claude-chatgpt/#connect-your-pbx-from-claude).

## Troubleshooting

**The device is online but calls have no audio**

The tunnel is down. The site firewall must allow **outbound UDP 51820** to `calls.voicelogica.ai`. 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:

1. The firewall between the device and the PBX passes **all UDP**, not only 5060.
2. On Linux, a default-deny host firewall drops audio. Run `ufw allow in on wg0` on the device.

**The device never comes online**

1. The installer finished and the machine is on (not asleep).
2. **Outbound TCP 443** to `calls.voicelogica.ai` is allowed.
3. The name resolves - DNS / web filtering often blocks new domains. Allowlist `calls.voicelogica.ai` and `voicelogica.ai`.
4. The Windows link (4 hours) or install token (72 hours) had not expired. If in doubt, generate a new one.

**Test now says No SIP response**

The IP or port is wrong, or the PBX ignores the 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 on the PBX's SIP / trunk settings.

**Claude says the PBX is not reachable, but the test works**

**PBX reachable** is a ping from the device. Many networks and PBXs block ping while SIP works fine. Trust **Test now** and the trunk's registration, not the ping.

**We have two PBXs on different networks**

One 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 on it.

**The trunk is registered but callers still reach nothing**

The PBX is not sending those calls to the trunk, or the number is not on this agent. Check the PBX routing, then [Your own carrier](https://docs.voicelogica.ai/telephony/your-own-carrier/) - default destination and **Channels - Telephony**.

## Next Steps

[Your own carrier](https://docs.voicelogica.ai/telephony/your-own-carrier/) - trunk types, numbers, default destination.  
[Claude and ChatGPT](https://docs.voicelogica.ai/integrations/claude-chatgpt/) - connect your PBX from a chat.  
[Routing](https://docs.voicelogica.ai/telephony/routing/) - when one number should land somewhere else.  
[Transfer](https://docs.voicelogica.ai/telephony/transfer/) - hand calls back to people on the PBX.