iControl — Documentation

What is iControl?

iControl turns any phone, tablet, or computer into a wireless trackpad and keyboard for your Mac. Open a link in your browser and your device becomes a remote control — no apps to install, no accounts to create, no internet required.

Everything happens on your local Wi-Fi network. Your phone talks directly to your Mac. Nothing goes through the cloud.

ℹ

iControl is a one-way tool. It sends input to your Mac. It cannot see your screen, access your files, or read anything from your Mac. The only information it receives back is the current volume level.

Installation

Download and open

1
Download iControl from the latest release on GitHub.
2
Open the .dmg file and drag iControl to your Applications folder.
3
Open iControl. The icon appears in your menu bar — there is no Dock icon.
4
Grant Accessibility permission when prompted. This is required for input simulation.

First launch — Gatekeeper warning

iControl is not notarized by Apple, so macOS Gatekeeper will block it on first launch with a message saying the app "cannot be opened because it is from an unidentified developer" or "cannot be verified."

To open it anyway:

1
Click Done (or OK) to dismiss the Gatekeeper dialog.
2
Open System Settings → Privacy & Security and scroll down to the Security section.
3
You will see a message saying iControl was blocked. Click Open Anyway.
4
In the confirmation dialog that appears, click Open. macOS remembers this choice — you will not be asked again.

ℹ

This is a standard macOS warning for apps distributed outside the Mac App Store. It does not mean the app is unsafe — it means Apple has not charged the developer a notarization fee. The iControl source code is fully open on GitHub and can be reviewed or built locally if preferred.

Accessibility permission

If the prompt does not appear automatically, go to System Settings → Privacy & Security → Accessibility and enable iControl.

⚠

Accessibility permission is used only to move the cursor and simulate key presses. iControl cannot read screen content or access other applications' data.

Connecting a device

Click the iControl icon in your menu bar. You will see a QR code and two URLs — one using your Mac's local hostname, one using its IP address.

On your phone or tablet, scan the QR code or type either URL into your browser. In Secure mode, the QR code already contains your authentication token — scanning it connects you automatically with no extra steps.

Install as a PWA

For quick one-tap access, install iControl to your home screen:

iPhone / iPad: tap the Share button in Safari, then Add to Home Screen
Android: tap the browser menu, then Install App or Add to Home Screen
Desktop: click the install icon in your browser's address bar

ℹ

Both devices must be on the same Wi-Fi network. iControl will not work over mobile data or across different networks.

Header

The header runs across the top of the screen:

Hamburger icon (left) — opens the Settings drawer
iControl logo (centre) — decorative, tappable to scroll to top
Connection dot (right) — green when connected, red when disconnected. Tap to manually trigger a reconnect.

Touchpad

The large surface at the top of the screen works like a laptop trackpad.

One finger move — moves the cursor with native acceleration
Tap — left click
Two fingers — scroll in any direction
Two finger tap — right click
Hold without moving — starts a drag. The touchpad highlights purple.

Clicks on the touchpad and the dedicated click buttons respect any active modifier keys. Latch Shift, Ctrl, Option, or Command before clicking to send modifier+click combos — for example, Cmd+click to open a link in a new tab, or Shift+click to extend a selection.

Below the touchpad are three mouse buttons — left, middle, and right click. The middle button doubles as a one-handed scroll control: touch it and slide your finger in any direction to scroll. Once the scroll starts, you can move your finger anywhere on the screen — you do not need to stay on the button. Lift your finger to stop. This lets you scroll both vertically and horizontally with a single hand without using the two-finger trackpad gesture.

General tab

Arrow keys, Tab, Backspace, Return, Space, and a volume slider on the right. Includes sticky modifier keys — Shift, Ctrl, Option, and Command.

Tap a modifier to latch it. It stays highlighted and active until you tap a regular key or perform a click, then releases automatically. This lets you fire shortcuts like Cmd+C or Ctrl+Tab without holding two keys simultaneously — and modifier+click combos like Cmd+click or Shift+click work the same way.

Type tab

Two ways to type on your Mac:

Compose mode

Tap the text area and type using your device's native keyboard — with autocorrect, emoji, voice input, and multilingual support. When ready, tap Send to deliver the text to whatever is focused on your Mac.

