Get an invite

Server guide

For the person who runs a Twring server. People who only use the app don't need this. New here? Start with Self-hosting.

What you need

  • Linux on x86_64 or arm64, with Docker and the Docker Compose plugin. The installer never installs Docker for you.
  • Ports 80 and 443 reachable from the internet. A domain is optional: without one, the installer uses an sslip.io name for your public IP.
  • For your own call audio: 7881/tcp and 7882/udp reachable. Without them, calls use Twring's audio service (see Call audio).
  • A speech account key: Deepgram, or xAI.
  • An email address. Twring's ring service sends one confirmation link. If it isn't confirmed within 7 days, rings pause, and so do calls on servers that use Twring's audio service.
  • Node.js 20 or newer, only if you want the installer to link the agents on this machine.

Install

As root, or with sudo in front of sh:

curl -fsSL https://twring.com/install.sh | sh

Let it ask for your email and speech key: the key is hidden as you type, and neither answer reaches your shell history. To answer ahead of time with sudo, export the settings and keep them with -E:

export TWRING_EMAIL=you@example.com
export TWRING_SPEECH_KEY=your-deepgram-key   # and TWRING_SPEECH_PROVIDER=xai for an xAI key
curl -fsSL https://twring.com/install.sh | sudo -E sh

Never write sudo TWRING_SPEECH_KEY=... sh: values on a command line can be seen by other users of the machine and land in shell history. Exported keys stay in your shell until you close it or run unset TWRING_SPEECH_KEY.

Other settings, all optional: TWRING_DOMAIN, TWRING_NEWS (yes or no), TWRING_AUDIO (auto, own or twring), TWRING_LINK_AGENTS (yes or no), TWRING_AGENT_USER, TWRING_SHARE_AGENTS (yes or no, default no: see Sharing agents), TWRING_VERSION, and for sandboxes TWRING_PUBLIC_URL, TWRING_LISTEN_PORT (default 8080) and TWRING_TRUSTED_PROXIES. Add --yes (sh -s -- --yes) to ask nothing.

The installer checks the server image and the installer kit against the published checksums, writes its settings to /opt/twring, keeps keys in the twring data volume, installs the twring command, starts the server and shows an admin code to scan with the Twring app (in the app update that connects to your own server, coming soon).

Agents are linked as a person, never as root: the user named in TWRING_AGENT_USER, else the user who ran sudo. After a root login with --yes, linking is skipped; run twring link --user <name> later. A machine links to one server at a time: linking its agents to your own server replaces that machine's link to Twring's service.

Sandboxes

In a cloud sandbox, give the public address the sandbox publishes for your port:

export TWRING_PUBLIC_URL=https://abc123.sandbox.example.dev TWRING_LISTEN_PORT=8080

Calls then use Twring's audio service. The server does not trust proxy headers by default, because a published port can sometimes be reached directly and callers could fake their address. If your sandbox always sits behind a known proxy, set TWRING_TRUSTED_PROXIES to its addresses so per-person limits see real addresses; otherwise limits apply to the whole server.

Ports and firewalls

  • 80/tcp: the HTTPS certificate and redirect.
  • 443/tcp: the app, chats and files.
  • 7881/tcp and 7882/udp: call audio, when your server carries it.

Open them in your cloud provider's firewall (security group, or the networking tab) and on the machine:

# ufw
ufw allow 80/tcp && ufw allow 443/tcp && ufw allow 7881/tcp && ufw allow 7882/udp
# firewalld
firewall-cmd --permanent --add-port={80,443,7881}/tcp --add-port=7882/udp && firewall-cmd --reload

Call audio

  • Your server: call audio runs on 7881/tcp and 7882/udp and goes only between your server and the phones.
  • Twring's audio service: call audio passes through Twring, encrypted in transit, and is never stored. Twring counts minutes, with daily limits, and these calls need the ring service (a confirmed email, and later the yearly charge).
  • Automatic (the default): at install, Twring's ring service checks your server's address. Audio ports open: your server. Closed: Twring's audio service. HTTPS on 443 is needed either way.

twring audio check tells you whether phones can reach your audio. twring audio check --full also checks 7882/udp, and stops call audio for about 10 seconds while it does: don't run it during a call.

The audio choice is made at install. Changing it means uninstalling and installing again, which deletes people, phones, chats and keys and registers the server again with a new email confirmation. Usually it's simpler to open the ports and keep what you have.

