> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with pgw

> Run pgw on your own computer, connect your PBX and your app to it, and call the app while it is closed.

At the end of this page, you call extension `1001`, the app on your test phone is closed, and the phone rings anyway.

This is a test setup. pgw runs on your computer with a self-signed certificate, which only a debug build of your app accepts. When it works, [install pgw on a server](https://docs.pgw.sipmicro.services/deploy/install.md).

## Before you begin

You need:

* **A computer** on the same network as your test phone, with 64-bit Linux, macOS, or Windows.
* **Your PBX**, reachable from that computer, with a SIP account to test with. This page uses `1001`.
* **Push credentials for your app.** For iOS, an APNs key (`.p8` file) with its key ID and your team ID. For Android, a Firebase service account file. If you don't have them yet, see [iOS apps](https://docs.pgw.sipmicro.services/apps/ios.md) or [Android apps](https://docs.pgw.sipmicro.services/apps/android.md).
* **A debug build of your app** that accepts a self-signed certificate. A build from the App Store or Google Play won't connect in this setup.

The examples use an iOS app, `com.example.phone`, and a PBX at `192.0.2.10`. Use your own values.

## Step 1: Start pgw

**1. Download pgw**

Download the file for your system from the [download page](https://pgw.sipmicro.services/#download) into a new folder, and rename it to `pgw` (`pgw.exe` on Windows).

On Linux and macOS, make it executable:

```bash theme={null}
chmod +x pgw
```

macOS blocks files that a browser downloaded. Remove the block:

```bash theme={null}
xattr -d com.apple.quarantine pgw
```

**2. Create the starter files**

`pgw init` writes everything that pgw needs to start, with working defaults:

```bash theme={null}
./pgw init
```

```text theme={null}
Wrote .env, config.yaml, and tenant.yaml.
Keep .env out of version control: it holds the master key and the bootstrap token.

Next:
  1. Edit config.yaml and tenant.yaml: set your PBX, and uncomment your app.
  2. ./pgw serve
  3. In a second terminal: ./pgw bootstrap --name test
  4. ./pgw config sync tenant.yaml
```

| File | What it holds |
| - | - |
| `config.yaml` | Settings for pgw itself, such as its address and ports. |
| `tenant.yaml` | Your app and your PBX. You edit this file in step 2. |
| `.env` | Secrets: the key that encrypts stored credentials, and the token that creates the first tenant. |

**3. Check the address**

Open `config.yaml` and look at `hostname`. Your phone and your PBX reach pgw at this address, and `pgw init` filled in your computer's LAN address. If your computer has several addresses and this is the wrong one, correct it.

**4. Start the server**

```bash theme={null}
./pgw serve
```

pgw logs its startup and stays in the foreground:

```text theme={null}
time=2026-11-16T02:52:27.049+03:00 level=INFO msg=configuration file=config.yaml
...
time=2026-11-16T02:52:27.094+03:00 level=WARN msg="serving a self-signed certificate, which apps reject; set tls_cert_file and tls_key_file" cert_file=data/selfsigned.crt
```

The certificate warning is expected in this setup. pgw then logs `pgw ready` with the ports that it listens on: `5061` for apps, `5060` for the PBX, and `8080` for commands, which only this computer can reach.

**5. Create your tenant**

Leave the server running, and open a second terminal in the same folder. A tenant is your workspace in pgw, and it comes with an API key:

```bash theme={null}
./pgw bootstrap --name test
```

```text theme={null}
<api key>
pgw: saved PGW_API_KEY to .env
```

You don't need to copy the key. The other `pgw` commands read it from `.env`.

## Step 2: Add your app and your PBX

pgw needs two records: an app, so that it can send pushes with your credentials, and an upstream, which is pgw's name for a PBX. In this setup, both come from `tenant.yaml`.

**1. Add your app**

Copy your credential file into the folder. In `tenant.yaml`, under `apps`, uncomment the block for your platform and fill in your values:

```yaml theme={null}
apps:
  - platform: ios
    bundle_id: com.example.phone
    apns_team_id: ABCDE12345
    apns_key_id: ABC123DEFG
    apns_key_pem_file: AuthKey.p8
    apns_environment: sandbox
```

A debug build of an iOS app receives pushes only from Apple's `sandbox` environment, so keep that value for this test.

**2. Add your PBX**

Under `upstreams`, replace `<pbx-host>` with your PBX's IP address:

```yaml theme={null}
upstreams:
  - host: 192.0.2.10
    name: PBX
    transport: udp
```

If your PBX doesn't support the Path header, also uncomment `contact_strategy` and set it to `masquerade`. You can't change it later. The page for your PBX, linked in step 3, says whether the PBX needs `masquerade`.

**3. Apply the file**

```bash theme={null}
./pgw config sync tenant.yaml
```

pgw prints what it changed. A `+` marks a record that it created:

```text theme={null}
  + app ios/com.example.phone
  + upstream 192.0.2.10
+2 ~0 -0
applied
```

## Step 3: Point your PBX and your app at pgw

**1. Configure the PBX**

The PBX must accept registrations that arrive through pgw, and send the calls for those devices back to pgw. The settings differ for each PBX, so follow its page, then return here:

* [Asterisk](https://docs.pgw.sipmicro.services/pbx/asterisk.md)
* [FreeSWITCH](https://docs.pgw.sipmicro.services/pbx/freeswitch.md)

**2. Configure the app**

In your debug build, turn off certificate checks, because pgw's certificate is self-signed. Then add the SIP account. The account stays the same as before, except that the app now connects to pgw instead of the PBX:

| Field | Value |
| - | - |
| Username and password | The account at your PBX, such as `1001` |
| Domain | Your PBX's address, as in `tenant.yaml` |
| Transport | TLS |
| Outbound proxy | `sip:<hostname>:5061;transport=tls`, with the `hostname` from `config.yaml` |
| Push notifications | On |

## Step 4: Check that it works

**1. Check the registration**

```bash theme={null}
./pgw binding list
```

A binding is one registered device. The list shows one binding for `1001`, with `flow_alive` set to `true` while the app is connected.

**2. Close the app**

Swipe the app away. On Android, use **Recents**, not **Force stop**: Android delivers no pushes to an app that was force-stopped.

**3. Call 1001**

Call `1001` from another phone on your PBX. The test phone rings, and the call connects when you answer.

## If the phone doesn't ring

Work through these checks in order.

| Check | What it means | What to do |
| - | - | - |
| `./pgw binding list` prints `null` | The app never registered through pgw. | Make sure that the phone can reach the `hostname` on port `5061`, and that certificate checks are off in the app. |
| The binding exists, but the phone stays silent | pgw received the call and the push failed, or the PBX never sent the call to pgw. | Read the push log, below. An empty log usually means that the PBX didn't send the call to pgw, so check the PBX settings again. |
| The push log shows an error | Apple or Google refused the push. | Compare the bundle ID, the key, and `apns_environment` with your app's build. |

To read the push log, ask the API for the latest push events:

```bash theme={null}
export PGW_API_KEY="$(sed -n 's/^PGW_API_KEY=//p' .env)"
curl -s -H "Authorization: Bearer $PGW_API_KEY" http://127.0.0.1:8080/api/v1/push-events
```

The newest event comes first. A delivered call push has the type `call` and the status code `200`.

For other symptoms, see [Troubleshooting](https://docs.pgw.sipmicro.services/troubleshooting.md).

## Next steps

> [card] [Install pgw on a server](https://docs.pgw.sipmicro.services/deploy/install.md)
>
> Move from this test setup to a host that runs pgw under systemd.

> [card] [Install a TLS certificate](https://docs.pgw.sipmicro.services/deploy/tls.md)
>
> Replace the self-signed certificate, so that store builds of your app connect.

> [card] [Concepts](https://docs.pgw.sipmicro.services/concepts.md)
>
> Understand the records that you created, and the choices behind them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.