byre/internal/agents/kb/client-exec.md

How a script or plain shell runs a command on a client Mac without an agent (byre client-exec), and how to check either Mac's screen lock (byre screen).

Running commands on a client Mac from a shell

client_bash needs an agent. For a script or plain shell on the machine byre runs on, such as a wrapper that fetches a token from the human's Mac, use:

byre client-exec [--client NAME] [--timeout SECS] -- CMD...

byre is /Applications/Byre.app/Contents/Helpers/byre on every Mac with the app.

• It runs CMD as client_bash does: zsh as a login shell in the home directory, in the app's session, as the human. That session is what GUI-only commands need.
• Without --client it picks the most recently active Mac, skipping the iPhone, which runs no commands.
• Each argument reaches the client as one word, so shell syntax needs -- zsh -c '...'.
• The command's stdout and stderr come back separately and byte for byte, once it ends, written to client-exec's own stdout and stderr.
• Exit status: the command's own; 75 when no client is connected, it didn't acknowledge the request within 2s, or it disconnected; 124 when --timeout (default 30s) killed it. A one-line byre client-exec: ... on stderr says why.

Credentials

It needs BYRE_TOKEN, which byre sets for everything it starts: agents, their tools and the processes those run, and the task's terminals. A process byre didn't start reads it from loopback-token in byre's data directory (~/Library/Application Support/byre/ by default); it changes every time byre restarts, so read it at each call:

BYRE_TOKEN=$(<"$HOME/Library/Application Support/byre/loopback-token") byre client-exec -- ...

byre logs each call (client, command, exit status, duration), never its output.

Sandboxed shells

client-exec calls byre's API at http://127.0.0.1:8270. When HTTP_PROXY (or http_proxy) is set it sends that call through the proxy, loopback included, unless NO_PROXY lists the address; a sandbox that denies direct loopback connections then needs only to allow 127.0.0.1:8270 through its proxy. BYRE_NO_PROXY=1 connects directly whatever the proxy variables say.

Screen lock

byre screen prints unlocked, locked or no-session (no GUI login for this user) for the Mac it runs on, and exits 0. Check the server Mac with byre screen and the client with:

byre client-exec -- /Applications/Byre.app/Contents/Helpers/byre screen

client-exec runs commands whatever the lock state; a script that needs an unlocked screen checks first and fails fast itself.