Agent-Driven New Machine Setup

This page is written for an AI coding agent (Claude Code, Codex, Hermes, or similar) that has been told to set up ADHDev on a brand-new machine. Follow the numbered steps below in order and run each command exactly as written.

For human readers: you can hand this page to your agent and say "set up ADHDev on this machine following the new-machine guide" — the agent will do everything except the one browser sign-in that only you can approve.

The goal: from a clean machine, get to a running daemon and a first adhdev launch with as little human involvement as possible. Exactly one step requires a human — the Cloud browser sign-in — and it is clearly marked.

---

Choose a mode first

ADHDev runs in two modes. Decide before you start; the install command is identical, only the account flow differs.

	A — Standalone	B — Cloud
Account / login	None	GitHub or Google (browser sign-in)
Human step needed	No — fully autonomous	Yes — one browser approval
Dashboard	http://localhost:3000	https://adhf.dev
Best for	Single machine, local use, no account, fully unattended setup	Multi-machine, remote access, sharing, Repo Mesh

Rule of thumb for the agent: if the user did not ask for cloud/multi-machine/remote features, choose Standalone (A) — it needs no human and no account. Choose Cloud (B) only when the user explicitly wants an account, remote access, or mesh, and is available to approve the browser sign-in.

---

Step 1 — Check prerequisites

ADHDev requires Node.js ≥ 22.

node --version

• Node ≥ 22: good, continue.
• No Node, or Node < 22: the install script (Step 2) will bootstrap a runtime for you (nvm/fnm/brew/apt/dnf/yum on macOS/Linux; a portable Node 22 on Windows). If you prefer to install Node yourself first, install a 22.x LTS — do not install Node 24+ on Windows (see the warning below).

Windows + Node 24+

On Windows, a global npm install -g adhdev on Node.js 24+ is blocked. Use the PowerShell installer instead — it provisions a portable Node.js 22 under ~/.adhdev/tools/node22 and uses that. Do not try to work around this by forcing a newer Node.

Verify OS while you're here so you pick the right install command in Step 2: macOS, Linux, or Windows.

---

Step 2 — Install the CLI (unattended)

The install script detects the platform, installs Node.js if missing, and puts adhdev on PATH.

For unattended agent-driven setup, set ADHDEV_NO_SETUP=1 so the installer installs only and does not launch the interactive setup wizard (you drive setup yourself in the later steps).

macOS / Linux:

ADHDEV_NO_SETUP=1 curl -fsSL https://adhf.dev/install | sh

Windows (PowerShell):

$env:ADHDEV_NO_SETUP=1; iwr https://adhf.dev/install.ps1 -useb | iex

Already have Node ≥ 22? (any platform):

npm install -g adhdev

Homebrew (macOS / Linux) — no separate Node needed:

brew tap vilmire/adhdev && brew install adhdev

Homebrew bundles its own Node.js runtime. The unattended install script above already prefers this path automatically when brew is present on macOS, so you normally don't need to run it by hand.

Optional: preview channel

Set ADHDEV_CHANNEL=preview to install the @next (release-candidate) build instead of stable. Omit it for the normal stable install. The Homebrew tap tracks stable releases only, so preview installs always go through npm.

Verify the install:

adhdev --version

This should print a version number. The installer updates PATH for the current session and registers it permanently, so this normally works right away — no new terminal needed.

