🔌 Connect
Connect the iOS app to VirtualProg on your Mac. You only do this once per Mac — the app remembers your servers.
🔧 Prepare Your Mac
- Open VirtualProg → Settings → CLI
- Enable CLI Server
- Enable External Access so other devices on your network can connect
- Note the address, port and token shown there
Tip: Create a scoped token in Settings → Access Tokens and use it on your phone instead of the master token. An Operator token can start, stop and view; an Admin token can also change configuration. See Security.
➕ Add a Server
On first launch the Connect screen appears. Fill in:
| Field | Description |
|---|---|
| Name | A label for this Mac, for example Mac Studio |
| Host or IP | Your Mac's address, for example 192.168.1.20 or mac-studio.local |
| Port | The CLI Server port (default 49152) |
| Use HTTPS | Turn on if you imported a certificate in VirtualProg |
| Token | The master or scoped token |
Tap Connect. If two-factor authentication is enabled for the token, enter the 6-digit code when asked.
HTTPS Certificates
When Use HTTPS is on, the app shows the certificate's SHA-256 fingerprint the first time. Tap Trust only if it matches your Mac's certificate. If the certificate later changes, the app warns you and does not connect until you review it again.
🔁 Switch or Edit Servers
- iPhone: tap the server icon at the top left of the VM list.
- iPad (sidebar layout): choose Switch Server at the bottom of the sidebar.
In the server list, tap a server to connect, swipe to Edit or delete it, and tap + to add another.
Your token is stored in the device Keychain and never leaves this device except to authenticate with your Mac.
🔒 Lock the App
Turn on Require Face ID / Touch ID in Settings to lock the app when it opens and after a minute in the background.
🩺 Troubleshooting
| Problem | What to check |
|---|---|
| Can't connect | VirtualProg is running, CLI Server is on, External Access is on, and both devices are on the same network |
| Token rejected | The token was copied completely, has not expired and has not been revoked |
| Certificate warning | Confirm the fingerprint, or edit the server and turn off Use HTTPS if the Mac serves plain HTTP |
| Empty VM list | A scoped token only shows the VMs it is allowed to access |
| Features missing | Some screens are hidden when your token doesn't allow them — see Security |