Full Keyboard

Tap Full Keyboard to open a replica of the Apple Magic Keyboard. Keys are sent one at a time as you tap them, exactly like a physical keyboard.

Cursorpad

The cursor icon button opens the Cursorpad — swipe in any direction to move the text cursor one character or line at a time. Hold and then swipe to select text as you move.

Sensitivity is configurable in Settings.

Media tab

An iPod-style control wheel. Outer buttons control volume and track navigation. The centre button plays or pauses. Tap and hold the left or right outer buttons to seek backward or forward.

Apps tab

Quick-launch buttons for Finder, Safari, Messages, Music, YouTube, and other common apps. At the bottom, type any app name, bundle identifier, or full URL and tap Open to launch it on your Mac.

System tab

Shortcuts for common macOS actions: Mission Control, Launchpad, App Exposé, App Switcher, Spotlight, fullscreen, minimise, select all, copy, paste, undo, redo, new, and open.

Full keyboard

The Full Keyboard opens from the Type tab. It is a complete replica of the Apple Magic Keyboard — every key, all modifier keys, and a full function row.

On iPad, the keyboard sits below the touchpad — the same spatial layout as a MacBook. On phones in landscape, the screen rotates to fit the keyboard layout comfortably.

Modifier keys

Shift, Ctrl, Option, and Command are sticky. Tap one to activate it — it highlights. Tap a regular key or perform a click and the combo fires, then the modifier releases automatically. This applies to clicks on the touchpad and the dedicated click buttons, in both tab view and full keyboard mode.

Shift — releases after one character. Capitalises letters and activates symbol variants.
Caps Lock — stays on until tapped again. Affects letters only, not symbols.
Cmd / Ctrl / Opt — stay active until released. Combine freely for multi-modifier shortcuts.
Fn — switches the function row from system actions to raw F-key events.

Function row

Key	Action	With Fn active
F1	Brightness down (built-in display)	F1 key event
F2	Brightness up (built-in display)	F2 key event
F3	Mission Control	F3 key event
F4	Launchpad	F4 key event
F5	Siri	F5 key event
F6	Screenshot toolbar	F6 key event
F7	Previous track	F7 key event
F8	Play / Pause	F8 key event
F9	Next track	F9 key event
F10	Mute	F10 key event
F11	Volume down	F11 key event
F12	Volume up	F12 key event

Keyboard gestures

The close button in the top-right corner of the keyboard does more than close:

Tap — close keyboard, return to tab view
Swipe down — collapse to peek mode (function row only visible)
Swipe up — swap keyboard and touchpad positions
Swipe down (from swapped) — swap back to default

Secure mode DEFAULT

In Secure mode, every device must authenticate before it can send input. Two paths exist:

Token — for your own devices

The QR code and URL in the menu bar contain your personal token. Scan the QR code and you are authenticated immediately — no typing required. The token is saved on your device and reused silently on every future reconnect.

Request Access — for guests

If someone opens the URL without a token, they can tap Request Access. A dialog appears on your Mac — click Allow or Deny. Approved guests receive a temporary session token that lasts until they close the browser tab or iControl restarts.

ℹ

Denied devices cannot try again in the same browser session. Closing and reopening the tab gives a fresh start.

Open mode

Any device on your network connects immediately with no authentication — useful for personal use where convenience matters more than access control.

Switching to Open mode requires Touch ID or your Mac login password. Switching back to Secure is instant — a new token is generated automatically. Any time you switch modes or regenerate the token, all currently connected devices are disconnected and must reconnect before sending input again.

Managing access

All controls are in the iControl menu bar under Connection Security:

Secure / Open — select your mode. Switching either direction requires biometric or password confirmation. Switching mode immediately disconnects all active clients — they must reconnect to continue.
Regenerate Token — visible only in Secure mode. Generates a new token and immediately disconnects all active clients. Devices must scan the new QR code or enter the new token to reconnect.

Situation	What to do
Setting up your own device	Scan the QR code — done
Letting a friend connect	Have them tap Request Access, approve on your Mac
Revoking all access	Regenerate Token in the menu bar
Temporary open access	Switch to Open, switch back to Secure when done

Settings

Tap the hamburger icon in the top left to open Settings.

