r5d-worker

r5d-worker connects a local or remote machine to r5d.dev so the agent can run host commands through the live worker.

r5d-worker start --label macos
r5d-worker --version

The worker uses the existing r5dctl config file and accepts R5D_WORKER_TOKEN or R5D_API_KEY. Project checkouts are managed under:

~/.r5d/projects/<namespace>/<project>/<branch-name>

Web shells and agent shell commands receive a server-issued r5dctl credential automatically. The credential is scoped to the signed-in user and revoked when the shell or command finishes, so commands such as r5dctl auth status do not require a separate login on the worker host.

When the user has signed in with GitHub, web shells and agent commands also receive that OAuth credential through GH_TOKEN. GitHub CLI commands such as gh pr, gh issue, and gh workflow therefore use the signed-in user's permissions without a separate gh auth login on the worker host. Signing in again refreshes the granted OAuth scopes for subsequently started commands and shells.

Visible branch checkouts are the user/agent workbench. Their origin is the authenticated r5d canonical project repository; GitHub remains available separately through gh and the injected OAuth credential. r5d workspace metadata lives under ~/.r5d/sync, and each worker behaves like an eventually consistent Git client. Known writes advance a durable dirty generation and coalesce into a publication after five quiet seconds or at a process/agent boundary. Publications run while ordinary shells and commands remain active: the worker rejects unstable snapshots and hydrates only paths that still match their captured preimages. The worker uploads an immutable candidate, while the server alone promotes canonical main with compare-and-swap. A 60-second scan catches missed notifications and out-of-band edits. Canonical remediation shells are the exception because they edit the hidden synchronization checkout directly and remain serialized with exact synchronization.

Branch names managed by r5d use lowercase letters, numbers, internal hyphens, and slash-separated segments, for example ft/esm-support. They may contain at most 45 characters. On the first start after upgrading to the nested checkout layout, the worker atomically moves each unambiguous legacy <namespace>-<project> directory to <namespace>/<project>. If both paths exist, it preserves both and stops with recovery instructions.

Releases that change the worker protocol are explicitly documented as breaking server/worker cutovers. For those releases, run the release-specific preflight and backfill against the production database, stop and upgrade workers to the required version, deploy the matching server, and then reconnect workers. Older workers are rejected before WebSocket upgrade rather than receiving incompatible target or manifest messages. Protocol-compatible releases use the ordinary worker update flow.

Worker labels are mandatory and unique per user. Choose labels that describe host capabilities, such as macos, linux, ios, or ec2-build.

r5d-worker start keeps a lightweight supervisor process attached to the launching terminal or service. When both r5d CLIs are updated from User Settings, the connected runtime verifies the installed versions, exits with a reload signal, and the supervisor reconnects using the new worker package. Updates only run while the worker has no active commands or shells.

The supervisor also reconnects automatically after server rollouts and transient network failures. A brief bounded delay prevents a tight retry loop while the server is unavailable. Pressing Ctrl+C still stops the worker, and agent-managed processes retain their existing in-process recovery path while disconnected.

One-click updates use the current user's global npm prefix and never invoke sudo. If that prefix is not writable, User Settings provides the exact command to run manually.

The agent runs commands through the virtual shell command:

worker exec macos docker compose up -d
worker exec macos bun test

Agent shell commands receive no stdin by default: prompts read immediate EOF instead of hanging. A command started with interactive: true is spawned with a writable stdin pipe, and the agent's shell_write tool delivers input through the exec_stdin protocol message. The worker acknowledges each write with an operation_result carrying the delivered byte count, closes stdin on an explicit eof, on cancellation, on timeout, and at process exit, and advertises this support through the execStdinV1 capability in its hello message. Servers refuse interactive runs and stdin writes for workers without the capability, so this is a protocol-compatible release that uses the ordinary worker update flow. Delivered stdin is audited server-side in the run's process-runs/<runId>/stdin.log.

When the connected r5d-browser requests a port forward, the worker opens each relayed connection only to 127.0.0.1 on the requested worker port. Browser-side and worker-side ports may differ. The worker never opens a public listener, and a disconnected worker leaves the browser's long-lived mapping unavailable until the same worker label reconnects.