The twring command

  • twring status: is it running, its address, call audio, and whether the ring service is active.
  • twring pair [--admin]: a code for a teammate's phone (--admin: a new admin phone).
  • twring people: people and their phones.
  • twring people remove <id> [--purge]: remove someone (--purge: also delete all their data).
  • twring link [--user <name>] [--shared]: link this machine's agents (--shared: let people you add use them too; read Sharing agents first).
  • twring register: register this server again with Twring's ring service (asks for the email again), when it is no longer registered.
  • twring audio check [--full]: can phones reach call audio.
  • twring update: the newest version, rolling back by itself if it fails.
  • twring backup [file] and twring restore <file>: encrypted backup and restore.
  • twring logs, twring start, twring stop.
  • twring uninstall [--keep-data]: remove Twring.

Update and roll back

twring update pulls the newest checked image for your version track, keeps copies of compose.yml, install.conf and your data, starts the new version and checks it. If the check fails, it puts the old version back. The server stops briefly while it updates, so calls in progress drop: update when nobody is on a call. The copy of your data is removed afterwards, whether the update worked or was rolled back. Update the server with twring update before anyone on it switches to Twring's service in the app: older servers keep ringing iPhones that switched away.

Backup and restore

twring backup /root/twring.tar.enc writes an encrypted backup of the data and settings, plus a check file ending in .hmac. It asks for a passphrase (or reads TWRING_BACKUP_PASSPHRASE). Keep both files and the passphrase: without it the backup can't be opened. The server stops briefly during a backup, so calls in progress drop. twring restore <file> checks the backup before changing anything.

Moving to a new machine: restore the backup on the new machine, then on the old one run twring uninstall --keep-data and remove its data by hand (docker volume rm twring_twring-data). Don't run a plain twring uninstall on the old machine: both machines share one registration with Twring's ring service, and it would delete it for the new one too. If that happened, run twring register on the new machine.

Removing people and phones

  • twring people remove <id> removes the person and their phones, computer links and rings at once. Their chats and settings stay on the server until purged.
  • twring people remove <id> --purge also deletes all their data. An admin can do the same in the app (coming with the app update).
  • A server always needs one admin. If the last admin deletes their own data, run twring pair --admin for a new one.
  • A lost or stolen phone: on the server run twring people, then twring people remove <id> for that person (or remove just the phone in the app from another admin's phone). Their calls end and the phone is signed out at once. If it was the only admin's phone, run twring pair --admin on the server for a new admin phone first.

Sharing agents

Agents are not shared unless you say so: the installer asks after your phone pairs (the answer is no unless you type y), and twring link --shared shares them later. A shared link makes every agent that machine offers visible to everyone on your server.

Think before sharing. A shared agent runs as the login that linked it. Anyone you add can ask it to read files and to use anything it can use without asking first, as that login: your files, saved passwords and keys (SSH, cloud), and Twring's own link on that computer. Approval prompts from others are declined, but an agent set to act without asking never prompts.

  • For shared agents, use a separate login on the computer made just for them, with no SSH or cloud keys and none of your personal files.
  • Each person gets their own conversation, but the agent's own memory lives on its computer and is shared: anything someone tells it may be remembered and come up for others.
  • Whoever runs the computer can read every person's conversations with its agents, stored on that computer.
  • If a computer's link is opened from somewhere else, its owner gets a message in Twring. If that wasn't you, run twring link again.

Tell your team.

Keys

  • The server key, in the data volume, is your server's identity with Twring's ring service. If it is lost, the server has to register again, with a new email confirmation.
  • Changing CORD_CREDENTIALS_KEY makes stored agent and speech keys unreadable (enter them again) and starts everyone on new agent conversations.
  • twring.env can be read only by root. Don't paste its contents anywhere.

Removing Twring

twring uninstall asks Twring's ring service to delete everything it keeps for your server (phones, counts and call records), then removes the server and all its data. If the ring service can't be reached, it says so: write to support@twring.com with your server's address and we'll delete them. twring uninstall --keep-data only stops the server. If you moved this server to a new machine, see Moving to a new machine first.

When something doesn't work

  • Ports 80 or 443 already in use: another web server (nginx, Apache, Caddy) holds them. The installer names it and stops; stop it (for example systemctl stop nginx) and run the installer again, or install sandbox-style with TWRING_PUBLIC_URL.
  • Calls connect but there's no sound: the audio ports are closed somewhere (cloud firewall or the machine). Run twring audio check --full when nobody is on a call, then open 7881/tcp and 7882/udp.
  • Phones don't ring when locked, or calls are refused: confirm the email Twring's ring service sent at install (check spam). Rings, and calls through Twring's audio service, pause 7 days after install until it is confirmed.
  • "This server is no longer registered with the ring service" in twring logs: its registration was deleted, usually by twring uninstall on a machine it was moved from. Run twring register, then confirm the email.
  • Call minutes look wrong with Twring's audio service: minutes are counted by Twring; there's nothing to set on your server. Write to support.
  • Anything else: twring logs, then support@twring.com.