Touchpad sensitivity — how fast the cursor moves relative to finger movement. Default 1x.
Scroll sensitivity — how far the page scrolls per two-finger swipe. Default 1x.
Cursorpad sensitivity — how many pixels of swipe trigger one arrow keystroke. At 1x, roughly 12px per keystroke.

Known limitations

iControl simulates input through standard macOS APIs. Some system features require hardware-level input that software cannot replicate:

Space switching (Ctrl+Arrow) — intercepted by macOS at a system level before iControl can deliver it. Use Mission Control on the fn row instead.

Hot corners — triggered by physical cursor arrival at screen edges, not cursor position alone.

Dock auto-hide — same mechanism as hot corners.

Password fields — macOS blocks all software input simulation when a password field is focused. This is a built-in security feature. Type passwords directly on your Mac.

Brightness keys — F1 and F2 affect the built-in display only. External displays are not affected.

Unencrypted traffic — WebSocket connections use plain HTTP, not HTTPS. On shared or untrusted networks, keystrokes are visible to anyone capturing packets on the same segment. On a home or trusted office network this is not a practical concern. Avoid using iControl on public or open Wi-Fi.

ℹ

These are platform constraints that affect all software-based input tools, not issues specific to iControl.

Best practices

A few setup choices that make iControl noticeably more reliable day to day.

Simplify your Mac's hostname

Your Mac's local hostname determines the URL iControl shows in the menu bar — something like aniss-macbook-pro.local:4040. Apostrophes get percent-encoded and hyphens stack up, making the URL awkward to type and occasionally causing resolution failures on some routers.

Set a clean, short hostname in System Settings → General → Sharing → Local Hostname. Something like studio, mac, or air gives you a URL like studio.local:4040 — easy to remember and type on any keyboard.

ℹ

Stick to lowercase letters and numbers only. No apostrophes, no hyphens, no spaces. The hostname is used by mDNS — special characters cause inconsistent resolution across devices and operating systems.

Assign a static local IP to your Mac

If you prefer using the IP address URL rather than the hostname — or if hostname resolution is unreliable on your network — your Mac's local IP address can change each time it reconnects to Wi-Fi. This breaks saved bookmarks and PWA shortcuts.

Fix your Mac's IP in your router's DHCP settings by creating a static lease tied to your Mac's Wi-Fi MAC address. The router will always assign the same IP. Your iControl URL becomes permanently http://192.168.1.x:4040 and never changes.

How to find your Mac's Wi-Fi MAC address: System Settings → Network → Wi-Fi → Details → Hardware Address.

⚠

Every router's interface is different. Look for DHCP reservation, static lease, or address binding in your router's admin panel. The IP you assign must be outside your router's automatic DHCP range to avoid conflicts.

Android PWA over HTTP — use Hermit

Chrome on Android enforces HTTPS for PWA installation. Since iControl runs over plain HTTP on your local network, Chrome will load the page but refuse to offer Add to Home Screen as a proper PWA — you get a browser shortcut instead, which opens with the address bar visible and no standalone feel.

Hermit (available on the Play Store) creates Lite Apps — frameless browser windows that behave exactly like PWAs without requiring HTTPS. Add iControl's URL in Hermit, enable frameless mode, and the result is indistinguishable from a native app install. No address bar, no browser chrome, full screen.

ℹ

iOS Safari and desktop browsers install iControl as a proper PWA without any workaround — this is an Android Chrome-specific limitation.

Add to home screen before leaving the network

Install iControl as a PWA while you are on the same network as your Mac. Some browsers cache the manifest and icons at install time — if you try to install from outside the network, the install prompt may not appear or the icon may not load correctly.

Keep the screen awake on your phone

If your phone's screen sleeps while iControl is open, the WebSocket connection may drop depending on your device's background app policies. For extended couch sessions, turn off auto-lock temporarily or use your device's guided access / stay awake feature.

The connection indicator turns red when the connection drops. Tap it to reconnect instantly — you do not need to reload the page.

Use the hostname URL on most devices, IP as fallback

The hostname URL (mac.local:4040) works reliably on iOS, macOS, and most Android devices. Windows and some Android configurations occasionally have trouble resolving .local hostnames due to mDNS handling differences. If a device cannot load the hostname URL, switch to the IP address URL — both are shown in the iControl menu bar.

