Get connected.
Keep your place.
Start with the question that matches what you see. These answers link to the installation and troubleshooting guides, with Apple and Google instructions where the stores handle access.
Install on both devices.
Computer downloads and the Android app are public. iPhone and iPad require a TestFlight invite.
How do I get the phone app?
Install Android from Google Play. For iPhone and iPad, request a TestFlight invitation with your Apple ID email address. Once invited, follow the TestFlight link on your device. A request does not grant immediate TestFlight access. You do not need Expo Go or a source build.
Follow the mobile installation guide. Apple explains TestFlight invitations.
Why can’t I access TestFlight?
Use your TestFlight invitation link and the invited Apple ID. Check that TestFlight is signed into that account. Contact us if the wrong account was invited. Android is publicly available on Google Play.
Which computer installation should I choose?
Use the Mac menu-bar app on Apple silicon with macOS 13 or newer. It bundles its runtime; Node and npm are not needed. Headless macOS can use the shared CLI installer, which includes its runtime.Linux uses a separate archive with a bundled runtime and requires tmux for sessions. A Windows host and an Intel Mac app are not shipped.
Choose a computer download, then follow the Mac app, headless macOS, or Linux guide.
macOS asks whether I want to open the app. Is that expected?
The official Mac app is signed and notarized. Download it from this site’s release link, drag it into Applications, and launch it there. A first-open confirmation is normal. A damaged-app or unverifiable-developer warning is different: check the download and report the exact message instead of disabling Gatekeeper. See Apple’s security guidance.
Why does a permission prompt name Shellbell?
Terminal mirroring does not need access to your personal folders or cloud storage. Connecting iTerm2 and enabling optional power controls have their own explained steps. Commands and developer tools running in a session can trigger additional macOS prompts; macOS may name the app responsible for launching the process, including Shellbell.
Deny unexpected access and check the command that triggered it. See the permission guidefor what Shellbell itself needs and how to change your choices.
Find your terminal.
Pairing, terminal access and a working network connection are separate steps.
The app is installed. How do I pair it?
Start Shellbell on the computer and open pairing. For a headless service, run shellbell pair. Scan the temporary QR in the phone app, then approve that phone on the computer. Allow camera access to scan. If the QR expires, generate a new one. Keep it private: it contains a temporary pairing secret.
Follow the first-connection walkthrough. A paired phone can control the sessions exposed by that computer’s OS user.
Why is my terminal missing from the list?
On macOS, enable a supported iTerm2, tmux or Herdr integration. Linux exposes local tmux sessions. An ordinary Ghostty or Terminal.app tab does not appear by itself; use tmux inside it, or a supported Herdr session. The computer must stay awake with Shellbell running.
For iTerm2, enable its Python API and connect it from Shellbell’s Terminals settings. Approve Shellbell’s access when asked; you do not need to allow every app. See the iTerm2 guide, iTerm2’s API permission documentation, and terminal setup.
Does TURN still carry terminal traffic?
Yes, when enabled and needed. TURN forwards the encrypted WebRTC connection between your devices; it does not receive the terminal decryption keys. This is separate from Shellbell’s coordination relay, which handles pairing, signaling and notification routing and never carries terminal screens, history or input.
TURN fallback is enabled by default. In the Mac app, open Settings → General → Allow TURN fallback, save changes, then restart the service when you are ready to reconnect. For a headless install, use shellbell config set turn off followed by shellbell service restart. Use on to enable it again. There is no separate phone setting. See TURN controls and tradeoffs.
It works at home but pauses on another network. What should I check?
Check that the computer is awake, its service is running, and both devices can reach the configured relay. Allow local-network access if the OS asks. Leaving TURN enabled helps some networks, but does not guarantee a connection: the computer’s TURN transport currently needs UDP. A network that blocks all UDP on the computer can still prevent terminal access.
Terminal data waits for the verified WebRTC connection. It does not fall back to the coordination relay. See connection troubleshooting.
Why can’t I see all the terminal history?
History depends on what the terminal integration can supply and what fits in the phone’s bounded memory. Scroll upward to request older available rows. Reading view wraps text for a narrow screen; Terminal preserves the terminal grid. A gap or replacement notice means earlier rows could not be preserved. Fit changes the phone presentation; it does not resize an existing computer window.
See terminal viewing and history. If the view moves while idle, include the view mode, terminal integration, and whether Terminal mouse changes it in your report.
The terminal works, but notifications don’t arrive.
Check the phone’s notification permission, Shellbell’s notification settings, and whether the session is open in the foreground. Push delivery is separate from terminal connectivity; a self-hosted relay also needs its own push-provider setup. See private notifications and diagnostics.
Update without starting over.
Keep your computer identity and pairings. An app update should not require a new identity.
Do the apps update automatically?
TestFlight and Google Play offer optional automatic updates for builds you can access. TestFlight builds expire after up to 90 days; an expired build needs an available replacement. See TestFlight and Google Play update settings.
The Mac app, Linux archives and headless service currently require a manual update. npm also requires an explicit update command; installing from npm does not create an automatic updater. See npm’s update instructions.
How do I update the Mac or headless service?
From computer 0.9.0, open Settings → General → Check for Updates in the Mac app. It checks on demand and offers release notes and an official installer. Follow the guide to stop remote access, quit the app and replace it. Check the helper instructions first if you registered the optional power helper.
On supported Linux archive installs and Mac CLI installations made with the shared installer from computer 0.10.0, shellbell update --check checks the latest computer release. Run shellbell update to confirm its download and installation. Running sessions keep their previous runtime until you explicitly update the service definition and start the new version. Old runtimes are kept for recovery.
Existing 0.8.0 installations need one manual upgrade to gain these controls. For the macOS npm CLI or a source install, use the original installation method and follow the service upgrade steps. Checks do not run in the background, and computer apps do not automatically download or install updates.
Keep the existing .shellbell identity, keys and pairings; do not run host init --new as an upgrade step. Follow the Mac app, macOS headless, or Linux update steps.
Still stuck?
Shellbell is independently maintained. Support is offered as time allows.
For installation or access questions, contact us. For a reproducible bug, open a GitHub issue with your OS, app version and build, terminal integration, steps to reproduce, and exact non-sensitive error. Review diagnostics and recordings before sharing; terminal output can contain private information.
Report suspected security issues privately through the security policy. Do not post pairing QRs, tokens, keys, or private terminal content in a public issue.
Ready for the first connection?
Install the computer service, accept your mobile invitation, and pair your devices.