Set up a runner

A runner is the open-source vps-agent CLI you install on your own machine or VPS. It registers with SprintFlint, polls for Autoplay jobs, runs a coding harness (Claude Code by default) on the cloned repo, and opens a pull request. The runner never merges; you review and merge yourself.

Prerequisites

Install these on the host before registering a runner:

• Node.js 18+ - the runner is a Node CLI installed via npm
• git - to clone your repository and push branches
• GitHub CLI (gh) - to open the pull request
• Claude Code (claude) - required for the default harness; skip if you only run the noop harness

Install

Install the CLI globally with npm:

npm install -g vps-agent

Verify it is on your PATH:

vps-agent --version

Register

Registration links the runner to your SprintFlint organisation. There are two modes.

Token mode (recommended)

Generate a registration token from the runner setup page in SprintFlint, then register with it:

vps-agent register \
  --token <token> \
  --api-url https://sprintflint.com

Open Runners in SprintFlint, create a runner, and copy its registration token. The token both identifies the runner and authenticates it; keep it secret.

Org-id mode

If you prefer to name the runner at registration time, register against your organisation id:

vps-agent register \
  --org-id <id> \
  --name <name>

Start the runner

Start polling for jobs in the foreground:

vps-agent start

To keep it running in the background (for a VPS or long-lived host), use daemon mode:

vps-agent start --daemon

Once started, the runner sends heartbeats and shows as online in SprintFlint. It now picks up Autoplay jobs for your organisation.

Status, logs, and stopping

Harness selection

The harness is the coding tool the runner invokes to implement the issue. Set the harness config key:

• claude - the default; drives Anthropic's Claude Code CLI against the cloned repo. Requires the claude CLI installed and authenticated.
• noop - a dry run that clones the repo and opens an empty PR without changing code. Use it to verify connectivity, git auth, and the PR flow before turning on a real harness.

Permission modes

The permission_mode config key controls how much the harness can do without prompting:

• acceptEdits - auto-accept file edits; a sensible default for unattended Autoplay
• bypassPermissions - run without permission prompts at all; use only on a host you fully trust and isolate
• plan - have the harness plan changes without writing them; useful for previewing what Autoplay would do

Git authentication

The runner uses the host's own git and gh CLI credentials to clone the repo, push the branch, and open the PR. Authenticate once on the host before starting the agent:

gh auth login

vps-agent doctor verifies this, and the agent refuses to start if gh is not authenticated. SprintFlint never handles your GitHub credentials.

Troubleshooting

Start with doctor

vps-agent doctor checks the common failure points and reports what is wrong:

vps-agent doctor

• Confirms Node 18+, git, gh, and claude are installed and on PATH
• Confirms the runner is registered and can reach the SprintFlint API
• Confirms git and gh are authenticated on the host

Runner shows offline

• Run vps-agent status on the host to confirm it is running
• Make sure outbound HTTPS to sprintflint.com is not blocked
• Re-check the registration token; regenerate it from Runners if needed

Jobs queue but never run

• Confirm at least one runner is online and started (vps-agent start)
• Follow logs with vps-agent logs -f while you start Autoplay
• Verify the project has GitHub integration and a configured repository

PR is not opened

• Check that gh is installed and authenticated (gh auth status)
• Confirm the runner can push to the repository
• Try the noop harness to isolate whether the problem is the harness or the git/PR flow

Next Steps

• Autoplay - How jobs are queued and run end to end
• GitHub Integration - Connect a repo and link PRs to issues
• API Reference - Issue comments and integration