Getting Started

Ten minutes, once through the whole path. At the end you will have sent a task from a phone and watched it run on your own machine.

Before you start

• Required: Node.js LTS (it ships npm) on that machine, installed before KernelHub. Runtimes are installed through npm, and the KernelHub installer does not install Node for you.
• A machine that holds the code you want to work on — macOS, Linux or Windows.
• A CLI coding agent already installed on it, such as Claude Code or Codex. KernelHub drives one; it does not include one.
• A phone or a second computer to drive it from.

1 · Node.js first, then install the executor

First make sure Node.js and npm are both there — this is required. Run these two and only go on once both print a version:

Either one says command not found? Install Node.js LTS (it ships npm) from nodejs.org first, or follow Windows from zero · Mac from zero · Linux from zero. Why: Runtimes are installed through npm, and the KernelHub installer does not install Node for you.

Then, on the machine that holds your code:

Windows PowerShell: irm https://icloser.xyz/install.ps1 | iex. On macOS / Linux it installs to ~/.local/bin and needs no sudo; on Windows it installs to %LOCALAPPDATA%\Programs\icloser, needs no admin, and afterwards checks whether typing icloser in a new terminal reaches the copy it just installed (if another tool on the machine has the same name, use icli). If the SHA-256 cannot be verified it says so rather than skipping quietly.

2 · First run

From inside the directory you want KernelHub to work in:

That directory becomes a workspace. The process stays in the foreground and polls for work every few seconds. The first lines it prints tell you which workspace it joined and which runtime it selected — read them; they are the answer to most later confusion.

3 · Pair a device

Open KernelHub Desktop on the same machine and choose Pair this phone, then scan the code with the phone. A join link works too. See Pairing for the details and for what to do when scanning does nothing.

4 · Choose the runtime

KernelHub selects a runtime it can find on the machine. To pin one, pass it explicitly:

Whichever runtime you pick, grants are checked in the same place: writes, edits and execs go through KernelHub's built-in Tool Server. How the runtimes differ: see Runtimes.

5 · Grant permission tiers

Nothing runs until you say what it may do. Grant on the machine itself:

Read and write are enough to edit files. Add exec only if you want it to run builds and tests. Delete / migrate data is never granted remotely. See Permissions.

6 · Send a task

On the phone or desktop, type one sentence into the composer and send it. Name the file if you know it — a task that names its target is easier for you to verify afterwards:

7 · Watch the Live Workspace

The task card turns into a live view: files read, commands run, files changed. When it edits something, a diff appears while it is still working. See Live Workspace.

8 · Read the diff

Open Diff on the card to see the change line by line. The file list is attributed to this task — files that were already modified before it started stay out. See Diff.

9 · Approve if it asks

If the task needs a tier it does not have, it stops before doing the work and raises a card. Approving applies to that one task and expires when the task ends. See Approval.

10 · Read the result

A finished task says what it did, what it changed, and what it could not do. If the result is thin, use Revise — that continues the same task instead of starting a new one. See Results.

First: Node.js and npm (required)

Install Node.js LTS (it ships npm) before anything below, then check that both commands print a version. Runtimes are installed through npm, and the KernelHub installer does not install Node for you.

Both print a version → carry on. Either says command not found → install Node.js LTS first; a brand-new computer is walked through step by step in the Windows / Mac / Linux from-zero guides.

Install it

One line per platform. The script reads the release manifest, so the version, the file name and the checksum are never written into the command you type. It refuses to install if the SHA-256 does not match.

Installed build is checked against the manifest on the spot — putting the file there is not the same as installing it. Prefer to check by hand? Every binary, its size and its SHA-256 are on the download page. 1.0.2 · build 202609161352

The first command after it lands

Run these in your project directory. pair is a one-off: it creates the workspace, writes the local config and draws a QR code in the terminal. run is the one you leave open.

Which build did I actually get — say this first when reporting a problem

Once per project: workspace + one permission question + a QR code

Leave it open. This is the thing that picks work up and does it.

Where the Desktop console opens

The console is a separate process — it does not start with icloser run. Start it with kernelhub-desktop (on a Mac you can also open KernelHub Desktop.app). The two commands below tell you whether it is running and where, and open it once it is; the second one just prints the address in a non-interactive shell instead of popping a browser window.

Where things stand, where the console is, what to do next — works before you have a workspace

Open it in the default browser

Bound to the loopback address only. Nothing outside this machine can reach it, which is why it needs no login of its own.