DocumentationiPhone
Pairing with the Mac
The phone holds a register of its own. Pairing is for the case where it should be writing into a Mac’s instead, and this page is the whole of that handshake, including the parts that refuse.
- For
- Pair the iPhone with a Mac so the phone writes into that Mac’s register.
- Will not
- It will not pair with a Mac whose fleet syncs through the cloud; the phone tells you to sign in instead, because the register is not on that machine.
- Writes
- Stores the Mac’s host, port, device token and certificate fingerprint in the Keychain; unpairing clears all four.
What pairing is for
Which register the phone writes into, and nothing else. It is not what gives the phone the ability to record.
The phone is not an accessory to the Mac. It keeps its own register, and a phone that has never met a Mac can still stand up an organisation and record an asset from nothing. Pairing changes where its writes land: into a particular Mac’s register over the local network, instead of the one on the phone.
The handshake is a one-time exchange that gives the phone a credential for that Mac and a certificate to check it against from then on.
There are two ways in. The first is Pair with the Mac, which is the code-and-check flow this page is mostly about. The second is a silent join when both devices are signed in to the same Apple Account, which the app offers above everything else on the discovery screen because it needs no code at all.
Pairing is not the same as signing in to Starkive Cloud. A Mac can hold its register locally, or sync it through the cloud, and the phone asks the Mac which before it stores anything. If the Mac answers that its fleet is in the cloud, the phone will not pair with it: it tells you to sign in instead, because the register you want is not on that machine.
Finding the Mac
The phone browses the local network for Macs advertising the Starkive service. Nothing is typed unless discovery fails.
Each Mac appears as a row with its name and the line Tap to ask this Mac to let you in. Tapping it does not pair immediately. The phone first asks the Mac where its fleet lives, and only then asks it to admit this device.
If nothing appears, the screen says No Mac in range and explains: open Starkive on the Mac, keep both on the same Wi-Fi, and note that some office and guest networks block the discovery this uses. That last sentence is the one that saves a support call.
Under the list there is a line reading Can’t see it? Enter a code. That opens the manual pairing sheet, which is the next section.
The pairing code, and the four digits beside it
The Mac shows a six-digit code. It also shows four digits under it, and those four are the part that matters.
The header of the sheet says Open Settings → Mobile Scanner on your Mac to get a 6-digit pairing code. Under the code on the Mac there is a second number, four digits long, printed under the heading Or Enter Manually. Both go into this sheet.
Pick the Mac, or type its address
Tapping a discovered Mac fills the Mac IP address field for you. If discovery found nothing, type the address shown on the Mac’s screen.
Enter the six-digit code
Into Pairing Code. The field is numeric and centred.
Enter the four-digit check
Into Check. The sheet says: Both numbers are on the Mac, under “Or Enter Manually”.
Name the device, then Pair Device
Device Name defaults to the phone’s own name. Pair Device is disabled until the address is filled and the code is six digits long.
The four digits are derived from the Mac’s certificate. The phone fetches the certificate first, computes the digits from it, and only sends the pairing code if they match what you typed. A relay sitting between the two devices has to present its own certificate to read anything, and its digits will not be the ones printed on the Mac’s screen. Sending the code is the theft, so the check happens before the code moves.
When the Mac asks you to approve
Tapping a discovered Mac does not use a code. The Mac asks its own operator to approve the phone, and shows a number on both screens.
The screen says Type this on your Mac and shows the number. The line under it is deliberately narrow: Your Mac is asking for it. Entering it there lets this phone in. It does not tell you to glance at the Mac, because the number you are supposed to be reading is the one on the phone in your hand.
The Mac’s operator types it. The phone polls once a second until somebody answers, or until roughly two minutes have passed. Cancel abandons the wait.
If the Mac refuses, the phone says so plainly: That Mac turned this device down. If nobody answers in time: Nobody answered on the Mac. Try again.
Joining with your Apple Account
If both devices are signed in to the same Apple Account, the Mac can leave a note the phone reads, and no code is needed.
The discovery screen offers your own Macs first, above everything else, under a heading reading Your Mac or Your Macs. Each row says Signed in to the same Apple Account. No code needed. and carries a Join button.
The note the Mac leaves carries a certificate fingerprint and a secret, but not an address. The phone walks the Macs discovery actually found and tries each one pinned to that fingerprint. Only the machine holding the matching private key can complete the handshake, so being wrong about where costs a failed connection rather than a wrong decision about who.
After a successful join the phone says: Paired using your Apple Account — no code was needed, because both devices are signed in to it. You can remove this phone from the Mac’s Settings.
Joining is never automatic. A phone that joined by itself would be a phone that reached across a guest network into your home Mac because it happened to be reachable, and you would have no idea it had.
When it does not work
The phone names the failure rather than blaming the network for all of them. Each message points somewhere different.
- Nothing answered at that address. Check Starkive is open on the Mac and that pairing is switched on there.
- That Mac accepted the connection and then closed it. It may not recognise this phone as being on its network. Update the Mac app.
- This phone couldn’t reach the local network. Check Settings → Privacy & Security → Local Network and make sure Starkive is on.
- That Mac didn’t answer. Some Wi-Fi networks stop devices talking to each other. Try a different network, or use a pairing code.
- That Mac already has connection requests waiting. Answer or turn them down on the Mac, or give it a couple of minutes, then try again.
- Those four digits don’t match this Mac. Nothing was sent. Somebody may be between you and it, or the number was mistyped.
- That Mac’s certificate changed part-way through. Nothing was paired. Try again.
Each message carries the address and the error code in brackets at the end. You will not know what -1004 means, but you can read it out, and that is the difference between one step and an hour of restarting a router.
The phone writes every connection attempt to a log file that survives the app, truncated at 200 entries. It is a diagnostic, not a record. A message on screen is not evidence, and diagnosing a pairing failure over the phone has twice turned on a detail the sentence did not carry.
What pairing stores, and what unpairing clears
Four things go into the Keychain, and all four go when you unpair.
Pairing stores the Mac’s host, its port, a device token and the certificate fingerprint. The fingerprint is the pin: from that point on, every request the phone makes to the Mac is checked against it, and nothing else is accepted.
The pin is taken at the one moment it means anything, which is an exchange you started by reading the Mac’s screen. It is never adopted from what the Mac reports back. A relay that passed the real Mac’s digest through would otherwise have the phone pinning a machine it had never actually spoken to.
Unpairing clears all four, and rebuilds the session that was checking against the old pin. Leaving that session alive would keep a phone checking against a Mac it has left.
The Keychain items are written with device-only protection, so they are not restored to a new phone from a backup. A credential for a register is not something to carry across a device you no longer hold.
Where the register lives, and why the phone asks
A Mac can hold its register locally or sync it through Starkive Cloud. The phone asks which before it stores anything.
When you tap a discovered Mac, the phone calls the Mac’s health endpoint and reads the answer. If the Mac says its fleet is in the cloud, the phone does not pair. It shows a note headed <Mac name> syncs through the cloud with the line: There’s nothing to pair with. Sign in below and you’ll have the same register, from anywhere.
That is not an error. It is the Mac telling the truth about where its register is, and the phone pointing you at the route that actually reaches it. Assuming local from the fact that you tapped a Mac is right only when the two agree, and when they do not, the phone would build a register against a source nobody writes to and report healthy the whole time.
A Mac too old to answer the question keeps the old behaviour rather than blocking the only route it has. The phone falls back to assuming local.