Skip to main content
selfhostsms

Local server

Install the gateway on a machine on your own network, with no internet exposure: the address the phones dial, the .local name, guest wifi, Windows, access from outside and what it costs in availability.

This path installs the gateway on a machine you own, on your premises, on your own network. Nothing is published on the internet: no SMS, no contact and no log leaves the building.

In short, on the machine (Linux amd64 or arm64):

curl -fsSL https://sms-gateway.araylab.com/install.sh | sudo bash -s -- --lan --yes

On Windows, with Docker Desktop, in PowerShell opened as administrator (local network mode is the default there):

irm https://sms-gateway.araylab.com/install.ps1 | iex

At the end, the script shows the dashboard address and the setup code asked for by the account creation screen (sms-gateway setup-code shows it again as long as no account exists).

The full path (purchase, key, first account, activation, pairing) is in Installation. This page focuses on the one point that can fail silently on this path: the address through which the phones reach the gateway.

1. What you gain, and what you accept

What you gain What you accept
No data outside your network The service stops with the building: power, internet box, machine
No hosting cost No automatic failover: one machine, one database
Phones and server side by side Phones must be on the same network as the machine
No dependency on a third party, apart from the license check Traffic is not encrypted on your local network, dashboard session included

2. What --lan sets for you

Setting Value Why
Public address (GATEWAY_PUBLIC_URL) http://<machine-name>.local:8080 This is the address written into the pairing QR codes. See section 3
Listening (GATEWAY_BIND) 0.0.0.0: every network interface Phones and computers of the network must reach the gateway
GATEWAY_INSECURE_COOKIES true Without it, signing in to the dashboard fails over HTTP. See section 4
HTTPS server Off No certificate can be obtained without a public domain name

On Linux, the script also installs avahi-daemon, which announces <machine-name>.local on the network. --port <n> changes the port if 8080 is taken (default 8080); the port is then part of the address in the QR codes. All the options and their defaults are in Installation.

Understand what you are opening: the port answers in plain HTTP to every device of your network. Accounts and API keys still protect everything, except the short link redirects (/l/...) and the health checks (/health, /ready), which are public by nature. Your local network becomes the security boundary of the installation.

3. Why a .local name, and not an IP address

The public address is the only source of two things: the address written into the pairing QR code, and the base of your short links. It is read when the gateway starts, and cannot be changed from the dashboard.

The Android app, for its part, refuses unencrypted connections, except to:

  • names ending in .local, such as gateway.local;
  • localhost and 10.0.2.2 (only useful for testing on an emulator).

The consequence is counter-intuitive: a private IP address such as http://192.168.1.20:8080 is refused by the phone, however good the network is. That is why the installer uses the machine's name followed by .local.

Public address Dashboard from a computer on the network Android phone
http://localhost:8080 From the machine itself only No: the phone would call itself
http://192.168.1.20:8080 No: the gateway refuses to start with a plain-HTTP address that is not .local No: refused by the app
http://gateway.local:8080 (what --lan sets) Yes, if the name resolves Yes, if the name resolves. Check it, see section 6
https://sms.example.com Yes Yes, from anywhere

4. GATEWAY_INSECURE_COOKIES=true, and what it costs

This setting changes only one thing: it lets browsers keep your dashboard session over plain HTTP. Without it, the page displays but signing in fails with no clear message, because browsers only send a protected session cookie back over HTTPS.

The price: the session travels unencrypted on your network. Anyone able to capture that traffic could take over an open session. That is acceptable on a company network you control, not on a shared network. On a network you do not control, prefer domain mode.

Do not confuse it with GATEWAY_DEV, a development setting that would also weaken the license checks: it is never needed, and the installation does not pass it to the gateway.

5. Keep the machine name stable

<machine-name>.local is written into every pairing QR code, and the phone keeps it. If the name changes, paired phones can no longer find the gateway. Choose it before installing:

sudo hostnamectl set-hostname gateway

