Browse rp

rp agent start

Start the configured agent harness and connect it to Repopack.

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 with rp agent configure --engine codex. Models are codex/<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. --attach and --allow-public-models apply 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.