If you still get command not found (a locked-down shell that didn't pick up the PATH change), you have two fallbacks that work without opening a new terminal:

1. Invoke the stable shim by full path (the installer always lands adhdev here):

   # Windows
   & "$HOME\.adhdev\npm-global\adhdev.cmd" --version

   # macOS / Linux
   "$HOME/.adhdev/npm-global/bin/adhdev" --version

2. Windows portable-Node escape hatch — if the shim itself won't run (e.g. the CLI landed but PATH to node.exe is stale), call the installed CLI entry directly with the portable Node 22 the installer provisioned:

   & "$HOME\.adhdev\tools\node22\node-v22.*-win-x64\node.exe" "$HOME\.adhdev\npm-global\node_modules\adhdev\dist\cli\index.js" --version

Otherwise, opening a new terminal always works (PATH is registered permanently).

---

Step 3 — Bring up the daemon

Mode A — Standalone (no login)

Standalone needs no account. Start it directly:

adhdev standalone

This starts the daemon on localhost:3847 and the dashboard on localhost:3000, with no authentication. Skip Step 4 entirely — go straight to Step 5.

Optional LAN access: adhdev standalone --host 0.0.0.0 --token <some-secret>. The --token is optional and only relevant for exposing standalone beyond localhost.

Mode B — Cloud (login required)

Cloud needs an account. The sign-in in Step 4 is the one human step. Do not run adhdev daemon until Step 4 reports the machine online.

---

Step 4 — Sign in (Cloud only) ⏸ HUMAN STEP

⏸ HUMAN STEP — the agent must stop here

Cloud sign-in uses an OAuth device flow that opens a browser for the human to approve. There is no non-interactive login flag, and this is intentional — account authorization is a security boundary a person crosses once, by design.

Never attempt to bypass this by injecting a machine secret through environment variables or any other side channel. That is not supported and must not be documented or scripted.

Agent instructions for this step:

1. Do not run a login command yourself and wait on it. Instead, tell the user: "I need you to sign in. Run adhdev setup (alias adhdev login) and approve the browser prompt with your GitHub or Google account."
2. Pause and hand control to the user. Do not proceed while sign-in is pending.
3. Resume only when the account is authorized. Poll adhdev status and continue to Step 5 only once it reports the machine/account as online. Until then, keep waiting — do not retry install or daemon commands.

For the human: run this, and approve the browser tab that opens against adhf.dev:

adhdev setup    # or: adhdev login

Sign-in requires a verified email from GitHub or Google, or it will be rejected. Once you've approved in the browser, hand control back to the agent.

Then start the Cloud daemon (background, long-lived):

adhdev daemon

The daemon connects to api.adhf.dev, registers the machine, and prints a machine ID.

---

Step 5 — Verify

Confirm the daemon is healthy:

adhdev status

Expected:

• Standalone: daemon reported healthy on localhost:3847.
• Cloud: the machine shows online, connected to api.adhf.dev.

If status is not healthy, see Troubleshooting below before launching.

---

Step 6 — Launch the first agent

Launch a CLI agent the user already has installed:

adhdev launch claude    # Claude Code
# or:  adhdev launch codex
# or:  adhdev launch <target>

adhdev launch <target> starts the agent under the daemon and mirrors it to the dashboard. ADHDev does not manage the agent's own API key or login — each tool keeps its own auth. If the agent asks for its own credentials, that is handled in the agent's UI, not by ADHDev.

Done. You now have a daemon running, the dashboard connected, and a first agent live.

---

Troubleshooting

• command not found: adhdev — the installer updates PATH for the current session too, so this is rare. If it happens, invoke the stable shim by full path instead of opening a new terminal: & "$HOME\.adhdev\npm-global\adhdev.cmd" (Windows) or "$HOME/.adhdev/npm-global/bin/adhdev" (macOS/Linux). Windows-only last resort if even the shim won't run: & "$HOME\.adhdev\tools\node22\node-v22.*-win-x64\node.exe" "$HOME\.adhdev\npm-global\node_modules\adhdev\dist\cli\index.js". Opening a new terminal also works — PATH is registered permanently.
• Node < 22 — install a 22.x LTS (or let the installer bootstrap one). ADHDev refuses to run on older Node.
• Windows, install fails on Node 24+ — use the PowerShell installer (portable Node 22), not npm install -g on Node 24+.
• Windows PSSecurityException / "cannot be loaded because running scripts is disabled" for ...\adhdev.ps1 — the default Restricted execution policy blocks the npm-generated PowerShell shim (PowerShell prefers adhdev.ps1 over adhdev.cmd). The installer relaxes this automatically for the current user; if it was blocked (e.g. Group Policy) run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned yourself, or bypass the .ps1 entirely by calling the .cmd: & "$HOME\.adhdev\npm-global\adhdev.cmd" --version.
• Daemon won't come online (Cloud) — run adhdev status; if it stays offline, sign out and back in: adhdev logout then adhdev setup, then adhdev daemon again.
• Agent won't respond after launch — adhdev status (daemon healthy?), then confirm the provider is installed for your target.

---

Bootstrap script

A companion Node script automates Steps 1–6 with the human-step guardrail built in: scripts/bootstrap-new-machine.mjs.

# See exactly what would run, without executing anything:
node scripts/bootstrap-new-machine.mjs --mode standalone --dry-run

# Fully unattended standalone setup:
node scripts/bootstrap-new-machine.mjs --mode standalone --yes

# Cloud: runs up to the sign-in, then stops and waits for you to approve in the browser:
node scripts/bootstrap-new-machine.mjs --mode cloud --yes

Flags:

• --mode cloud|standalone — which mode to set up.
• --yes — unattended; run install/daemon without extra confirmation. Without it, destructive steps are only described, not executed.
• --dry-run — print the commands only; run nothing. Use this first to preview.

In cloud mode the script deliberately stops at the sign-in step, prints the browser-approval instruction, and then polls adhdev status until the machine is online before resuming — mirroring the ⏸ HUMAN STEP above. It never injects credentials.