Install the SDK
Run the wizard to install humanbehavior-js into your app, or take the manual path if you want to place the code yourself.
Installing Human Behavior means getting humanbehavior-js into your app and
calling init once, in the browser, with your API key. Do this after your
workspace is unlocked. We often run it with you on the call or in Slack; the
wizard path below is what your engineer (or we) runs in the repo.
Before you start
You need an API key and a JavaScript app that runs in a browser: Next, React, Vue, Svelte, Nuxt, Remix, Astro, Angular, Gatsby, or bundled HTML.
Backend-only projects are not a fit. There is no Python or Go SDK, and the wizard will refuse a Flask repo rather than pretend it installed something.
Run the wizard
From the root of your app, or the frontend package if you are in a monorepo:
npx @humanbehavior/wizard@latestTwo different packages
Run @humanbehavior/wizard to install. The wizard adds humanbehavior-js,
the runtime SDK, into your app. Do not run npx humanbehavior-js.
Here is what happens, in order:
- A browser tab opens so you can sign in and Approve the device. This is how the wizard gets a key for your project.
- Back in the terminal, it detects your framework.
- An AI agent adds the dependency, writes the init code into the right file for your stack, and sets your environment variables.
- It runs lint, typecheck, and build scoped to what it changed.
- It writes
humanbehavior-install-report.mdinto your project so you can read exactly what it did.
Expect this to take one to three minutes, longer on a big Next.js repo. It is an agent reading your code, not a template being stamped out. If the browser tab never opens, allow popups and run it again.
Reading the result
The wizard ends in one of three states, and the difference matters:
| Result | What it means | What to do |
|---|---|---|
| success | Wiring and checks both passed | Move on to Verify |
| needs-attention | The code is wired up, but a build or lint check failed | Open the install report, fix the files it names, then verify |
| failed | Unsupported project, or the wiring is broken | Fix the project type or install manually |
A failed install exits non-zero, so you can use it in a script.
The wizard does not take the agent's word for it. After the agent finishes, the
host re-checks the work and will downgrade a cheerful "success" if it can prove
a problem: a bad init signature, an empty API key, an unsubstituted
placeholder, or a dependency written into the wrong package of a monorepo. A
needs-attention result is the system being honest, not a bug.
Installing from inside the product
If you are in the in-app setup flow, the Install step offers the same three routes:
- Install with AI gives you the wizard command, pre-filled with your dashboard URL and project. This is the same wizard, so everything above applies.
- Install manually opens copy-paste instructions for your framework. The manual install page is the fuller version.
- Import existing data connects a supported analytics or error tool and backfills history. Available importers today: PostHog, Datadog, Amplitude, Mixpanel, and Sentry. PostHog uses OAuth: pick US or EU, then Connect with PostHog opens a secure authorization page. No API key, host, or project ID to paste.
While you are on that step, a chip in the corner reads Scanning for connection and flips to SDK connected as soon as the first events arrive. It polls about once a second, and Next stays disabled until it connects, so open your app in another window and click around to make it happen.
Skip Step is available while you are not connected. It asks why, and some answers open an invite modal or a call booking before moving you on. Skipping is the right call when you do not have repository access yet; nothing about it is permanent.
Prefer to place the code yourself?
Manual install
Add the package, set env vars, and call init yourself. The rules that keep it working, plus copy-paste code.
Framework guides
Line-by-line placement for Next, React, Vue, Svelte, Nuxt, Remix, Astro, Angular, Gatsby, and HTML.
If it did not work
- The wizard hit its turn limit on a large monorepo —
cdinto the frontend package and run it again - It refused your project as unsupported — check it is a browser app, not a backend service
- It reported success but you see hydration errors — see the Next.js guide; a leaf initializer avoids this
- Anything else — common install failures and the wizard reference
Next
Verify data is flowing. Do not skip it; a clean install log is not the same as data arriving.