TerminalPhone

Encrypted push-to-talk voice communication over Tor hidden services.

TerminalPhone is a single, self-contained Bash script that provides anonymous, end-to-end encrypted voice and text communication between two or more parties over the Tor network. It operates as a walkie-talkie: you record a voice message, and it is compressed, encrypted, and transmitted to the remote party as a single unit. You can also send encrypted text messages during a call. No server infrastructure, no accounts, no phone numbers. Your Tor hidden service .onion address is your identity.

---

Table of Contents

• Features
• Installation
  • Linux
  • macOS
  • Termux (Android)
• Quick Start
• Usage
  • Menu Options
  • In-Call Controls
  • CLI Mode
• How It Works
• Security Model
• Configuration
• Troubleshooting
• License

---

Features

• Walkie-Talkie Push-to-Talk Mode -- Record a complete voice message and transmit it on release.
• In-Call Encrypted Chat -- Send and receive encrypted text messages during a call. Press T to type a message.
• Caller ID -- Both parties automatically exchange .onion addresses on connect. The remote address is displayed in the call header.
• Auto-Hangup Detection -- When one party hangs up, the other is notified immediately and the call ends automatically.
• Configurable Cipher -- Choose from 21 curated ciphers ranked by strength (256-bit → 128-bit). Includes AES, ChaCha20, Camellia, and ARIA families. Weak ciphers (DES, RC4, ECB modes) are excluded.
• Live Cipher Negotiation -- Both parties exchange cipher information on connect. The call header shows both local and remote ciphers with green (match) or red (mismatch) indicators, updated in real time.
• Mid-Call Settings -- Press S during a call to access settings. Change your cipher on the fly; the remote party's display updates automatically.
• Snowflake Bridge Info -- When using Snowflake for censorship circumvention, the call page displays the bridge descriptor name, fingerprint, and transport connection status parsed from Tor's logs.
• Auto-Listen -- When enabled, a background listener starts automatically when Tor boots. Incoming calls are detected and accepted from the main menu without needing to manually select "Listen for calls". After a call ends, the listener restarts.
• Configurable PTT Key -- Change the push-to-talk key from the default spacebar to any key via the Settings menu.
• Message Stats -- The call screen displays the encrypted payload size for sent and received messages, updated in-place.
• Remote PTT Status -- The call screen shows a static indicator for the remote party's state: "Idle" (green) or "● Recording" (red). Resets immediately when audio data arrives, before playback begins.
• PTT Chime -- Optional notification sound when the remote party starts recording. Five built-in presets (tone, double, chirp, ding, click) generated with sox, plus the ability to record a custom 2-second chime. Configurable via Settings.
• Connecting Animation -- When calling a remote address, a cycling animation plays until the call interface loads.
• Voice Changer -- Apply voice effects to outgoing audio. Includes 6 presets (deep, high, robot, echo, whisper) and a fully configurable custom mode with pitch shift, overdrive, flanger, echo, highpass filter, and tremolo. Effects are processed using sox before Opus encoding.
• Volume PTT (Termux) -- Experimental mode that lets you double-tap the Volume Down button to toggle recording, even when Termux is in the background. Requires jq (installed on demand). Volume is automatically restored after each trigger.
• Tor Hidden Service -- Each instance runs its own Tor hidden service. Your .onion address serves as a permanent, routable endpoint. No port forwarding or public IP required.
• End-to-End Encryption -- All audio and text is encrypted using a configurable cipher (default: AES-256-CBC) with PBKDF2 key derivation from a pre-shared secret before entering the Tor network.
• Passphrase-Protected Secret -- The shared secret can be encrypted at rest using a user-chosen passphrase (AES-256-CBC, 100,000 PBKDF2 iterations). Existing plaintext secrets are automatically detected with an offer to migrate.
• Low Bandwidth -- Opus codec at 16kbps, 8kHz mono. A typical 10-second voice message is under 20KB, well within Tor's capacity.
• QR Code Sharing -- Option 3 can display your .onion address as a scannable QR code in the terminal. If qrencode is not installed, you are prompted to install it. The QR code renders on the alternate screen buffer and is destroyed when dismissed. A note warns that some QR scanners auto-prepend http://; this prefix is automatically stripped when dialing.
• Opaque Temporary Files -- All temp files use generic .tmp extensions and random hex identifiers. No file type or timing metadata is leaked to the filesystem.
• Circuit Hop Display -- Opt-in display of your Tor circuit path during calls, showing relay names and full country names. Auto-refreshes every 60 seconds. Configurable via Settings → Tor Settings.
• Exclude Countries -- Exclude specific countries from your Tor circuits. Presets for Five Eyes, Nine Eyes, and Fourteen Eyes alliances, or enter custom country codes. Uses ExcludeNodes with StrictNodes in the torrc.
• HMAC Protocol Authentication -- Optional HMAC-SHA256 signing of all protocol messages (voice, text, control signals) using the shared secret. A random nonce is included per message, and seen nonces are tracked to reject replays. Unsigned, forged, or replayed messages are silently dropped. HMAC state is frozen at call start to prevent mid-call desync. Configurable via Settings → Security.
• Overwrite Before Delete -- Optional toggle in Settings → Security that overwrites every temporary file with random data from /dev/urandom before deletion. The file size is read, that many bytes of random data are written over the file with dd using conv=notrunc, the write is flushed to the storage device with sync, and then the file is removed with rm. Covers all sensitive runtime files: raw PCM recordings, Opus-encoded audio, encrypted payloads, decrypted inbound audio and chat, voice effect intermediaries, cipher and HMAC key material, nonce logs, session flags, PID files, named pipes, Tor hidden service keys on rotation, and relay session data. For directories, all files inside are overwritten recursively. A built-in test option creates a sample file, shows the original content in plaintext and hex, overwrites it, and displays the overwritten hex so the user can visually confirm the data is destroyed. Off by default — for most users, standard rm is perfectly fine. TerminalPhone's temp files are small and short-lived, and the disk space is typically reused quickly by normal system activity. This feature is for users who want an extra layer of protection against forensic recovery. Note: on SSDs and flash storage, wear leveling means the overwrite may land on different physical NAND cells — full-disk encryption is the only reliable defense on flash media. On traditional HDDs, the overwrite replaces data at the same physical location and is effective against all software-based recovery.
• Relay Mode (Group Bridge) -- Run a zero-knowledge relay that bridges N anonymous callers. The relay forwards encrypted audio and chat without decrypting, requires no shared secret or audio hardware. Clients auto-detect relay mode via RELAY:1 handshake and display live group caller count. One caller leaving does not disconnect others. Operator dashboard shows caller count, uptime, and data throughput.