Getting Started

Sign in on your phone, install the desktop app on your computer, and scan the QR code it displays — connected. No terminal commands, no passwords on desktop, no SSH keys, no VPN.

How it works

The RemoteAI desktop app runs on your computer and connects to a secure cloud relay over WebSocket (TLS). Your phone connects to the same relay to reach your terminal. The desktop app manages tmux sessions, installs notification hooks for your AI tools, handles OAuth interception, and bridges terminal data to your phone. All traffic is encrypted in transit.

Prerequisites

  • A Mac or Linux computer you want to control
  • iPhone (iOS 13+) or Android device with the RemoteAI mobile app installed
  • At least one AI coding tool installed: Claude Code, Gemini CLI, or Codex CLI

Setup Guide

Step 1: Create your account on mobile

Open the RemoteAI mobile app and sign in with Apple, Google, or email. Your account holds the identity for everything — desktop apps you link later all sign in through this account.

Step 2: Download the desktop app

From the mobile onboarding screen, or from this site's download section, install the RemoteAI desktop app on your computer:

  • macOS — Universal binary (Intel + Apple Silicon), macOS 13+
  • Linux — x64, available as .deb or AppImage

Step 3: Open the desktop app — it shows a QR code

Launch RemoteAI on your computer. Instead of a sign-in form, the desktop displays a QR code and a 6-digit code — there's no password to remember, and no Apple/Google/email button to click on the desktop. The desktop is paired entirely from your phone.

Step 4: Scan the QR with your phone to link

In the mobile app, tap Scan QR Code on the onboarding screen (or open Settings → Linked Desktops → + at any time). Point the camera at the QR. A confirmation sheet appears showing the desktop's hostname, OS, and approximate location. Tap Approve — the desktop transitions into the terminal screen within a second or two.

Prefer typing? Tap Enter code manually on the scanner to punch in the 6-digit code instead.

Codes are short-lived. Each QR / code expires after 5 minutes and is one-time use. If a code expires, the desktop generates a new one automatically.
Once linked, the desktop sets itself up automatically. Notification hooks for Claude Code / Gemini CLI / Codex CLI, OAuth interceptor, auto-launch at login, and tray-icon background mode are all installed without any terminal commands.

Step 5: Start a session

Tap + in the header to open a new session. Pick a session type — Claude, Gemini, Codex, or plain Shell — then name it. The app creates a session on your computer and drops you into a shell. Use the floating action button to quickly launch your AI tool.

Apps

Desktop App

The desktop app is a lightweight tray application that bridges your computer with the mobile app.

Dashboard

  • Connection status — shows relay connection state and how long you've been connected.
  • Mobile peer indicator — shows when your phone is connected to a session.
  • Active sessions — lists all running sessions with the detected AI tool type (Claude, Gemini, Codex, or Shell), last activity time, and which device is attached.
  • New Session — create a new terminal session.

System tray

The app minimizes to the system tray. Right-click (or left-click on macOS) to access:

  • Connection status
  • Sessions list — click any session to open it in a terminal
  • Open Window / Open Terminal / Quit

Settings

  • Account — shows the email this desktop is linked to and a Sign Out button. Account deletion lives in the mobile app (mobile owns the account; desktops are revocable peers).
  • Connection — relay status and relay token (tap to copy).
  • Hooks — shows installation status for Claude, Gemini, and Codex notification hooks. Install CLI tools or reinstall hooks individually.
  • Auto-Launch — toggle whether RemoteAI starts automatically when you log in.
  • About — app version, update check, and log file location.

Notification hooks

The desktop app installs small hooks into each AI tool's configuration so they can notify your phone when events happen:

  • Claude Code — hooks added to ~/.claude/settings.json (Stop and Notification events)
  • Gemini CLI — hooks added to ~/.gemini/settings.json (SessionEnd and Notification events)
  • Codex CLI — notify script added to ~/.codex/config.toml

These hooks detect task completion, attention requests, and usage limit events, then forward them to your phone as push notifications.

OAuth interception

When an AI tool tries to open a browser for authentication (e.g. claude login, gemini auth), the desktop app intercepts the URL before the browser opens and pushes it to your phone instead. You authenticate on your phone, and the callback is relayed back to the AI tool on your computer. Supported providers: Anthropic, Google, and OpenAI.

Continue on Computer

When you tap Continue on Computer on your phone, the desktop app receives the request and opens the session in your native terminal emulator automatically — no manual commands needed.

Mobile App

Everything the RemoteAI app can do.

Terminal tabs

Each tab is an independent session on your computer. Sessions survive connection drops and app restarts — close the app, reopen it, and your session is exactly where you left it.

  • Tap + to open the session picker.
  • Swipe left or right on the terminal to switch tabs.
  • Tap × on a tab to close it in the app. The session keeps running on your computer.

