Computer Use on a Remote Mac
Keep agents working on a remote Mac's desktop when its screen locks. Let Agentastic unlock it, or set the Mac up so it doesn't lock
Overview#
Agents can use the desktop of a Mac you reach over SSH: they click and type in its apps through dev computer, and you watch in the Computer tab. When that Mac's screen locks, macOS sends their input to the lock screen, so the computer waits and the agent has to ask you to unlock it.
You can stop those interruptions in two ways:
| Unlock automatically | Keep the Mac from locking | |
|---|---|---|
| The lock screen | Stays on; Agentastic unlocks it when agents need the screen | Off; waking the display shows the desktop |
| What you set up | Save the Mac's password once in the Computer tab | Run two commands on the Mac |
| The password | In your Mac's Keychain | Not stored anywhere |
| Good for | Macs other people can reach | A dedicated Mac in a place you control |
Both need the account your workspace uses to be signed in at the Mac's screen. If a different account is signed in there, the Computer tab says so.
Unlock automatically#
Agentastic keeps the lock screen and unlocks it with the account's password whenever an agent's computer finds the screen locked.
What the Mac needs#
- Screen Sharing turned on in System Settings → General → Sharing, allowing the account your workspace uses. Agentastic types the password through it, on the Mac itself.
- That account signed in at the Mac's screen. Agentastic unlocks a locked session; it doesn't sign in.
- A current Agentastic server on the Mac. After updating Agentastic, reconnect to the Mac once.
Set it up#
- Open the Mac's Computer tab: the one an agent opened, or New Computer in a worktree on that Mac.
- When the tab shows Unlock with the Mac's name, click Unlock automatically…. You can also choose … → Unlock Mac Automatically… at any time.
- Enter the account's macOS password and click Save, or Save and Unlock when the screen is locked.
Agentastic checks the password with the Mac's Screen Sharing before saving it, so a mistyped password never reaches the lock screen.
How it works#
When dev computer finds the screen locked, it asks Agentastic to unlock it. Agentastic sends the saved password to the Mac over the workspace's SSH connection. There, the computer host signs in to the Mac's own Screen Sharing as the account, types the password into the lock screen, presses Return and waits until macOS reports the screen unlocked. The agent's command then runs again, and the agent never has to ask you.
- The password stays in your Mac's Keychain. It isn't stored on the remote Mac, shown to agents or written to logs.
- Agentastic types only into the lock screen of the account your workspace uses. If another account's session is in front, or nobody is signed in, it types nothing.
- If the Mac rejects the password, Agentastic doesn't send it again until you save it again or restart Agentastic. After a failed unlock, agents wait two minutes before trying again.
- When the screen is locked and a password is saved, an open Computer tab unlocks the Mac as soon as it shows the lock screen. Agents can also ask with
dev computer unlock.
Settings → Computer Use → Remote Macs lists the Macs Agentastic unlocks. Stop Unlocking deletes a Mac's password from the Keychain.
Keep the Mac from locking#
On a Mac that only you can reach, you can turn the lock screen off. Run these on that Mac as the account agents use, for example over SSH. Each command asks for that account's password:
# Don't ask for a password after the display sleeps or the screen saver starts.
sysadminctl -screenLock off -password -
# Optional: keep the display on, so agents never find it asleep.
sudo pmset -a displaysleep 0Then unlock the Mac one last time. sysadminctl -screenLock status shows the current setting.
This covers locking that happens when the Mac is idle. The screen still locks when someone locks it by hand (the Apple menu's Lock Screen, Control+Command+Q or a hot corner), and after a restart. Anyone at the Mac's display or keyboard gets the account's session, so prefer Unlock automatically for Macs other people can reach.
To turn the lock screen back on:
sysadminctl -screenLock immediate -password -
sudo pmset -a displaysleep 10After a restart#
With FileVault off, macOS can sign the account in by itself after a restart:
sudo sysadminctl -autologin set -userName <account> -password -Use the account your workspace connects as. If automatic login names a different account, agents find that account's desktop instead and the Computer tab asks you to sign in. FileVault turns automatic login off. On a FileVault Mac, sign in after a restart, at the Mac or with Show Mac's Screen in the Computer tab's … menu.
Troubleshooting#
- "Screen Sharing is off": turn on Screen Sharing in System Settings → General → Sharing on that Mac.
- "did not accept the password": save the password again from the Computer tab. If it's right, open the info button next to Screen Sharing and check that the account is allowed.
- "but it stayed locked": Screen Sharing accepted the password, but the lock screen didn't. This can happen when the Mac uses a different keyboard layout. Click Show Mac's Screen in the Computer tab's … menu to see the lock screen.
- "screen shows … session" or "is not signed in": sign in to the Mac as the account your workspace uses.
Related#
- Remote Machines: connect to your dev boxes over SSH
- Skills: the bundled
computer-useskill that agents follow