Runner Installation

A Runner is a local executor that picks up requests and runs your configured AI agent automatically.

💡 The runner is optional. You can use AgentTeams with just the AgentTeams CLI and a local agent (Claude Code, etc.). Install a runner only if you want requests to be picked up and executed/dispatched automatically.

Install & initialize

npm install -g @agentteams/runner
agentrunner init --token YOUR_TOKEN

The runner registers as an OS service (launchd on macOS, systemd on Linux, Task Scheduler on Windows) and starts automatically on login.

Supported engines

The runner executes each engine through its locally installed agent CLI. Install the CLI for the engine you want and make sure its command is available on your PATH.

Prepare Copilot CLI

To use Copilot CLI as a Runner engine, complete installation, sign-in, and workspace trust approval under the same account that runs the Runner. Choose one of GitHub’s official installation methods for your environment.

# npm (all platforms, Node.js 22 or later)
npm install -g @github/copilot
 
# Homebrew (macOS or Linux)
brew install --cask copilot-cli
 
# WinGet (Windows PowerShell)
winget install GitHub.Copilot

After installation, start copilot once in the workspace the Runner will use and complete GitHub authentication with /login. When Copilot CLI asks whether to trust a directory, approve persistent trust only for workspaces you consider safe for repeated execution. GitHub manages Copilot subscription and organization policy; AgentTeams does not bypass either.

⚠️ For unattended execution, AgentTeams Runner invokes Copilot CLI as copilot -p <prompt> --allow-all. This automatically approves permissions Copilot CLI needs while it works, so use it only in trusted workspaces. When isolation is needed, prefer a dedicated RunnerBox or worktree.

Prepare Cursor CLI

To use Cursor CLI as a Runner engine, install the CLI and complete authentication under the same account that runs the Runner.

# macOS or Linux
curl https://cursor.com/install -fsS | bash
 
# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex
 
# Verify the installation
agent --version

After installation, sign in with agent login, or provide an existing CURSOR_API_KEY environment variable to the Runner service account. AgentTeams does not create, store, or change Cursor API keys, login state, authentication storage, or Cursor settings.

⚠️ For unattended execution, AgentTeams Runner invokes Cursor CLI as agent -p --force --output-format stream-json --stream-partial-output. --force automatically approves permissions needed during the task, so use it only in trusted workspaces. When isolation is needed, prefer a dedicated RunnerBox or worktree.

Prepare Kimi CLI

To use Kimi CLI as a Runner engine, install it and complete Kimi Code authentication under the same account that runs the Runner. On Windows, install Git for Windows  before the first launch because Kimi CLI uses its bundled Git Bash shell environment.

# macOS / Linux
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
 
# Windows PowerShell
irm https://code.kimi.com/kimi-code/install.ps1 | iex
 
kimi --version

Start kimi once in the workspace the Runner will use and complete /login. Kimi Code stores authentication and configuration under ~/.kimi-code/ by default (or the directory selected by KIMI_CODE_HOME). AgentTeams does not create or inject Kimi credentials or Kimi Code settings.

⚠️ For unattended execution, AgentTeams Runner invokes Kimi CLI as kimi -p <prompt>. Kimi’s print mode uses its auto permission policy; keep Runner workspaces trusted and isolated with a dedicated RunnerBox or worktree when needed.

Discovered RunnerBoxes

The Runner automatically discovers linked Git worktrees in the repositories connected to it — regardless of which tool created them — and registers each as a reusable RunnerBox. There is no dependency on any specific worktree creation tool: any git worktree add (by you, an editor, or another automation) is picked up on the next successful poll.

• The Runner only scans repositories connected to AgentTeams. It never searches your home directory or the whole machine.
• The default checkout is excluded (it overlaps the existing run path); only linked worktrees are registered.
• Discovery is read-only. The Runner never runs git worktree prune/remove and never deletes directories or branches.
• A valid worktree is AVAILABLE. A worktree that disappears from a successful listing (removed externally, or prunable) becomes MISSING. A failed Git lookup preserves the existing state instead of falsely marking entries missing.
• Local paths stay on the owning Runner. They are never sent to the server or shown in the web UI; a discovered RunnerBox always runs on the machine that owns it.

Discovered worktrees are external: AgentTeams treats them as read-only and never owns their lifecycle. Removing a MISSING discovered RunnerBox from the management screen deletes only the AgentTeams registry entry — your local Git worktree directory, branch, and past run history are left untouched.

Status & lifecycle

agentrunner status       # check active state / autostart registration
agentrunner stop         # graceful shutdown
agentrunner uninstall    # stop + remove autostart + clean up

If autostart is registered, the OS may restart the runner after stop. Use uninstall to fully remove it.

Next steps

Once installed, see Runner Requests for usage — sending requests, tracking status, and multi-runner setups.