VibeDesk
Get started

VibeDesk User Guide

Install the apps, connect to your Mac, and get your first remote app session running.

On this page

What you need

VibeDesk runs your apps on a Mac. Use an iPhone, Android device, or another Mac to control them remotely.

Sign in before using the app. Use Apple or Google on iOS and macOS, or Google on Android and Windows. For email sign-in, select “Sign in with email”, enter a valid address, and complete human verification before requesting a code. Use the same email on every device to see them in one account.

The Mac you control
macOS 14 or later · Apple Silicon or Intel
Your controller
iOS 17+, Android 8.0+, or macOS 14+
Your connection
The same local network, or a VPN already configured to reach your Mac

Keep the host Mac awake and signed in. Your device connects directly to it using TLS and a six-digit connection code.

Install the apps

The current installation path is to build from source. Get the VibeDesk repository, then follow the instructions for your devices. Install the Mac app on the computer you want to control, plus the app for your controller.

Mac Host or controller
  1. Install the full Xcode app and open it once to finish setup. You also need Homebrew for the command below.
  2. Install XcodeGen with Homebrew, then run the build script from the repository’s root folder:
brew install xcodegen
./script/build_and_run.sh

The script builds and opens VibeDesk.app. To reopen the same build later, run ./run.sh. To control from another Mac, install VibeDesk on that Mac too.

End any remote session and quit VibeDesk before rebuilding. After granting Screen Recording, reopen the existing build instead of rebuilding or signing it again.

iPhone Controller
  1. On your Mac, install Xcode and XcodeGen. From the repository’s root folder, generate and open the Xcode project:
brew install xcodegen
./generate.sh
open MobileDesk.xcodeproj
  1. Choose the MobileDeskiOS scheme. In the iOS target’s Signing & Capabilities, select your Apple development team and use a unique iOS bundle identifier if needed.
  2. Connect your iPhone, select it as the run destination, and click Run. Enable Developer Mode or trust the developer on your iPhone if prompted.
  3. Open VibeDesk on the iPhone and allow Local Network access.
Android Controller
  1. Open the repository’s android/ folder in Android Studio.
  2. Install Android SDK 36 and use JDK 17 or later. Android Studio’s bundled JDK is recommended.
  3. Enable USB or wireless debugging on your Android device, connect it, and select the app configuration and your device in Android Studio.
  4. Click Run to build and install VibeDesk.

For command-line installation and SDK configuration, see the Android setup instructions.

Set up your Mac

  1. Allow remote control

    Open VibeDesk on the Mac you want to control. Choose the sidebar option for allowing remote control. This page shows the permissions and your six-digit connection code.

  2. Grant Screen Recording

    Use VibeDesk’s permission button to open macOS settings and enable Screen Recording for VibeDesk. If macOS asks you to quit and reopen, relaunch the same app build with ./run.sh.

  3. Grant Accessibility

    In System Settings → Privacy & Security → Accessibility, enable VibeDesk. This lets it resize and move app windows and send your mouse and keyboard input.

  4. Keep the code handy

    Leave VibeDesk running, with your Mac awake and signed in. Enter the code on your controller when you connect. You can change it when no device is connected.

Using a Mac only as a controller?

It does not need Screen Recording or Accessibility permissions. Grant these on the Mac being controlled.

Connect your device

  1. Put your device and the host Mac on the same network, or connect through a VPN that can reach the Mac.
  2. Open VibeDesk on your device. On a Mac controller, choose the sidebar option for controlling another Mac.
  3. Select your Mac from the nearby devices list. If it does not appear, enter the Mac’s local IP address or hostname manually.
  4. Enter the six-digit code shown on the host Mac, then connect.

You can find your Mac’s IP address in System Settings → Network → your active connection → Details → TCP/IP. Use that address on a real phone; 127.0.0.1 refers to the phone itself.

VibeDesk remembers the most recent successful connection, including its code. If you change the code on your Mac, enter the new one on your device. Use the saved-connection removal option to forget the Mac.

Connecting away from home

Set up a VPN first. The native apps currently use direct connections on TCP port 9876; automatic internet relay is not integrated.

