← remotekit.ai

RemoteKit – User guide

Full instructions for the Mac app and chat app. Also linked from the app so you or an AI assistant can use it for help.

Latest Mac app (v0.3.7)

Download for Apple Silicon: RemoteKit-arm64.dmg (Developer ID signed and notarized, v0.3.7) or ZIP. Release highlights: What’s new on the home page.

1. What is RemoteKit?

RemoteKit lets you use your AI coding setup (Cursor, Copilot, Claude, and other ACP-compatible agents) from your phone or tablet. Your code stays on your Mac; the chat runs in a browser (Progressive Web App). When you use the relay, traffic between your phone and your Mac is end-to-end encrypted; the relay does not see your messages or project data.

  • Mac (or dev machine): Runs the RemoteKit bridge and your agent (e.g. Cursor). The bridge serves the chat UI locally and can connect to an optional relay so you can use the app from anywhere.
  • Phone or tablet: You open the chat app in the browser (same WiFi as your Mac, or via the relay). You pick a project, send messages, and get replies from the agent running on your Mac.

You must be signed in to the agent on your Mac (e.g. Cursor login). Sign-in is done only on the Mac for security; the phone app only shows status and lets you start the login flow when you are at your Mac.

2. What you need

  • Mac: macOS with Node 18+ (the Mac app includes Node). Your AI agent (e.g. Cursor) and its CLI must be installed and in PATH if you run the bridge from the terminal; the Mac app bundles what it needs.
  • Phone or tablet: A modern browser (Safari, Chrome, etc.). No app store install required; you open the chat URL in the browser.
  • Agent sign-in: You must be logged in to your agent on the Mac (e.g. Cursor). The first time or after your token expires, you log in from the Mac app or by running the agent’s login command on the Mac.

3. Installation

Option A: Mac app (recommended)

  1. Download the Mac app from remotekit.ai or the direct DMG: latest RemoteKit for Mac (arm64) (signed & notarized).
  2. Open the downloaded DMG, drag RemoteKit to Applications (or your preferred folder).
  3. Open RemoteKit. The first time, it may show a Setup Guide and ask for permission to run in the menu bar.
  4. In the menu bar you’ll see the RemoteKit icon. Use it to start the bridge, get your room code and PIN (for remote use), and open the chat.

Option B: Run from terminal (bridge only)

In a terminal: cd bridge, then npm install, then npm run cli. The CLI will guide you through sign-in, projects, and relay. On your phone, open the URL shown (same WiFi) or use the relay URL and room + PIN for remote access.

4. First run (Mac app)

  1. Open RemoteKit from Applications (or Dock if you enabled “Show in Dock”).
  2. Setup Guide (first time): Set Projects (folder or list of project paths) and optionally Relay URL (e.g. https://app.remotekit.ai).
  3. Start the bridge from the menu bar (Start Bridge, or enable Auto-start bridge in settings).
  4. Sign in to your agent: If you’re not signed in, the tray icon will be amber and you may see a prompt. Choose Login… in the menu to start the sign-in flow on your Mac. When done, the icon turns green (same WiFi) or blue (relay connected).
  5. Open the chat on your phone: Use Copy phone link or Show QR Code in the menu, then on your phone open that link (or open app.remotekit.ai and enter the room code and PIN).

5. Menu bar app – reference

Tray icon colors

GrayBridge is stopped.
GreenBridge running and signed in; phone can connect on same WiFi (LAN).
BlueBridge running, signed in, relay connected; phone can connect from anywhere.
Amber/OrangeNeeds attention: starting, or not signed in, or relay not connected yet.
RedError (e.g. bridge failed to start, no projects configured).

Menu items (when bridge is running)

Login… / Change user… – Shown depending on sign-in state. Use these when you’re at your Mac; sign-in runs on the Mac. Open Local Chat – Opens the chat in the browser (same WiFi). Open Remote Chat – Opens the chat via the relay. Copy phone link, Show QR Code, Copy Room + PIN – For opening the app on your phone. Restart Bridge / Stop Bridge, Run Setup Guide…, Open Settings…, User guide, View Logs, Quit.

6. Connecting from your phone

Same WiFi: Start the bridge on the Mac. In the menu, note the “Open on phone” URL (e.g. http://192.168.x.x:8765). On your phone, open that URL in the browser and tap Connect.

From anywhere (relay): Set the relay URL in Mac app Settings (e.g. https://app.remotekit.ai), start the bridge. Use Copy phone link or Show QR Code. On your phone, open the link or go to app.remotekit.ai and enter the room code and PIN.

Important: When you’re on your phone away from your Mac, you cannot sign in or change user. Sign-in only works when you’re at your Mac. If you’re not signed in and remote, the app will tell you to sign in when you’re at the Mac, then reconnect via relay.

7. Sign-in (agent auth)

Your AI agent (e.g. Cursor) must be signed in on your Mac. RemoteKit does not store your agent password or token.

  • At your Mac: In the menu bar, use Login… (if not signed in) or Change user… (to switch account). The agent’s login runs on your Mac.
  • Away (phone, relay): The chat app will show “Not logged in” or “Sign in on your Mac.” There is no Login/Change user button when using the relay from far away; sign in when you’re at the Mac.
  • First run: The Mac app may show a one-time dialog; choose Login… to start the flow.
  • Token expired: Tray icon turns amber; use Login… from the menu bar when at your Mac. In the chat app, a Re-login button may appear for auth-related errors.

8. Using the chat app (PWA)

Connect screen: Direct – enter your Mac’s bridge URL. Relay – enter relay URL, room code, and PIN.

Auth screen: If not signed in, you’ll see instructions. When on relay and away from Mac, only instructions are shown; sign in from the Mac menu when you’re back.

Project screen: Pick a project; expand Advanced for Agent/Model. Tap “Logged in as …” to open the sign-in screen (direct only). Tap a project to start a new chat.

Chat screen: Send messages; header shows title and project. Menu (☰): Switch chat, Agent, Model, Project. Chats with at least one message are saved; empty chats are not. On tablet and desktop, you get a wider layout with preview, sidebar, and keyboard shortcuts—see What’s new on the home page.

9. Settings (Mac app)

Open Open Settings… from the menu bar. General: Launch at login, auto-start bridge, show in Dock. Network: Relay URL, optional fixed room. Projects: Projects root folder or list of paths. Save; restart the bridge if needed for some changes.

10. Troubleshooting

Tray icon stays amberYou’re not signed in. Use Login… in the menu and complete the agent’s login on your Mac.
“Not logged in” on phone (relay)Sign in only on the Mac. Use menu bar Login… when at the Mac, then tap Refresh on the phone.
Can’t connect (same WiFi)Bridge running? Same network? Try the “Open on phone” URL from the menu. Disable VPN on the phone if it blocks local IPs.
Can’t connect via relayCheck relay URL in Settings. Ensure bridge shows room and PIN. Enter same room and PIN on the phone.
“No projects configured”Open Settings → Projects: set projects root or add paths. Save and restart the bridge if needed.
Session ended / DisconnectedCheck the Mac tray; restart the bridge if needed. On the phone use Retry session or reconnect.
Agent “not authenticated”Token may have expired. At your Mac use Change user… or Login…. In the chat app use Re-login if shown.

11. Where to get help

If you ask an AI assistant “How do I use RemoteKit?” or “How do I log in?”, it can use this user guide to give you step-by-step instructions.

← Back to remotekit.ai