Mac helper

The Assent helper pairs a Mac with Assent by QR code, sends a heartbeat every 30 seconds and runs Run now: when you answer an agent's ask on your phone, the helper restarts that agent on this Mac with your answer. It needs macOS and Node.js 20 or later.

Set it upCopy Anchor Link

These steps apply once the helper is available.

1. Run assent-helper pair. It shows a QR code.
2. In Assent, open Connect, choose Pair a computer, and scan the code, or type the code shown. The code lasts 10 minutes.
3. Link an agent to this Mac in Assent: set When you answer one of its asks to Run now, pick this Mac as its Linked computer and give it a Resume command.
4. Review and allow that agent's command on this Mac, then start the background service:

assent-helper agents
assent-helper allow <agent-uuid>
assent-helper install

The helper talks to the hosted Assent service. Set ASSENT_API_URL or pass --api-url to pair only to point at another Assent server. Pairing refuses a plain http:// address unless the host is localhost or 127.0.0.1.

CommandsCopy Anchor Link

assent-helper pair [--api-url url] [--name name]   show a QR code and wait for your phone to scan it
assent-helper status                               pairing, allowed agents and the local queue size
assent-helper agents                               agents linked to this Mac and whether each is allowed
assent-helper allow <agent-uuid> [--yes]           review and allow an agent's resume command
assent-helper revoke <agent-uuid>                  stop allowing it
assent-helper unpair                               remove this Mac from Assent and forget its key
assent-helper queue                                answers claimed and waiting to run on this Mac
assent-helper once                                 heartbeat, claim and run what is due, then exit
assent-helper run                                  keep doing that every 30 seconds
assent-helper install | uninstall                  add or remove the background service

--name sets the computer's name in Assent and defaults to this Mac's host name. Every command prints one line of JSON.

SettingsCopy Anchor Link

Requests to Assent give up after 15 seconds and count as Assent being unreachable. Pairing again while run is active takes effect on the next tick, without a restart.

What the resumed agent receivesCopy Anchor Link

The helper runs the agent's resume command with your answer in these environment variables:

Exit code 75 from the command means "busy, try later". The helper tries again every 10 minutes, for up to 6 hours. If the agent is still busy after that, the answer is reported as failed and goes back to the agent's next scheduled run.

Exit codesCopy Anchor Link

How Run now stays safeCopy Anchor Link

• Only agents linked to this computer in Assent, with Run now on and a resume command, are considered.
• Nothing runs until you allow that agent's exact resume command on this Mac with assent-helper allow <agent-uuid>, which shows you the command first. If the command changes in Assent, it stops running until you allow the new one. The helper always runs the command stored on this Mac.
• The command gets your environment with every other ASSENT_ variable removed, and without any value holding an agent or computer key.
• Each answer is claimed once. A run that was interrupted (helper stopped, Mac restarted) is never re-run automatically: the helper tells Assent it was interrupted, the answer goes back to waiting for the agent's next scheduled run, and the log tells you which one to check.
• Only one helper works the queue at a time. A second once or run exits with code 3 and names the process holding it.
• The helper's log is redacted: emails, keys, tokens, phone numbers, home paths and this Mac's own computer key. Pairing never prints the computer key.
• While Assent is unreachable, answers wait on the server. The helper keeps running anything it already claimed and catches up when Assent is back.

Pausing itCopy Anchor Link

The background service restarts itself if it stops, so to pause the helper run assent-helper uninstall, and assent-helper install to start it again. install records the path of the helper it was run from, so run it again after reinstalling the helper somewhere else.