Follow the Tailscale or Jiedian Xiaobao setup below to connect across different networks.

Remote networking

Use Tailscale or Jiedian Xiaobao (节点小宝) to reach your Mac from mobile data or another Wi-Fi network. These tools create a private network between your devices; VibeDesk uses it to carry your remote app session. Choose one tool and set it up on both devices.

First, set up VibeDesk on your Mac and confirm that a local connection works. Keep the Mac awake, signed in, and connected to the internet.

Tailscale Jiedian Xiaobao (节点小宝)

Tailscale

  1. Install Tailscale on the host Mac and your iPhone, Android device, or second Mac. Allow the VPN configuration or network extension requested during setup.
  2. Sign in with the same Tailscale account on both devices so they join the same private network, called a tailnet. If device approval is enabled, have the administrator approve both devices.
  3. Keep Tailscale connected on both devices. Find the host Mac in Tailscale’s device list or admin console and copy its Tailscale IPv4 address, usually starting with 100..
  4. On the host Mac, check that Tailscale allows incoming connections. If your tailnet uses custom access rules, allow your controller to reach this Mac on TCP 9876.

With Tailscale installed on both devices, this setup needs no exit node or subnet router. See the official quickstart and address guide.

Jiedian Xiaobao (节点小宝)

  1. Install Jiedian Xiaobao on both devices from its official downloads. On Apple Silicon Macs, select the Mac app rather than the iPhone/iPad app, as shown in the macOS instructions.
  2. Sign in with the same Jiedian Xiaobao account on both devices. Allow its VPN configuration when prompted, and keep both clients signed in and connected.
  3. Open the remote networking area (异地组网) and its device network (设备组网). Make sure the host Mac’s Enable networking switch (开启组网) is on, so other devices can reach it.
  4. Copy the host Mac’s assigned networking IP (组网IP) from the device list. Use this IP for VibeDesk, rather than a web access link or a domain created for an HTTP service.

These steps use Jiedian Xiaobao’s device networking feature. See the official device networking guide for current controls and screenshots.

Connect through VibeDesk

  1. Leave your chosen networking tool connected, then open VibeDesk on your phone or controller. Enter the host Mac’s networking IP in the manual address field. Nearby discovery may not work across this network.
  2. Enter only the IP address: no https://, path, or :9876 suffix. VibeDesk automatically uses TCP port 9876.
  3. Enter the six-digit connection code shown in VibeDesk on the host Mac. This is the VibeDesk code, not a login verification code from your networking tool. Connect, then choose ChatGPT or another app.
Example host address

100.101.102.103

This is an example only. Replace it with the address assigned to your Mac by the tool you chose. Router port forwarding is not needed for this device-to-device setup.

Test before you leave: turn off your phone’s Wi-Fi, keep mobile data and the networking tool connected, and try VibeDesk again. A successful session confirms that the connection works beyond your home Wi-Fi.

Both devices are online, but VibeDesk will not connect
  • Recheck the host Mac’s networking IP and current VibeDesk code. The phone’s own IP and your Mac’s home Wi-Fi address are not the address to use for this setup.
  • Use one networking tool at a time while testing. Another VPN can replace the active tunnel or conflict with the same address range.
  • Check Tailscale’s incoming connections and access rules, or Jiedian Xiaobao’s host Enable networking switch. Also allow VibeDesk through the Mac firewall for TCP 9876.
  • If the session connects but feels slow, check the Mac’s upload speed and your phone’s connection. Try a lower frame rate or the low-data preset in workspace and video settings.

Choose your workspace

Open the app you want to use on your Mac first. After connecting, open the content picker, refresh the list if needed, and choose what to control.

App
Bring one app’s windows and related dialogs into a dedicated workspace. Start here for ChatGPT, Claude, or Terminal.
Single window
Control only the selected window when you want a narrower view of one task.
Virtual desktop
Use a dedicated desktop when you need several apps or dialogs opened by another process.

Make the text comfortable to read

Choose 480 × 800 for a portrait phone workspace, or start with 800 × 640 in landscape. These are the Mac’s logical workspace dimensions, so the app lays out for that space instead of shrinking an entire desktop.

