Skip to content
Report Bugs Join the Community Ask Questions

Basic Setup

This is a step-by-step guide on VoIP setup at home or at the office. For calls to the PSTN you will need to have a sip provider like or



This tutorial assumes the following:

  • Two SIP phones connected to the same LAN
  • A fresh installation of Routr
  • SIP providers such as or

Setting up the Server

A set of sample configuration converting this scenario can be found at basic sample files. You might overwrite the files in the config folder if you wish to skip this section.

Configuring the Gateway

To configure the Gateway you must consult your sip provider and obtain the credentials and registration host. The key fields for the configuration are metadata.ref, and spec.regService.credentials. Here is an example:

- apiVersion: v1beta1
  kind: Gateway
    name: Provider Inc
        username: 'youruser'
        secret: 'yoursecret'
      transport: udp

Configuring the DID

To configure your DID or virtual number, you must open and edit the file config/dids.yml. Notice in the example below, how your reference the Gateway by using the field metadata.geRef. The key field while configuring DIDs are spec.location.telUrl and spec.location.aorLink. Keep in mind that the value in spec.location.telUrl must be formatted exactly as sent by the provider.

- apiVersion: v1beta1
  kind: DID
    gwRef: gweef506
      city: Columbus, GA
      country: USA
      countryISOCode: US
      telUrl: 'tel:17066041487'
      aorLink: 'sip:1001@sip.local'

Creating a new Domain and EgressPolicy

Routr is a Domain centric Sip Server. A Domain is used to group several Agents in the same context. The Domain URI can be an arbitrary name but we recommend using a fully qualified domain name (FQDN). You will also need to setup and EgressPolicy to allow calls outside the Domain. Here is how the file config/domains.yml needs to look like:

- apiVersion: v1beta1
  kind: Domain
    name: Local Office
      domainUri: sip.local
        rule: .*
        didRef: dd50baa4

Creating the Agents

We will now create the Agents 1001 and 1002. Keep in mind that field spec.credentials.username can be alphanumeric, so john or john001 is also acceptable.

Pay close attention to the credentials block since it contains the username and secret for both Agents.

- apiVersion: v1beta1
  kind: Agent
    name: John Doe
      username: '1001'
      secret: '1234'
    domains: [sip.local]
- apiVersion: v1beta1
  kind: Agent
    name: Janie Doe
      username: '1002'
      secret: '1234'
    domains: [sip.local]

To verify your configuration, start the server by issuing the command routr. In a separate window use the following commands:

  • rctl get gateway
  • rctl get did
  • rctl get domain
  • rctl get agents

Your output should be as follows:

Starting the Server

Verifying the Configuration

Configuring the Sip devices

We are using "Telephone" for this example. You might use any softphone you wish, just keep in mind that the configuration will look slightly different.

Configure your softphone using the information you gather in the last step. Start by completing only the required information: username, domain, password. Also, In the advanced section use the server's IP as your Registry Server and Proxy. Here is how mine looks like:

Make sure to check the box "Use this account" to register your device

If everything went well we just need to confirm that both softphones have registered correctly. Conveniently you can use the .rctl locate to obtain a list of "online" devices. This may seem like a lot of information. But what's relevant here is that both 1001 and 1002 are present in the location service and therefore can reach each other.

Making calls

This is a pretty easy step. If everything went well you will be able to call devices inside and outside your domain. Simply use the destination URI (eg.: 1001@sip.local or 7853178060@sip.local).

What’s Next?

You can check out the wiki to see more examples. If you have any questions start an issue or contact us via: