Wagglet Runner

Connect a customer-owned Mac, Windows, or Linux machine with one command. No desktop app, Apple certificate, agent email, separate Wagglet account, or copied pairing token is needed.

Install Node.js 22.18 or newer (including npm), then run:

npx --yes @rockbite/[email protected] setup

1. Runner opens Wagglet in your browser. Check the matching code in the terminal and approve the team with your existing Wagglet account. On a headless machine, open the printed link on another device.
2. Runner creates Machine name · Codex and/or Machine name · Claude for each logged-in provider, initially disabled with one concurrent task.
3. Your existing local Codex and Claude logins are reused. If neither is present, choose Codex or Claude Agent (--provider codex|claude; non-interactive setup defaults to Codex). Codex opens its normal browser login; Claude opens Anthropic Console login for API billing only. Wagglet does not offer claude.ai subscription login: an existing subscription login is used only when you already signed in yourself. Anthropic approval is required before advertising subscription-backed Claude agents. Codex, Claude and Git are bundled; Claude always uses the SDK’s matching executable.
4. Setup checks access to your team's repositories. If GitHub login is missing, it opens GitHub's device login and configures the local credential helper. The GitHub CLI is reused or downloaded from its official release with checksum verification. Organization access/SSO may still need approval from your organization. Other Git hosts use your existing local credentials.
5. Chromium is prepared locally for browser tasks. Managed sessions receive instructions to use Runner's bundled Playwright for local QA and screenshot evidence, including when their worktree has no Playwright dependency. This does not require a connected desktop Browser plugin. An explicitly requested browser still needs its own connection. Linux may require Playwright's system libraries and a logged-in Secret Service keyring (secret-tool).
6. Runner installs and starts its background service automatically. Return to Team → Agents and enable automatic work when ready.

You can close the terminal after setup completes. Keep the machine awake and online. The service starts at user login: LaunchAgent on macOS, a user systemd service on Linux, and a per-user Scheduled Task on Windows. No administrator privileges are requested by Runner.

Run the same setup command again to repair or update an installation. The package and its dependencies are copied into a durable per-user directory before setup, so clearing npm's cache does not break the service. Saved pairing and existing logins are reused. Use setup --reconnect only to replace the machine's Wagglet connection; revoke the old connection in Wagglet if no longer needed.

Provider/Git credentials and worktrees stay on the machine. Transcripts remain locally; when a task owner or agent administrator opens the session inspector, Runner sends the requested transcript page to Wagglet. Pages expire after ten minutes. Known credential formats are redacted before transfer; hidden reasoning and system messages are excluded. The Wagglet machine credential is stored in macOS Keychain, Windows DPAPI, or Linux Secret Service. Wagglet receives account labels, model/quota observations, comments and outcomes. Agents on the same machine/provider share the actual local login and subscription quota. Changing an agent's name does not create a new subscription.

Providers

• Codex reports its local account label, supported models and quota windows.
• Claude Agent reports its account label and kind (subscription / API key), full claude-… model ids, and either 5-hour / weekly subscription windows or API billing · no quota window. API accounts are eligible without quota windows. The SDK honours the Runner user's API keys, provider routing and CLAUDE_CONFIG_DIR; credentials stay local.

Claude agents always use Full access (bypassPermissions). Run Runner as your normal user: Claude refuses bypass permissions as root or sudo. User, project and local Claude settings, skills and hooks load for every turn. The four Wagglet workflow tools are available through the in-process wagglet MCP server. Resume, rework and delivery use the same local session; restart recovery checks its transcript and reports an interrupted active turn through the existing failed-turn recovery flow.

If starting Runner from a Claude terminal, the driver removes only the nested-session markers CLAUDECODE and CLAUDE_CODE_ENTRYPOINT from its children. It preserves authentication and provider routing. If authentication fails, run the bundled Claude executable's auth status --json, then auth login --console and setup again. Setup prints the bundled path when Claude is not signed in.

Commands

Use the same npx --yes @rockbite/[email protected] prefix with:

• setup: connect, prepare tools and start the service; also the default command.
• status: show the saved connection and agents.
• dependencies: install a locked npm project using the machine's dependency cache (run from the project directory; no pairing needed).
• start: run in the foreground (do not start a second copy of an installed service).
• install-service: repair service registration for an already prepared installation.
• pair --server <url> --token <one-time-code>: legacy/headless token pairing. Normal setup does not require this.

Build and distribution

Dependency reuse and completion recovery (unreleased)

Managed prompts direct agents to the installed Runner's dependencies command when dependencies are actually needed, instead of repeatedly running npm ci. Changelog-only conflict resolution uses Git checks and fresh remote verification without installing packages or building the application, unless repository instructions explicitly require it. Code conflicts get checks scoped to the affected behavior.

The cache keys pristine unpacked packages by repository, root and workspace manifests, lockfile, Node/ABI, OS/architecture, npm version and installation configuration. Each worktree gets separate files (copy-on-write where available), then native builds and project lifecycle hooks run locally, including Prisma generation. Internal npm workspaces retain their relative links and nested dependencies. Agent edits and generated clients never enter the shared snapshot. Only cache population holds the shared writer lock; readers can restore the atomically published snapshot while another worktree runs hooks. A second install in the same worktree is rejected. Phase timings and wait messages distinguish copying, hooks and waiting for another run. Interrupting an install cancels its own child process group on macOS/Linux; a waiting reader never terminates the writer. Agents must not kill processes based on a matching command name.

External local/Git dependencies fall back to npm ci --prefer-offline --no-audit --no-fund. Other package managers retain their own cache behavior. Snapshots live under the Runner state directory's dependency-cache; remove that directory only when no dependency command is running to reclaim disk space. The macOS LaunchAgent uses ProcessType=Interactive: user-requested coding jobs must not inherit Background CPU/I/O throttling. Existing installations need their LaunchAgent registration updated as well as the package; changing source alone does not change launchd policy.

The Runner checks durable provider completion records as well as live notifications. It retries lost outcomes, preserves the delivery request during restart recovery, and never treats a final prose message or quiet session as successful delivery. Matching transcript activity refreshes Wagglet's activity time at most once per minute; an interrupted turn becomes a visible failure instead of staying "working". Deploy the website's provider_activity event support before updating the Runner. Update the installed Runner only after active turns and pending events finish; preserve pairing and saved sessions.

npm ci
npm test
npm pack

Publish the reviewed package as @rockbite/wagglet-runner with public access. npm installs its pinned dependencies for the customer's platform. The package includes its shrinkwrap lockfile; the durable installation uses npm ci so the background service survives npm cache cleanup. Publish versions immutably: a changed public package requires a new Runner version. Keep the website setup command pinned to that version.

For 0.6.0 (meeting-prep MCP servers) and 0.5.0, publish the Runner package before the website release so its pinned setup command resolves. Deploy the website (including the capacity migration) before updating installed runners: old servers reject the new heartbeat field. Protocol version remains 1.

Publishing requires npm maintainer access, but no Apple signing. No installer workflow or desktop build is involved.

From the repository root, website CI runs npm run test:runner-recovery for the command, protocol and recovery contracts. Run npm run test:runner for full Runner release validation, including Git workspace provisioning.

For isolated local checks use WAGGLET_RUNNER_HOME and WAGGLET_RUNNER_APP_HOME outside your real installation. setup --no-service --server http://127.0.0.1:<port> connects without replacing the installed background service; run start with those same scratch environment variables. Local setup supports a local Wagglet instance; non-local servers must use HTTPS. Browser installation and browser tests remain local/manual, never required CI.

Session inspection and recovery

Open Inspect agent session on the task to read messages, tool calls and output, load older pages, search loaded content, and inspect previous runs. Runner 0.3.0 also reports live Git preparation progress. Runner 0.3.1 admits session starts two at a time (override with WAGGLET_RUNNER_START_CONCURRENCY); runs still execute in parallel once started. The inspector polls independently of long-running commands; no transcript page is sent unless requested. Very long entries are explicitly marked as shortened; the original JSONL remains local.

Stop session interrupts the provider turn or workspace preparation, releases the task and pauses automation. Existing worktrees and transcripts are retained under the existing 30-day run retention policy. Fresh starts require confirmation from the original machine before selecting the same or another agent. They create a new run, conversation and workspace; uncommitted work is not copied.

Event delivery retries independently from heartbeats and command polling. A rejected event or unavailable saved provider is isolated to its run. Authentication, throttling and temporary server failures retry for up to seven days or 100 attempts; permanent client errors are quarantined immediately. The last 20 rejected payloads and their reason/time remain in that run's local state for diagnosis. Do not send these state files publicly: they can contain task information.

After re-pairing, old runs that the new connection cannot access no longer block the host. Their workspaces and local records become eligible for the normal 30-day cleanup, measured from the first permanent context refusal. Restore the original connection before that retention period expires if you need to resume those runs. A malformed event alone does not make its workspace eligible for cleanup.

GitHub workflow permission

For repositories using GitHub CLI's OAuth login over HTTPS, setup requests the workflow scope and upgrades an existing login that lacks it. Approve the device code in your browser. wagglet-runner status reports a missing permission without starting an interactive login. Repair it with setup or gh auth refresh -h github.com -s workflow, then retry the run.

This check follows Git's effective repository URL and credential, so SSH keys, other credential helpers, personal access tokens and environment tokens do not trigger an OAuth scope warning. The background Runner never opens an authentication flow. If GitHub explicitly rejects a push for missing workflow scope, the Runner stops the provider turn and the ticket identifies the machine, agent and fix; the local commits remain available.

Workspace preparation and cleanup serialize shared-cache operations per repository. Cancellation finishes an in-flight shared Git write before releasing that cache; queued cancelled runs do not start Git work. Different repositories remain concurrent.