RunBuoy
  • English

      • Quick Start

      The RunBuoy Skill and CLI are available to install today. Start with the complete prompt if your agent supports Skills, or use the manual flow when you want to control each command. Complete phone pairing requires an iPhone with access to the RunBuoy app for iOS 18 or later.

      One prompt installs the Skill + CLI

      Your agent installs the RunBuoy Skill first, then reads its built-in safety rules to install and verify the CLI. It must explain the command and wait for approval before using sudo, a system package manager, or a curl installer.

      Copy the complete prompt and paste it into an agent that supports Skills:

      Help me install and verify RunBuoy:

1. Use your native Skill installation mechanism to install the RunBuoy Skill from
https://github.com/TANG617/RunBuoy/tree/main/skills/runbuoy
Preserve SKILL.md, agents/openai.yaml, and the references/ directory in full. Do not guess an installation path.

2. After installation, read references/installation.md from that Skill and follow its safety rules to install the RunBuoy CLI. First check command -v runbuoy. If it is missing and uv is available, run:
uv tool install --python 3.12 runbuoy

3. If uv or tmux is missing, or sudo, a system package manager, or a curl installer is required, explain the exact command and wait for my approval.

4. Finally run:
runbuoy --version
runbuoy doctor --json
runbuoy capabilities --json

Only report whether the Skill is discoverable as $runbuoy, the CLI version, local_ready, and delivery status. Do not start pairing, a demo, or any monitored command, and do not upload logs.

      This flow only installs and verifies RunBuoy. It does not pair a phone or start a run. Learn how the agent installation prompt is designed and used.

      Install the CLI manually

      Manual installation · Available now

      The uv flow below is a public, executable installation path for macOS and Linux.

      1. Install system dependencies and uv

      macOS
      Debian / Ubuntu
      Fedora
      Arch Linux
      brew install tmux uv
uv tool update-shell

      Restart the terminal before continuing. uv downloads and manages the required Python 3.12 runtime; tmux is a system dependency that must come from your operating system package manager.

      2. Install the CLI

      uv tool install --python 3.12 runbuoy

      Choose the completion command for the shell you actually use:

      Bash
      Zsh
      Fish
      runbuoy completion install bash

      3. Verify the installation

      runbuoy --version
runbuoy doctor --json
runbuoy capabilities --json

      local_ready=true from doctor schema v2 confirms that the platform, Python, tmux, and local storage meet execution requirements. delivery.ready is separate; local Runs remain available before pairing or while the Server is unreachable.

      Optional: use the Python API in a project

      The CLI environment created by uv tool is isolated from your project environment. If your code imports APIs such as from runbuoy import progress, declare the dependency in the project root as well:

      cd my-project
uv add --optional runbuoy runbuoy
uv sync --extra runbuoy

      Installing into both environments is intentional. SDK calls must run inside the process tree started by RunBuoy; see Progress modes.

      Already installed the CLI manually?

      You can use the agent prompt above later to add the Skill. The agent checks command -v runbuoy first, so an existing CLI is not installed again; it simply continues with verification.

      Already have access to the iOS app? Pair next

      Continue only after you have installed the RunBuoy app for iOS 18 or later:

      runbuoy device pair
runbuoy run -- python3 experiment.py

      After scanning the one-time pairing code, the command remains on the computer while iPhone displays carefully scoped status, progress, timing, and results. Existing demo commands remain available for separate verification, but are not required installation steps.

      Next steps