Skip to content

FAQ

Your network can’t reach the relay, so only devices on the same network as the Mac can connect. You can enter a reachable self-hosted relay (iroh-relay, starting with https://) in the Mac’s Settings › Network; paired phones will still find the Mac after the change.

If the menu bar shows “Network failed to start”, click Retry.

Some public WiFi networks (hotels and airports, typically) enable client isolation, which blocks devices on the same network from reaching each other. The phone and the Mac are on the same WiFi, yet they can’t connect directly and fall back to the relay, which hurts speed and latency.

Turning off WiFi on the phone and switching to cellular (5G / 4G) usually restores a direct connection; alternatively, put both devices on a network without isolation, such as a phone hotspot or a home or office WiFi.

The device was removed on the Mac, the Mac’s identity was reset, or it’s a leftover configuration from before QR pairing. Click the UULink icon in the Mac’s menu bar, choose Pair New Device… and scan again with the phone.

UULink on the Mac and on the phone are different versions. Update both to the same version, then tap Retry After Updating.

The phone says “Server Identity Changed”

Section titled “The phone says “Server Identity Changed””

UULink was reinstalled on the Mac or its keys were reset. First check that the new fingerprint shown on the phone matches the Server Fingerprint in the Mac’s Settings › Network, then tap Trust New Identity — or simply scan to pair again.

An agent shows “Not Detected” in Settings › Agent

Section titled “An agent shows “Not Detected” in Settings › Agent”

UULink can’t find its executable. Select it in Settings › Agent, install and sign in as shown there (see also Supported agents), then click Detect Again. If it’s installed in an unusual location, click Choose… to point UULink to the executable.

Agent processes inherit the environment of your login shell (whatever ~/.zshrc and friends export). Variables set only inside a function or alias (a proxy, say) aren’t carried over; select the agent in Settings › Agent and add them under Environment Variables. API keys go there too. On the phone, open the Mac’s Info page, tap the agent and edit its Environment Variables.

The menu bar says “No available AI assistant detected”

Section titled “The menu bar says “No available AI assistant detected””

No usable agent was found on this Mac. Click How to Install next to the notice to open Settings › Agent, select the agent you want, install and sign in as shown there, then click Detect Again. The notice disappears as soon as any one agent is available; other agents showing Not Detected doesn’t affect anything.

No completion notification after leaving the app

Section titled “No completion notification after leaving the app”

iOS decides when to wake apps in the background. If you swipe the app away in the app switcher, iOS won’t wake it again. See Settings › Notifications › Background Refresh Log on the phone.

This applies to Claude Code only: the long-running claude process exits after 10 idle minutes (configurable). The next message resumes it automatically with --resume — nothing changes for you.

Section titled “Sessions started in UULink don’t appear in claude --resume in Terminal”

This is how Claude Code itself behaves; the sessions are not lost.

UULink starts claude the way the Claude Code SDK does, so the session records (the jsonl files under ~/.claude/projects/) are marked as SDK sessions. When you run claude --resume in Terminal, Claude Code leaves SDK sessions out of the session list, so sessions started in UULink don’t appear there. This was verified with Claude Code 2.1.310 and may change in later versions of Claude Code.

There are two ways to continue these sessions in Terminal:

  • Resume by session ID (recommended): on your iPhone or iPad, touch and hold the session in the session list and choose Copy Session ID. With Universal Clipboard turned on, you can paste it straight on your Mac. Then, in Terminal, go to the session’s folder (for a session in a worktree, the worktree’s folder) and run:

    终端窗口
    claude --resume <session ID>

    Resuming by ID isn’t affected by the list filter and opens the full session.

  • Show SDK sessions in the list: run Claude Code with an environment variable that makes it run as the SDK:

    终端窗口
    CLAUDE_CODE_ENTRYPOINT=sdk-cli claude --resume

    The list then includes sessions started in UULink as well. Claude Code started this way doesn’t run the way it normally does in Terminal, so use it only to find a session, not as your default.

The other direction works as usual: Claude Code sessions started in Terminal can be viewed and continued on your phone.

Will I lose messages if the network drops?

Section titled “Will I lose messages if the network drops?”

No. Messages are written to an outbox on the phone before being sent, and are resent in order after reconnecting. The server de-duplicates by message ID, so each message runs exactly once. If the Mac restarts mid-run, the run is not retried automatically — you’ll be asked to confirm before resending.

  • Make sure UULink is running on the Mac and the Mac isn’t asleep.
  • Check that the phone is still listed under Paired iPhones in the Mac’s Settings › Devices; if not, scan to pair again.
  • If the Mac’s menu bar says it isn’t connected to a relay, only devices on the same network can connect — see “Not connected to a relay”.
  • If it’s slow or only goes through the relay on the same network, check that UULink is allowed in iPhone Settings › Privacy & Security › Local Network.

The Devices section of the Mac’s menu bar lists every paired device: online ones show whether they’re direct or relayed and the latency; offline ones show when they were last seen.

Click Remove next to it under Paired iPhones in the Mac’s Settings › Devices. It’s disconnected immediately and has to scan again to reconnect.

While UULink is running it keeps the Mac from going to sleep when idle by default, so your phone can connect at any time; you can turn off “Prevent Mac from Sleeping” in the Mac’s Settings › General. Closing a laptop lid or putting the Mac to sleep still disconnects it. For long remote sessions, keep the lid open and the Mac plugged in.

The session shows the error returned by the agent. The usual cause is a missing sign-in or an invalid API key: run the agent once in the Mac’s Terminal (for example claude, codex, agent or qodercli) to make sure you’re signed in and it can respond. For agents that use an API key, such as DeepSeek Harness and Pi, check the environment variables in Settings › Agent. Then resend from your phone.

Screenshots or clicks don’t work after turning on “Control the desktop”

Section titled “Screenshots or clicks don’t work after turning on “Control the desktop””

Control the desktop works through the Mac’s built-in Screen Sharing. In Settings › Control Desktop, make sure Screen Sharing shows “On”; if it doesn’t, use the button next to it to open System Settings › General › Sharing and turn on Screen Sharing. Unlocking and filling in passwords also require Accessibility. The first time it takes control, you enter this Mac’s login password on your iPhone; it is saved only after it is verified. If you later change your login password, UULink clears the old one automatically and asks again the next time; you can also click Clear Saved Password under Control the desktop. If it still fails after changing System Settings, reopen UULink once. See Control the Mac desktop.

Are Intel Macs, iPad or Android supported?

Section titled “Are Intel Macs, iPad or Android supported?”

The Mac app runs on both Apple Silicon and Intel Macs (macOS 14 or later) from the same download. The same app runs on iPhone and iPad (iPadOS 18 or later); Android isn’t supported yet.

No. UULink is developed independently and isn’t affiliated with Anthropic, OpenAI, Google or any other agent provider. Claude and Claude Code are trademarks of Anthropic; other product names belong to their respective owners.

Whose relay is it, and can it see my data?

Section titled “Whose relay is it, and can it see my data?”

By default UULink uses the public relays run by n0 (the team behind iroh). They only forward encrypted data when the phone and Mac can’t connect directly, and can’t read it. You can switch to a self-hosted relay in the Mac’s Settings › Network.

No. The phone and the Mac get to know each other by scanning a QR code; there’s no account to sign up for with UULink or anyone else.

What’s the difference between Free and Subscription, and how is it billed?

Section titled “What’s the difference between Free and Subscription, and how is it billed?”

The free tier connects 1 Mac with unlimited project folders, and includes direct-connect speed, no lost messages, end-to-end encryption and continuing terminal sessions on your phone. A subscription adds: multiple Macs, push notifications, sending images, files and web pages to your phone, sending images with your messages, and Live Activity status.

UULink charges nothing extra for any agent. Each agent uses your own account, subscription or API key, and any usage fees are charged by that provider.

A subscription is ¥18/month or ¥180/year (2 months free), billed by Apple through the App Store; manage or cancel under Settings › Apple Account › Subscriptions on your iPhone. See the full comparison on the home page.

Please collect the following:

  • Mac logs: Settings › About › Diagnostics › Logs › Show in Finder (~/Library/Logs/UULink/uulink.log).
  • Both app versions (Mac: Settings › About; phone: Settings › About).
  • A screenshot of the phone’s Settings › Notifications › Background Refresh Log (for notification issues).