[idea] Opt-in client-local actions for remote sessions

[imleon]

idea / problem

When I use herdr --remote from a local desktop machine to drive agents on a remote host, some useful capabilities only exist on the attaching local client, not on the remote server.

Concrete example: I run Claude Code inside a remote Linux Herdr session, but my browser automation runtime and authenticated browser state live on my local Mac. The remote agent can operate the remote terminal through Herdr, but it has no safe Herdr-native way to ask the attached local client to perform a local desktop/browser action.

This feels adjacent to #3427, because it is also about agents spanning machines while keeping the human control surface local. It also feels adjacent to #1749, because Herdr already has precedent for bridging a local-client resource into a remote session for clipboard/image paste. The capability I am asking about is narrower: a remote session requesting an explicitly allowlisted local client action.

requested change

Consider supporting opt-in client-local actions for remote sessions.

A remote Herdr server could ask the currently attached local client to run a local action, but only if that action was explicitly configured on the local client. The remote side would not provide an arbitrary command or argv. It would only provide an action id and bounded input.

For example, local config might define an action like:

[client.local_actions.browser]
command = ["some-local-browser-tool"]
stdin = "pipe"
allow_remote = true
timeout_ms = 120000
max_stdin_bytes = 1048576
max_stdout_bytes = 1048576
max_stderr_bytes = 262144

Then a remote agent or plugin could request:

client.local_action.invoke browser

and receive stdout, stderr, exit code, timeout, and truncation metadata.

Important constraints:

• default off
• explicit local allowlist
• no remote-provided command or argv
• bounded stdin/stdout/stderr
• timeout
• foreground attached client only, at least for v1
• clear error if no capable local client is attached
• suitable audit/log surface
• not a generic remote command execution feature

Implementation-wise, this seems like it might fit the existing stable endpoint control lane rather than requiring a new network service or a new wire enum variant, but I am more interested in whether this belongs in Herdr's product model than in prescribing the implementation.

why you want this

It would let remote agents use local-only resources without giving up Herdr's remote workflow or exposing a separate public service.

Examples:

• a remote Claude Code session requesting a local browser automation tool that has the user's authenticated browser state
• a remote session requesting a local desktop-only helper
• workflows where the compute/project state belongs on a remote host, but a small, explicitly allowed capability belongs to the attaching desktop client

Today the workaround is to run a separate SSH reverse tunnel or local broker outside Herdr. That works, but it splits lifecycle, security, and observability away from the tool that already owns the remote session.

[imleon]

One thing I am unsure about is the trust boundary. Static local configuration may be enough for some actions, but for actions that touch authenticated desktop state, Herdr might also want an optional per-invocation confirmation mode. I would be happy with either model; the main requirement is that the remote side never provides the command or argv.

[paulbettner]

Thanks for opening this. We run herdr with --remote: the agents live on a Linux box, and the client runs on a Mac. Two things keep pulling us back to the client machine:

• Live voice with an agent needs the client's microphone and speakers, not the server's.
• File paths printed in a pane should open in an editor on the client, where we actually read the code.

Today both need side channels outside herdr. An opt-in way to run client-local actions would cover both, and we like that the client stays in control of what may run.

Posted by an AI coding agent on behalf of Paul Bettner, who approved it.