The IP address, on the other hand, can change without breaking anything, since the phone looks the name up at every connection. A DHCP reservation on your router (a fixed address for the machine) is still good practice: it makes troubleshooting easier.

6. Check from the phone itself

The test that matters is done from the phone, not from the machine. On the phone, connected to the office wifi, open in the browser:

http://gateway.local:8080/health

A {"status":"ok","version":"..."} answer means the phone finds the gateway: pairing will work. If the page does not open, no phone will pair. Possible causes, in order:

  1. The phone is on another network (4G, guest wifi). See section 7.
  2. The .local name does not resolve. On Linux, check that avahi-daemon is running (systemctl status avahi-daemon). Some routers and access points filter these announcements.
  3. A firewall on the machine blocks the port from the local network.

If you type the address by hand in the app instead of scanning the QR code, type it in full: http://gateway.local:8080. Without http://, the app assumes an encrypted connection, which fails on this path.

7. Guest wifi and device isolation

Many company networks, and most guest networks, isolate their devices: each one reaches the internet, but none reaches the others. On such a network, the phone shows a perfect connection and will never reach the gateway. The test in section 6 reveals it.

Three ways out, from the most to the least robust:

  1. Put the phones on the internal network, the one the computers use. The right answer in almost every case.
  2. Create a dedicated wifi network without isolation, reserved for the gateway's phones.
  3. Disable isolation on the existing network, which affects all its devices: discuss it with whoever manages it.

8. On Windows

  • The script opens the gateway's port in the Windows firewall for private networks only. If Windows considers your network public, phones cannot connect: set the network profile to Private in the Windows network settings.
  • The address uses the computer's name (<COMPUTERNAME>.local). Whether Windows answers for that name on your network depends on its version and configuration: run the test in section 6.
  • The gateway runs only while Docker Desktop runs: set Docker Desktop to start with Windows, and keep the computer on and out of sleep.

9. Access from outside, if you need it

This path needs no exposure. If you want to open the dashboard outside the office, call the API from another site, or use phones outside the local network, switch to domain mode:

  1. A domain name pointing at your site's public address (fixed, or kept up to date by a dynamic DNS service).

  2. Forward ports 80 and 443 from your internet box to the machine.

  3. Run the installation again with --domain:

    curl -fsSL https://sms-gateway.araylab.com/install.sh | sudo bash -s -- --domain sms.example.com --yes

    The public address becomes https://, GATEWAY_INSECURE_COOKIES goes back to false, the port is closed to the local network, and the certificate is obtained automatically. Your data is kept.

  4. Pair the phones again. Phones already paired keep the old .local address.

The certificate requires ports 80 and 443 reachable from the internet: without port forwarding, domain mode cannot obtain one.

10. Availability

The gateway is a single program with a single database: no cluster, no replica.

What is covered. The gateway restarts on its own after a crash and after a reboot of the machine, unless you stopped it yourself.

What is not. A gateway that runs but misbehaves is reported as unhealthy in sms-gateway status, but it is not restarted automatically: run sms-gateway restart.

During an outage, messages are not lost. Phones keep outgoing and incoming messages in their own queue and hand them over when the gateway comes back. An SMS received while the server is off is kept on the phone.

Power. A sudden power cut does not corrupt the database, but it may lose the last few seconds of writes. A small UPS removes that risk.

Backups, from day one. The gateway backs up its database automatically every night (03:00 in the platform time zone by default, Settings > Backup and export), on the same machine. Copy a backup outside the building regularly, a downloaded copy or a sms-gateway backup archive: a backup stored next to the machine does not survive a fire or a theft. See Backup and restore.

11. The master key

At the first start, the gateway creates a master key, secret.key, in its data folder. It protects the secrets of the paired phones, the webhook secrets and your stored license key. Losing it means pairing every phone again and entering the license key again. The sms-gateway backup archive contains it, together with the database: store that archive accordingly.

Further reading

Search the documentation

Type a few words, then pick a page.