Input bar & image attachments

A text field at the bottom lets you compose and send commands. Tap the paperclip icon to attach images — useful for sharing screenshots or designs with your AI tool.

Keyboard toolbar

When the keyboard is open, a toolbar appears with keys iOS doesn't provide natively: Esc, Ctrl, Tab, and arrow keys.

Tap Ctrl to arm the modifier (turns green), then type a letter. Common: Ctrl+C (interrupt), Ctrl+D (EOF), Ctrl+Z (suspend), Ctrl+L (clear).

Custom keyboard

Tap the keyboard icon to switch to a custom terminal keyboard with three swipeable pages of keys that you can fully customize — drag to reorder, add, or remove keys.

Pinch to resize & landscape

Pinch on the terminal to adjust font size. Rotate to landscape for more vertical space — the UI collapses into a slim sidebar.

Quick actions (FAB)

A floating action button shows the session's AI logo. Tap it for quick actions: Start, Resume, Login, and more — customizable per AI type in Settings. Continue on Computer and Reconnect are always available.

Push notifications

The desktop app sends push notifications for:

  • Task complete — AI finished and is waiting at the prompt.
  • Needs attention — AI is asking a question or waiting for input.
  • Sign in required — triggers the OAuth sheet automatically.
  • Usage limit reached / restored — with reset time.

Notifications screen

Tap the bell icon in the header. Shows all recent notifications grouped by day, filterable by type. Tap a notification to jump to its session.

OAuth login

When Claude, Gemini, or Codex needs to authenticate, the desktop app intercepts the browser call and pushes the URL to your phone. A browser sheet slides up — authenticate, and the callback is relayed back automatically.

Important: Login commands must be run from a session started through the mobile app. The OAuth interceptor is only active in sessions managed by RemoteAI.

Settings

  • Account — email, relay token (copy/regenerate).
  • Terminal — font size, cursor style, cursor blink, theme (5 presets).
  • Quick Actions — customize FAB menu per AI type.
  • Notifications — toggle usage limit and limit restored alerts.
  • About & Legal — version, rate the app, terms, privacy, compliance.
  • Manage — sign out, delete account.

Android

The RemoteAI Android app has the same features as the iOS version — terminal tabs, multi-AI support (Claude, Gemini, Codex), OAuth, push notifications, custom keyboard, themes, and all settings. Install from the Play Store or via the website.

Reference

Uninstall

To uninstall RemoteAI:

  1. Open the desktop app's Settings and disable Auto-Launch.
  2. Quit the desktop app from the system tray.
  3. Delete the app like any other application on your platform.
  4. Optionally, remove ~/.remoteai/ to clean up hooks, logs, and configuration files.
Hooks added to your AI tool configs (~/.claude/settings.json, etc.) are safe to leave — they point to the hook script in ~/.remoteai/ and will simply do nothing once that directory is removed.

FAQ

The connection dot stays grey — my computer isn't showing as online

Check that the RemoteAI desktop app is running (look for the tray icon) and its dashboard shows "Connected". If the desktop still shows the QR / link screen, it isn't paired yet — scan the QR with the mobile app (Settings → Linked Desktops → +). Check ~/.remoteai/ for log files if issues persist.

The OAuth sheet doesn't appear when logging in

  • Make sure the desktop app is running and connected.
  • Run the login command from a session started through the mobile app, not directly on your computer.
  • Check hooks are installed: desktop app Settings → Hooks. Click Reinstall if needed.
  • Verify the mobile app has notification permissions.

Scrolling / mouse doesn't work in tmux

Add set -g mouse on to ~/.tmux.conf, then reload: tmux source-file ~/.tmux.conf

My computer went to sleep — how do I reconnect?

The desktop app reconnects automatically when your computer wakes. To avoid interruptions, prevent sleep when plugged in:

  • macOS: System Settings → Battery → Options → Prevent automatic sleeping
  • Linux: Check your desktop environment's power management settings

How do I revoke a desktop's access?

In the mobile app, go to Settings → Linked Desktops, tap the desktop, and tap Revoke access. The desktop is signed out within ~1 second and shown the QR / link screen. Other linked desktops keep working — revocation is per-device.

How do I rotate my relay token?

Go to Settings → Account → Regenerate in the mobile app. All currently-linked desktops will need to be re-linked after rotation.

How do I reinstall hooks?

Open the desktop app, go to Settings → Hooks, and click Reinstall for the affected tool.

What platforms are supported?

  • iPhone: iOS 13 and later
  • Android: Available on Play Store
  • Mac: macOS 13+ (Universal binary)
  • Linux: x64 (.deb / AppImage / tarball)