Skip to content

Docs

Getting started

Install both apps, pair, and make your first connection.

Nearshell is two apps: one on the Mac (the controlled machine) and one on iPhone / iPad (the controller). Getting set up takes just a few minutes.

Nearshell isn’t open to the public yet. The flow below describes how it works once launched; to hear the moment sign-ups open, join the waitlist.

1. Install both apps

  • iPhone / iPad — install Nearshell from the App Store (coming soon);
  • Mac — download the free Mac app from this site. It’s Apple-notarized, so you just double-click to install and approve on first launch.

The Mac app itself is free; the subscription is purchased on iPhone / iPad, with a 14-day free trial and one Mac free.

2. Grant permissions (Mac side)

The Mac app needs two system permissions:

  • Screen Recording — to capture the screen;
  • Accessibility — to inject mouse and keyboard input. Remote clicks and typing take effect only after this is granted, and any held keys are released the moment a connection ends.

Grant them under System Settings → Privacy & Security, then restart the app.

3. Pair

Pairing happens once; the device is then remembered securely.

  1. On the Mac, open the pairing screen — it shows a one-time QR code (device name, model, and a one-time secret);
  2. Scan it from the iPhone; both sides pin each other’s cryptographic identities via mutual HMAC proof;
  3. The Mac then destroys the one-time secret and uses signed signaling from there on.

On a device without a camera, use the text invite instead: copy the text code shown on the Mac and paste it into the iPhone’s pairing screen.

4. Connect and control

Back on the iPhone home screen, devices appear as list cards:

  1. Tap Connect on a device card; the connection is direct-first, relayed through a nearby node only when needed, encrypted throughout;
  2. Once connected, the whole screen is a trackpad: one-finger cursor move, single / double tap, long-press drag, two-finger scroll, two-finger right click;
  3. The video button up top starts / stops Mac capture; with video on, pinch to zoom / pan the frame and use three fingers to scroll;
  4. Raise the keyboard toolbar when you need to type, and toggle between IME composition and raw key-passthrough.

5. Confirm the path

The diagnostics view shows codec, send / receive FPS, jitter buffer, frame drop / freeze, available bitrate and quality limitation. The connection path is labelled Direct or TURN, so you can tell your current state at a glance.

Stuck? Check the FAQ, or dig into How it works.