Peak Setup

Set up Peak in a repository

Peak runs GitHub Actions jobs on bare-metal microVMs. The only change to a repository is the runs-on line of each job. The Peak CLI makes that change, opens a pull request, and never edits anything else.

Before you start

Check these. Stop and tell the user if one fails.

• The folder is a git repository with a GitHub remote named origin.
• Node 22.13 or newer is installed. Run node --version.
• The user is an owner of the GitHub organization. Personal accounts do not work yet.

Steps

1. Run this in the repository folder:

   npx -y @peakinc/init@latest --yes --json --no-browser
   

2. Read stdout one line at a time. Each line is one JSON object with an event field.

3. When you see {"event":"authorization_required","url":...,"user_code":...}, show the user the url and the user_code. Say: "Open this link and approve the sign in." Then keep reading. The command waits up to 10 minutes.

4. When you see {"event":"pull_request","url":...}, give the user that link. Say what changed: the number of jobs from the plan event, and the files from the applied events.

5. When you see {"event":"done"}, stop. Do not merge the pull request. The user merges it.

If the command stops early

Read the exit code.

Common blocks and their fixes:

• The Peak GitHub App cannot see owner/repo. Show the github_app link from the links event. The user adds the repository to the App there, then adds it in Peak Settings.
• GitHub is not connected to Peak. Show the peak_settings link. An organization owner connects GitHub there.

Hard jobs

The plan event lists jobs the CLI could not move under manual, with a reason. Matrix jobs with macOS or Windows legs, runs-on expressions, and runner label lists land here. For these, run the Peak agent instead:

npx -y @peakinc/wizard@latest --yes --json --no-browser

It does everything init does. For the hard jobs it sends only those workflow files to Peak over a secure connection. Peak decides per job and edits only the runs-on line and the matrix values. The events are the same, plus translate_skipped for each job Peak left as it was, with the reason.

Manual fallback

If neither command can run, change one line per job in .github/workflows/*.yml:

runs-on: ubuntu-latest     # before
runs-on: peak-ubuntu-24.04-4   # after

Open a pull request with that change. Leave everything else in the file as it is.

Rules

• Never print, log, or store a token. The CLI never prints one either.
• Never edit workflow files by hand when the CLI can make the change.
• Never merge the pull request. The user merges it.
• Never remove the old CI. The user removes it after the first green run on Peak.
• If PEAK_TOKEN is set in the environment, the CLI uses it and skips the sign in. Do not ask for it. Do not echo it.
• To undo a run: npx -y @peakinc/init@latest --undo. It deletes the branch the CLI made and nothing else.

Events you may see

check, step, progress, free_minutes, authorization_required, waiting, authenticated, links, detected, plan, diff, applied, committed, pull_request, run, done, error. The wizard adds ci_detected, plan_requested, translate_skipped.

Every question the CLI could ask has a flag. With --yes there are no questions. Without --yes, a question event arrives with id, text, choices and default; answer on stdin with {"answer":"<id>","value":"<choice>"}.