Start the local runner from any directory. No linked checkout, project selection
or repository list is required. rp agent start uses the harness saved by
rp agent configure and exits with setup guidance if no
harness is saved. If you have a profile from an older version, configure that
same profile once and choose its existing harness; keep your workspace and
profile to preserve conversations.
rp agent start [--engine opencode|codex] [--profile <directory>] [--workspace <directory>]
First open Agent workspace → Connect agent → Pair agent harness
in your signed-in browser. Within three minutes start rp agent on the box.
An unprepared start cannot create a pairing request; return to the browser to
prepare it and run the command again. Enter the eight-character
code shown by the runner in the segmented field; the displayed four-and-four code
can be pasted with or without its separator. One pairing covers
active projects where the paired account has project.read and task.write;
access changes are discovered while the runner is active. Workspaces are prepared only when a conversation needs
them. OpenCode uses a reusable native service; Codex runs its own native
app-server from its private signed-in profile. The selected native CLI, Bubblewrap, Git and OpenSSH are
required on Linux. Configure provider credentials first.
Restarting with the same private workspace resumes the saved, revocable binding
without another pairing request. A deliberate native rp operation or accepted
chat message renews its 30-day inactivity window. Polling, heartbeats and
background snapshots do not. An expired or revoked grant cannot be revived;
prepare a new browser enrollment and run the command again. Preserve the runner's
private workspace: it contains the binding, outside native agent mounts.
Re-pairing the same runner instance replaces its earlier credentials after
approval without revoking other instances. Previously issued duplicates are
not revoked on deployment; revoke old credentials individually in Agent
connections or let them expire. This list shows valid credentials, not live
runner processes.
Before pairing, the runner checks the selected model's provider in its own
profile. Missing configuration stops startup with instructions for
rp agent configure; your ordinary OpenCode/Codex login is not imported.
Configured local runtimes and custom endpoints do not require a paid provider.
Managed runtimes disable OpenCode's free-model fallback unless you explicitly
pass --allow-public-models. That flag permits public/unconnected models for
this run; it is not a provider sign-in or a saved preference.
The terminal shows one runner summary and a line for each ready chat. The short
tab ID distinguishes multiple chats on the same task. For detailed startup
timings, run RP_AGENT_VERBOSE=1 rp agent start. Native errors remain visible
in either mode.
If Repopack is temporarily unavailable (HTTP 503) during project discovery,
a running runner retries automatically. If it happens on startup, wait a moment
and run rp agent start again.
Optional flags:
--model provider/model: initial model for new sessions. Without it, use the profile's configured/catalog default, not a model borrowed from another chat. Resumed sessions retain their own selected model. When the paired native service has model inventory, the runner publishes its available models and initial choice to the chat composer before the first conversation starts. Older servers still connect but cannot show that choice until a session reports it. If a connected server restarts, the runner republishes its inventory on its next presence poll without requiring a new pairing.--allow-public-models: explicitly permit public models without a configured provider connection. Omit it when you intend to use your authenticated provider.--engine codex: use the separate signed-in native Codex profile prepared withrp agent configure --engine codex. Models arecodex/<native-model>, not OpenCode provider aliases. The runner names each new owned thread to materialize its native history without a model turn, then verifies that thread's paged history before browser delivery. Reconnect keeps the exact native thread ID; an uncertain message is never resent. Preserve the private profile and runner workspace.--attachand--allow-public-modelsapply only to OpenCode.--repo <path>: repeatable local source override, not project enrollment.--ssh-known-hosts <path>: explicit SSH host-trust file.
Managed Git over SSH uses pinned host keys, never prompts, and bounds connection
setup to 10 seconds. Keep the supplied GIT_SSH_COMMAND unchanged in Chat. If
host verification fails, check the runner's trusted host keys rather than
disabling verification.
--isolation workspace|host: default filesystem/PID sandbox, or explicit trusted-host execution. Sessions in one runtime share a trust domain; this is not cross-session or network isolation.--attach <loopback-url>: explicitly attach an existing OpenCode service; requires--isolation host. The runner does not stop an attached service. It checks its provider metadata but does not change its free-model policy.
Pairing approval expires after three minutes; the agent grant expires after 30 days of inactivity. Revoke a connection in Agent connections. Restart with the same profile/workspace to resume native session state. Do not delete profile/workspace state to diagnose a lost connection. See chat delivery and recovery.
If the server raises its minimum CLI version while the runner is polling,
the runner exits with upgrade instructions. Run rp update, then restart it.
The companion publishes bounded pending native questions and accepted inbox items to their owning chat. It relays an operator's answer or explicit pending item cancellation to the exact native request; it does not resend accepted messages on reconnect or restart. Long tool output is shortened in the browser preview while the full result remains in the runner's native OpenCode session. A large or Unicode-heavy shell result must not prevent the runner from publishing later chat updates.
Runner connection
An updated paired runner shares one authenticated event stream across its projects and chats. Idle chats do not send command polls. A task change, message, or permission decision wakes the relevant worker. If the connection drops, the runner reconnects with backoff and reconciles current work; an unconfirmed instruction keeps its original receipt. An older server or CLI continues to use polling. Restart the updated CLI to switch transports.
When deleting several chats, the runner waits for each active worker to exit and continues through the batch. If a task-status read temporarily fails after assignment, the runner retries it with backoff so it can install the write key.