Restart your app to revoke approved accesses

If you used Request Access to let a guest connect temporarily, quit and relaunch your app when you are done. This clears their session and re-secures the connection without requiring you to switch modes or change any other settings.

Troubleshooting

macOS says the app cannot be opened

This is the Gatekeeper warning for non-notarized apps. Click Done to dismiss it.
Go to System Settings → Privacy & Security, scroll to the Security section, and click Open Anyway next to the iControl entry.
Confirm by clicking Open in the dialog that follows. macOS will not ask again after this.

Page does not load

Make sure both devices are on the same Wi-Fi network — mobile data will not work.
Try the IP address URL instead of the hostname URL. Some routers block local hostname resolution.
Disable any active VPN on either device — VPNs often route traffic away from the local network.
Check System Settings → Network → Firewall and make sure iControl is allowed.

Connection indicator stays red

Tap the red dot to manually trigger a reconnect.
Close the browser tab and reopen the URL.
In Secure mode, your saved token may have been invalidated — for example, if the token was regenerated or the auth mode was switched. Scan the QR code again to get a fresh token.

Cursor moves but clicks do not register

Check System Settings → Privacy & Security → Accessibility — iControl must be enabled.
Try toggling Accessibility off and back on, then restart iControl.

Typing does not work in some apps

Click the target app window on your Mac to give it focus first.
Password fields block all software input by design — type passwords directly on your Mac keyboard.

Keys are not doing what I expect

Check for latched modifier keys — they are highlighted when active. Tap to release.
Check whether Caps Lock or Fn are active on the full keyboard.
Close and reopen the keyboard to reset all modifier state.

Touchpad feels imprecise

Adjust Touchpad sensitivity in Settings — lower values give finer control.
Matte screen protectors add noise to touch input and can affect smoothness.

Someone connected without permission

Open the iControl menu bar and tap Regenerate Token. This immediately disconnects all devices.
If you were in Open mode, switch back to Secure — this also generates a new token.

iControl does not appear in the menu bar

iControl is a menu bar app — look at the top-right of your screen, not the Dock.
If the menu bar is full, other icons may be hiding it. Try making space by removing other menu bar items.

Frequently asked questions

No. iControl requires both devices on the same local network. If you have a Mac but no router, create a hotspot on your Mac and connect your phone to it — iControl will work over that connection.

No, and this is intentional. iControl only listens on your local network. It is physically impossible for someone outside your home network to connect — even if they know your URL. No port forwarding, no VPN, no cloud relay. The server is simply not reachable from the internet.

No. iControl is input-only. It sends commands to your Mac — cursor movement, key presses, system shortcuts. It never reads your screen, captures images, or accesses files. The only information received from your Mac is the current volume level, used to keep the volume slider in sync.

Accessibility permission is required for any app that simulates keyboard and mouse input on macOS. Without it, iControl cannot move the cursor or press keys. The permission does not allow iControl to read screen content — it only enables input simulation.

Yes. Multiple devices can be connected simultaneously. They all share the same cursor and keyboard focus — whoever sends a command last is who the Mac responds to. There is no conflict resolution — it works like multiple people touching the same trackpad.

The WebSocket connection drops when the Mac sleeps. When it wakes, tap the connection dot to reconnect, or simply close and reopen the tab. Devices with a saved token reconnect silently.

Devices with a saved token reconnect automatically and silently. Guest devices approved via Request Access will need to request access again — session tokens are in-memory only and clear on restart.

macOS activates Secure Input Mode when a password field is focused. It blocks all software-based input simulation — not just iControl, but any tool using the same macOS APIs. This is intentional and cannot be bypassed. Type passwords directly on your Mac keyboard.

Brightness control via keyboard simulation only works for the Mac's built-in display. External monitors control their own brightness through physical buttons or separate software like MonitorControl.

Yes. iControl is open source under the MIT license. The entire frontend is a single HTML file with no build step. The backend protocol is documented in the README. Fork it, modify it, make it yours.

Yes. The entire product — the macOS app and the web client — is under 1 MB combined. No frameworks, no bundlers, no external services. The web client is a single HTML file. The Swift backend has four source files. Small by design.

User Manual