humanish
Synthetic user research for apps, CLIs, and agent-facing product flows. Open-source and public-safe.
Humanish runs studies. Realistic synthetic participants, each with its own goals, patience, and skill, actually use your product on isolated desktops while you watch. A study leaves verifiable evidence: screenshots, action traces, per-task completion funnels, participant outcomes with the denominator attached, and estimated cost lines. A fail-closed share-safety gate stands between that evidence and anything public, and the end of the pipeline is a public-safe feedback draft you can turn into a real issue. Committed study source lives under humanish/; run evidence lands under gitignored .humanish/.
A live four-persona study of drawDB, a public open-source database diagram editor, driven against a commit-pinned local checkout. Every lane is a real computer-use session on a hosted desktop; the captions are each persona's own final report. drawDB is the application studied; it is not a Humanish adopter or endorser.
Quickstart · Study your app · CLI reference · Limits and evidence
Install
Use Node.js 20 or newer, in a project directory:
npm install --save-dev humanish@e2b/desktop is the optional peer for live hosted desktops. Install it alongside Humanish when choosing that route (npm install --save-dev @e2b/desktop) so the CLI can resolve it; a one-shot npx humanish@latest can miss the peer. The keyless preview and local-browser setup need only humanish.
Choose how the participant runs:
| Route | Participant authentication | Desktop | Automatic findings | | --- | --- | --- | --- | | first-run preview | None; synthetic evidence only | None | No model analysis | | Local browser study | Codex ChatGPT login; remote inference | Linux x64 + Docker/KVM or M3+ Mac + Lima; no E2B key | Separate Codex account analyst by default | | openai-computer-use | OPENAIAPIKEY | E2BAPIKEY + desktop SDK | Separate OpenAI request | | local-agent | Codex or Claude Code's own login | E2BAPIKEY + desktop SDK | Still needs OPENAIAPIKEY; skipped without it |
A Codex ChatGPT login can power a local-agent participant. It does not authenticate Humanish's OpenAI API requests. Choose the actor explicitly in your lab; installing Codex does not change an openai-computer-use lab.
For local browsers, install only humanish and follow the local study setup. The first live run downloads a verified runtime image; npx humanish runtime setup prepares it ahead of time. Supported Macs use Lima instead of Docker Desktop. Optional camera and spoken conversation use a separate media runtime. Local inboxes remain a follow-up.
For a new local study, initialize with your app URL and task:
npx humanish init --yes \
--local-browser http://127.0.0.1:3000 \
--local-mission "Complete the primary flow and explain anything confusing"
npx humanish doctor --lab local-browser
npx humanish run local-browserStart your app before running the study. If you already initialized this project, edit humanish/labs/local-browser.yaml to change its URL or mission; init preserves existing files and warns when supplied settings cannot be applied.
doctor only inspects setup. It does not install or start the runtime, open a browser, or use Codex account quota. The local study needs a supported Codex CLI version and ChatGPT login. Linux x64 also needs local rootful Docker, KVM and TUN; M3-or-newer Apple Silicon Macs need native ARM64 Node and Lima 2.2+.
Run a live study with the API route. Set the desktop and model keys with hidden prompts, then send one synthetic participant into the included drawDB study: