Support

Find answers to common questions or get in touch

Getting Started

TermAway lets you access your Mac's terminal from your iPad, iPhone, or any browser on your local network. Here's how to get up and running:

  1. Install the macOS app — Download TermAway from the downloads page and open it on your Mac. It runs as a menu bar app.
  2. Start the server — Click the TermAway icon in your menu bar and start the server. It will display a local URL (e.g. http://192.168.1.x:3000).
  3. Connect from your device — Open the TermAway iOS app or visit the URL in any browser on the same network. Your terminal is ready to use.

Getting Started on Linux

TermAway's server also runs on Linux. Here's how to set it up:

  1. Download the Linux package — Get the latest .tar.gz from the downloads page.
  2. Extract and install — Run tar xzf TermAway-Linux-*.tar.gz && cd termaway-linux && sudo ./install.sh
  3. Start the server — Run sudo systemctl start termaway. The server starts on port 3000 by default.
  4. Connect from your device — Open the TermAway iOS app or visit http://your-linux-ip:3000 in any browser on the same network.

Access from anywhere with Tailscale

On your own Wi-Fi, TermAway works out of the box. To reach it from anywhere (a coffee shop, your phone on cellular), add Tailscale: a free private network (WireGuard) across the devices in your tailnet. TermAway itself stays on your Mac; nothing runs in a TermAway cloud. Tailscale connects your devices directly when it can, and relays end-to-end encrypted traffic through its own servers when a direct path isn't available. It cannot read that traffic.

  1. Install Tailscale on both your Mac and your iPhone or iPad, and sign in to the same account on each. It's free for personal use.
  2. Copy your Tailscale URL — open the TermAway menu bar app. It shows a Tailscale: http://100.x.x.x:3000 entry next to your LAN URL. Click to copy it.
  3. Connect from anywhere — paste that URL into the TermAway iOS app. As long as both devices are signed into Tailscale, you're in — no port forwarding, no public exposure.

Because your terminal is now reachable across your tailnet, set a password in the menu bar app so only you can connect.

Keep sessions running when the server stops

By default a session lives inside the TermAway server: stop the server, or restart your Mac, and the shells inside it end. Turn on persistence and each session runs inside tmux instead, so your work keeps running and TermAway reattaches to it the next time it starts.

  1. Install tmux on your Mac — brew install tmux. TermAway won't let you turn persistence on without it.
  2. Open Preferences in the menu bar app, go to Server, and switch on Keep sessions running when the server stops. The server restarts by itself.
  3. That's it. Stop the server, start it again, and your sessions are back with whatever was running still running.

One thing to expect: TermAway replays a session's recent output when you reconnect, and that buffer lives in the server, so it starts empty after a restart. Your processes and tmux's own history survive — you reattach to a live screen, not to a log of what happened before.

Switching persistence back off asks what to do with sessions tmux is still holding, so nothing is left running where you can't see it.

Frequently Asked Questions

Do my sessions survive restarting the server?

Only if you ask them to. Turn on Keep sessions running when the server stops in Preferences → Server and each session runs inside tmux, so stopping the server — or rebooting — leaves your work running. It needs tmux installed. See the section above.

Do I need an internet connection?

On your own Wi-Fi, no — TermAway runs entirely over your local network, with no internet or TermAway account required. To reach it from outside your network, add Tailscale (see above); traffic then flows over Tailscale's end-to-end encrypted network, with no TermAway cloud service in between.

Is my data secure?

TermAway is self-hosted, so your terminal data never passes through infrastructure we operate. Over Tailscale it's end-to-end encrypted (WireGuard); on your LAN you can enable TLS. You can set a password for server access, and TermAway is open source, so you can inspect the code yourself.

My device can't find the server

Make sure both devices are on the same Wi-Fi network, or both signed into Tailscale. Auto-discovery works on your LAN; over Tailscale, enter the Tailscale URL manually from the macOS menu bar app. Also check that your Mac's firewall isn't blocking incoming connections on the server port.

The terminal is not responding

Try detaching and reattaching the session, or creating a new session. If the server has restarted, existing sessions may have been cleared. You can also restart the server from the macOS menu bar app.

Which shells are supported?

TermAway uses your system's default shell (set in $SHELL). This is typically zsh on macOS and bash on Linux. Fish and other shells work as well — just change your default shell in System Settings (macOS) or via chsh.

Can I run the server on Linux?

Yes. TermAway's server runs on any Linux distribution with Node.js 18+. Download the Linux package from the downloads page and run the install script. The server runs as a systemd service and starts automatically on boot.

Can I use this outside my home network?

Yes, with Tailscale. No port forwarding or public TermAway URL is required: Tailscale reaches it over your tailnet's end-to-end encrypted network. See "Access from anywhere with Tailscale" above.

Reporting Issues

If you've found a bug or have a feature request, please open an issue on our GitHub Issues page. When reporting a bug, include:

  • What you were trying to do
  • What happened instead
  • Your macOS/Linux version and device model
  • The TermAway version (shown in the menu bar app)

Contact

If you need help or have questions that aren't covered here, you can reach us through: