Shellbell

Your terminal rings. You answer.

Keep using your computer's shell from your phone. Leave a build, a deployment or a coding agent running, walk away, then read its output and respond in the same session. Your processes, working directory and shell stay on your computer.

Documentation · Self hosting · Contributing · Privacy · shellbell.dev

Continue where you left off

1. Run the computer service and pair your phone by scanning its temporary QR code and approving the phone on the computer.
2. Open an existing terminal session on your phone. Follow live output or scroll back through available history; switch to Reading mode for text. Claude Code and Codex sessions open as a Chat with their full history, after a one-time agent setup that the computer offers when it starts.
3. Send a command, type into an interactive program, or use keys such as Escape, Tab, arrows and Ctrl+C. Input goes back to that session on your computer.
4. Receive a notification when a command finishes, a session goes quiet or a supported coding agent needs attention. Open it to return to the terminal.

The phone and computer can use different networks. Both connect outward to a reachable relay, so the relay path needs no shared Wi-Fi, inbound computer port or manual SSH tunnel. The computer must remain awake, online and running the service. Notifications do not keep it awake or prove a quiet command has finished.

Screens, history, titles and input are end-to-end encrypted between paired devices. The relay routes ciphertext and sees connection and routing metadata; Privacy explains the boundary. Pairing grants control of the sessions that the computer's OS user exposes.

Local apps on Android

With Android Shellbell 1.2 and computer 0.17 or newer, open registered tools such as Sous from the computer's Apps tab, or tap a localhost link to preview a local web server. The computer serves the page over the encrypted direct route. Install the underlying application first; Shellbell's plugin browser enables its integration. See plugin setup, authoring and registry submissions. Apps is Android-only; existing supported phone/service combinations retain terminals and chat.

Terminals and shells

Integration	What you can continue from your phone
iTerm2	Existing tabs and panes through its native local API
tmux	Existing tmux panes, including those opened in Ghostty, Warp, Terminal.app, Alacritty, Kitty or WezTerm
Herdr	Terminal panes and supported coding-agent state through its local API

Shellbell works with the shell running inside a supported session, including zsh, bash and fish. Other terminal apps need their shell to run inside tmux; installing tmux alone does not expose ordinary tabs. These are the three built-in backend integrations, not separate native adapters for every terminal app.

The macOS service includes all three backends. The Linux headless path currently uses tmux. See backend behavior and limits and extension points.

Current source also offers new tmux or Herdr sessions in a selected Ghostty or iTerm2 window, including cold startup, and owner-enabled local adapters. See terminal adapters for prerequisites and remaining device qualification checks.

Connection and project status

Mobile connections negotiate a direct WebRTC data channel using encrypted relay signaling. Terminal traffic waits for the verified direct connection; if it drops, the terminal pauses while Shellbell retries. The relay never carries terminal data. The app shows the committed route and connection progress. Both WebSockets stay connected for coordination. Same-network Android/Mac tests have passed; the owner reports Fold 7 Wi-Fi/cellular recovery and successful iPad use through TestFlight. Wider device/network checks and independent security review remain part of launch qualification. See how connections work.

Shellbell is a public preview. GitHub Releases lists computer releases and mobile testing candidates. Each release names its architectures, channel and qualification limits. Mobile internal testing requires an invitation. Public mobile distribution is coming soon:

Store	Availability
App Store for iPhone and iPad	Invite-only testing
Google Play for Android	Invite-only testing

Visit shellbell.dev for downloads and setup.

The release checklist distinguishes implementation from qualified artifacts and devices. A Windows host service and Linux desktop app are not shipped.

Setup

Computer 0.10.0 includes the signed and notarized Apple silicon Mac app (build 33), the macOS headless package, and Linux ARM64/x64 archives. Install the CLI on Apple silicon macOS or Linux as your normal user, with its runtime included:

curl -fsSL https://shellbell.dev/install.sh | sh

The macOS CLI also remains available through npm with Node.js 22 or newer:

npm install -g shellbell@latest

See CLI setup for PATH, first start and optional background-service instructions. Installation does not start a service. The release includes checksums, installation notes and qualification limits for each artifact.

• macOS app and computer service
• Service installation and troubleshooting
• Linux headless archives
• Native Android and iOS builds
• Your own relay

Push delivery uses direct FCM on Android and APNs on iOS. Expo libraries remain in the app, but Expo's push service and cloud build service are not required. Building your own notification-enabled app requires matching app identities and provider credentials.

For contributors, use Node 22.23.1 and pnpm 11.12.0 from the repository root:

corepack enable
pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm test
pnpm build

Native prerequisites and additional checks are in CONTRIBUTING.md.

Your relay, your infrastructure

Run the relay in your own Cloudflare account or use the standalone Node/SQLite container on a server with private durable local storage. Authentication, pairing, revocation, queue limits and notification policy live in a shared core; Cloudflare and Node provide adapters for sockets, storage and scheduling.

• Cloudflare deployment
• Docker deployment and TLS with Caddy
• Organization operations
• Other runtime and database adapters
• WebRTC and relay capacity

A different stack can reuse the core or implement its protocol contracts. It still needs runtime, storage and recovery qualification. The supplied SQLite server uses one process and one writer; shared volumes and automatic migration from Cloudflare are not supported.

Set Relay address in the Mac app or run shellbell config set relay wss://relay.example.com on the computer, then restart its service. New pairing QR codes carry that address. Existing mobile computer records expose Relay URL in settings. Both endpoints must agree; an empty replacement relay may require pairing again. See device connection steps.

Maintainer

Shellbell is a solo project by Bilal. Contributions, feedback and thoughtful connections are welcome. I may be available to help pro bono with causes I believe in; contact me through my website.

Report suspected vulnerabilities privately using SECURITY.md.

Documentation, releases and licenses

The documentation index covers setup, architecture and operations. The versioning strategy gives computer, relay and mobile components their own release lines; Android and iOS share the mobile version. CHANGELOG.md tracks shipped changes when releases are prepared.

The apps and project's hosted service have Terms of Use. Privacy explains data handling and the limits of encryption.

The code is under the MIT License. Retain third-party notices, including xterm.js credits. The name and logo have a separate trademark policy; the brand kit contains the visual assets.