Try a larger preset if your app needs more room. Custom sizes must use even numbers: width 480–1920 and height 480–1440. Apps keep their own minimum window sizes, so VibeDesk may expand the workspace to fit them.

Rotating your phone changes the viewer’s layout. Choose a different workspace size in the display settings when you want the Mac app’s layout to change too.

Adjust video quality

  • Start with Balanced at 30 fps for general use.
  • Choose the clearer quality preset when reading code or small text, if your connection can handle it.
  • Try the low-data preset at 15 fps if the connection is slow or unstable.

Start remote control after choosing your content and settings. Exit the Mac app’s native full-screen mode first so VibeDesk can move its window.

Controls & keyboard

Touch or trackpad mode

Use the input-mode control to switch between touching the app directly and moving a pointer like a trackpad.

Touch mode

Tap where you want to click. Drag with one finger. Long-press for a right-click, or double-tap for a double-click.

Trackpad mode

Slide one finger to move the pointer. Tap to left-click at the pointer, or tap with two fingers to right-click.

Scroll

Drag with two fingers. On iPhone, if you have zoomed in, this gesture pans the view instead.

Zoom on iPhone

Pinch to zoom from 1× to 4×, then pan with two fingers. Android does not currently support pinch zoom.

Type and send shortcuts

First click the text field in your remote Mac app, then open VibeDesk’s keyboard panel to enter text. Use shortcut controls for keys such as Enter, Escape, and Command combinations.

On iPhone, the floating shortcut ball includes Enter, Shift+Enter, Command, Escape, Copy, and Paste. You can edit up to eight shortcuts. Android provides a floating menu for the keyboard, shortcuts, input mode, and session controls.

Paste uses your Mac’s clipboard

VibeDesk does not sync the phone and Mac clipboards. Copy text on the Mac before using the remote Paste shortcut.

Full screen and ending a session

Enter full screen to give the remote app more space. On iPhone, use the floating ball’s exit button or tap with three fingers to leave full screen. On Android, use the floating menu or the device’s Back action. On a Mac controller, Control + Option + Esc releases remote keyboard focus and exits full screen.

End control closes the remote workspace and keeps the connection available. Disconnect closes the connection too. Windows moved by VibeDesk return to their previous position and size when control ends normally. Leaving the mobile app may also end the session.

The local Mac and remote device share the same signed-in session, mouse, and app focus. Coordinate with anyone using the Mac locally.

Troubleshooting

Start with the issue you are seeing.

My Mac does not appear in the list

Confirm that VibeDesk is running on the host Mac and that both devices are on the same network. On iPhone, enable Local Network access for VibeDesk in Settings. Guest Wi-Fi can prevent devices from reaching each other.

Try the Mac’s local IP address manually. For a VPN connection, use an address reachable through that VPN. Nearby discovery may not cross a VPN.

The connection fails or the code is rejected

Use the current six-digit code shown on the host Mac, including any leading zeros. Re-enter it if you changed the code after a previous connection.

Check the address, keep the Mac awake, and ensure its firewall or network permits VibeDesk’s direct connection on TCP 9876. Update both devices to the same current app version.

I see a blank view or cannot control the app

Check Screen Recording and Accessibility on the host Mac. Screen Recording supplies the picture; Accessibility enables window movement and remote input. Quit and reopen the existing app build after granting permissions if macOS requests it.

Open the target app, exit its native full-screen mode, refresh the content picker, and select it again.

A dialog is missing or the app is too wide

Try App mode to include that app’s other windows and dialogs. If the dialog belongs to a different process, choose Virtual desktop.

A Mac app’s minimum window dimensions still apply. Try a wider workspace or landscape orientation rather than forcing the app into a narrower size.

The picture is blurry or feels slow

For small text, try the clearer quality preset. If updates are delayed, reduce the frame rate or choose the low-data preset. Check your Wi-Fi or VPN connection.

Retina rendering is used when available. Some small workspace sizes may fall back to native pixel rendering, which can look less sharp. A larger workspace can help.

Still need help?

Check the project documentation or report an issue on GitHub. Include your device, OS version, app version, and the steps that led to the problem.