How to Pair and Sync Devices in Gumpbox

Gumpbox can connect your Apple devices so your iPhone can act as the control plane while your Mac or iPad runs as a trusted passive node. Once paired, devices can exchange approvals, heartbeats, and credential sync messages through Gumpbox's encrypted iCloud relay.

This guide walks through the practical setup: what you need, how to pair, how sync works, how to remove a device, and what to check if something does not connect.

What you need

Before pairing devices, make sure you have:

• Gumpbox installed on each device you want to connect.
• The same iCloud account signed in on every device.
• iCloud Drive/CloudKit available for the app.
• Internet access on both devices.
• The latest Gumpbox build on iPhone and the passive node.
• Both apps open while pairing finishes.

Gumpbox uses your private iCloud database as a relay. Devices do not need to be on the same Wi-Fi network, and Gumpbox does not rely on a local LAN pairing route.

Understand the roles

Gumpbox uses a simple device-control model:

• iPhone is the control plane. It starts pairing, scans codes, sends requests, approves work, syncs credentials, and removes devices.
• Mac and iPad can be passive nodes. They show pairing codes, confirm incoming pairing requests, and apply trusted sync messages.

This keeps trust management easy to understand. If you want to connect or remove a device, start from iPhone.

Step 1: Check iCloud readiness

Open Gumpbox on both devices and go to Devices.

Look for the iCloud readiness card. You want the state to say the device is ready to pair or sync.

If Gumpbox says it is checking, wait a moment. It is verifying that it can read and write private relay messages.

If Gumpbox says sync needs attention, check:

• Are both devices signed into iCloud?
• Is the internet connection working?
• Are you using the latest signed build?
• Is the app allowed to use iCloud?

Do not start pairing until the readiness state is healthy on both devices.

Step 2: Show the pairing code on the passive node

On the Mac or iPad you want to connect:

1. Open Gumpbox.
2. Go to Devices.
3. Choose Show Pairing Code.
4. Keep this screen open.

Gumpbox displays a QR code and a manual pairing code. The code is short-lived, so generate a fresh one if it expires.

Step 3: Scan from iPhone

On iPhone:

1. Open Gumpbox.
2. Go to Devices.
3. Tap Connect Device.
4. Scan the QR code shown on the Mac or iPad.
5. If scanning is not available, enter the manual code.

After scanning, iPhone sends a pairing request through your private iCloud relay.

Step 4: Confirm on the passive node

Return to the Mac or iPad that showed the pairing code.

You should see a confirmation prompt saying that the iPhone wants to pair. Confirm only if you just started this pairing flow from your iPhone.

After confirmation, Gumpbox saves local trust on both devices and establishes an encrypted device channel.

The device should now appear in the connected devices list.

Step 5: Keep both apps open briefly

After pairing, keep both apps open for a short time.

Gumpbox uses hot sync windows around pairing so devices fetch relay messages quickly while the flow is active. Keeping both apps open gives CloudKit subscriptions, pairing responses, and the first heartbeat enough time to settle.

Once connected, Gumpbox can continue using CloudKit pushes, foreground refresh, and heartbeats to keep state current.

How credential sync works

When credential sync is available, start it from iPhone.

The high-level flow is:

1. iPhone selects the trusted target device.
2. Gumpbox creates an encrypted device-channel payload.
3. The payload is sent through the iCloud relay.
4. The receiving device validates the sender and decrypts locally.
5. Sync status updates in the Devices screen.

CloudKit does not receive plaintext credentials. The relay only carries encrypted payloads and routing metadata.

How approvals work

For approval-based workflows, the passive node can send an approval request to the iPhone control plane.

The iPhone receives the request through the same encrypted relay mechanism. You review the action, approve or deny it, and Gumpbox sends the response back through the encrypted channel.

This keeps sensitive server or automation actions tied to a trusted device relationship.

How to remove a device

Device removal is controlled from iPhone.

On iPhone:

1. Open Gumpbox.
2. Go to Devices.
3. Find the device you want to remove.
4. Tap the remove action.
5. Confirm with biometric authentication if prompted.

Gumpbox then:

• marks the device revoked locally
• deletes the local channel key for that device
• publishes a revocation event through iCloud
• starts a short revocation sync window
• prevents stale relay messages from restoring that device

When the removed device receives the revocation, it revokes the iPhone/control-plane relationship locally and stops accepting trusted messages from that relationship.

Why removal may take a moment

Removal sync depends on CloudKit delivery and app lifecycle.

It is usually fast when both apps are open. If one device is asleep, locked, offline, or not receiving pushes, it may apply the revocation when it next opens Gumpbox or returns online.

The important part is that revocation is monotonic. Once a device has a local tombstone, stale heartbeats or old pairing records should not make it trusted again.

Troubleshooting pairing

The iPhone cannot scan the code

Try these steps:

• Increase screen brightness on the device showing the QR code.
• Regenerate the pairing code.
• Use manual code entry instead of scanning.
• Make sure the passive node is showing a fresh code.

The passive node does not show a confirmation prompt

Check:

• Both devices are signed into the same iCloud account.
• iCloud readiness is healthy on both devices.
• Both apps are open.
• The pairing code has not expired.
• The iPhone sent the request after scanning.

If needed, close the pairing sheet, generate a new code, and try again.

The device appears paired but not connected

A paired device may show as available or trusted before the first heartbeat marks it connected.

Keep both apps open for a short time. If it still does not connect:

• Check iCloud readiness.
• Bring both apps to the foreground.
• Confirm both devices are on the latest build.
• Remove and re-pair from iPhone if this is a development build.

A removed device still appears briefly

Bring both apps to the foreground and wait for the revocation sync window to run. If the removed device is offline, it may not update until it opens Gumpbox again.

On the controlling iPhone, the removed device should disappear immediately after removal.

Security checklist

For the safest setup:

• Pair only devices you physically control.
• Confirm pairing only when you just initiated it from iPhone.
• Keep iPhone as the device-control authority.
• Remove devices you no longer use.
• Keep Gumpbox updated on all devices.
• Do not share pairing codes publicly.
• Regenerate a code if you are unsure who saw it.

Summary

Pairing and syncing in Gumpbox is designed to be simple:

• Show a code on Mac or iPad.
• Scan it from iPhone.
• Confirm on the passive node.
• Let Gumpbox establish encrypted device sync.
• Use iPhone to remove devices when trust changes.

Behind that simple flow, Gumpbox keeps trust local, encrypts sensitive payloads before they enter iCloud, validates every incoming device message, and treats revocation as permanent until a fresh pairing flow happens.