Control study spend, understand where credentials live, and decide what evidence is safe to share.

Humanish is an MIT-licensed CLI. Live studies use your provider accounts; the hosted desktops and model calls have their own costs.

Set a study budget

For the computer-use route, declare both the study budget and a per-participant backstop:

execution:
  target: e2b-desktop
  timeoutMs: 600000
  caps:
    maxTotalUsd: 4
    maxUsd: 2

maxTotalUsd tracks estimated model spend across the study.
maxUsd applies to each participant. Without a study cap, four participants at $2 each have separate thresholds totaling $8; actual spend can exceed that sum.
Both thresholds are checked after model responses report usage. They do not reserve the cost of the next request. An in-flight model call and concurrent participants can cross a threshold before stopping. They are not hard provider billing limits.
E2B desktop time, app provisioning, and any services used by your target app are additional. Desktop estimates use dated assumptions; your provider bill is authoritative.
A model without a known rate cannot satisfy a fail-closed computer-use cap, so the run is refused rather than treated as free.

The included try-live lab uses one participant and maxUsd: 2. It is a starting point for learning the product, not a recommended budget for every task.

npx humanish stats --lab try-live --json

Inspect the run's estimated model and desktop costs, rates, and missing-usage fields. An unknown amount means unknown, never zero. A budget_reached computer-use session is incomplete; reaching a threshold does not establish task completion.

After humanish init, use the keyless first-run path or an explicit lab dry run for a preview that makes no provider calls:

npx humanish run first-run
npx humanish lab run try-live --dry-run

How cost estimates work

Computer-use bundles carry a per-participant model estimate and an aggregate E2B compute estimate. Model estimates multiply recorded token usage by a dated rate table. On the independent computer-use route, each desktop records its observed CPU and memory and a host-measured span from acquired handle to cleanup. Different template sizes are priced separately. Every amount is advisory, not an invoice.

The rate table records its date, source, and whether a rate is a placeholder. Runtime desktop estimates use the allocation's resource readback; missing metadata stays unpriced. The legacy desktop helper uses a labeled 8-vCPU/8-GiB planning assumption, which is not a provider spending ceiling or a measurement of your template. Inspect those fields alongside the amount. An unknown model rate or missing token usage produces estimatedCostUsd: null with a reason; it is never silently counted as zero. Previews invent no spend.

Where the model has separate cache or long-context rates, per-request usage lets the estimator apply them. Missing usage limits what can be priced; a complete-looking total is not proof that every provider charge was observed.

Desktop estimates exclude allocation/startup time before Humanish acquired the handle, plan fees, credits, and negotiated enterprise prices. A desktop kept for debugging or with unconfirmed cleanup adds an unknown remaining-lifetime line, so its total is marked incomplete. Shared-world, scripted-browser, and terminal routes do not yet emit these per-desktop compute estimates.

Choose a model

The maxOutputTokens control below requires Humanish 0.83.0 or later.

For first-party OpenAI computer-use studies, optional actors[0].maxOutputTokens sets a positive integer limit on each response's output, including reasoning tokens. It applies to every participant, continuation and retry. A closing report uses the smaller of this value and its existing 1024-token limit. The effective setting is recorded in the actor's modelSettings; omitting it keeps the provider's normal output behavior.

A small value can end a session before it produces visible text. An explicit provider token-limit response is recorded as budget_reached / incomplete; its partial output does not establish task completion. This setting does not bound input/context tokens, total requests, cumulative spend or desktop time. Terminal, local-agent, scripted, custom-provider/session routes and per-lane overrides are rejected when they declare this unsupported control.

The default computer-use model is gpt-5.6-sol. Set actors[0].model in the lab to pin another supported model. The checked-in rate table also prices models such as gpt-5.6-terra, gpt-5.6-luna, and gpt-5.5; consult the table in your installed version instead of assuming a newly available model is priced.

A declared computer-use cap (maxUsd or maxTotalUsd) on an unpriced model is refused at preflight with HUMANISH_CUA_LAB_UNPRICED_CAP. This checks whether a rate is available; it does not prepay or reserve the next request. An absent cap is uncapped. A zero threshold can still allow a paid model request before its reported usage triggers the stop, so maxUsd: 0 is not a no-provider-call mode. Desktop provisioning can also incur charges.

The terminal route uses scenario.caps.maxUsd for its separate cost-ledger and product-spend rules; it does not use these computer-use model thresholds. The computer-use route uses execution.caps; scenario.caps.maxTotalUsd is not a terminal study budget. Check route warnings before relying on a field.

Store credentials

npx humanish keys set e2b
npx humanish keys set openai
npx humanish keys list
npx humanish doctor

The hidden prompts write keys to the Humanish user store with mode 0600. keys list prints names only. Environment variables work too: E2B_API_KEY and OPENAI_API_KEY for the default live path. An explicit ignored env file can be passed through --env-file on commands that support it.

Keep env files and credentials out of version control. Humanish records provisioned variable names, not their values, and scrubs known secret values from persisted text. The computer-use model's API key stays on the host; the desktop receives actions, not that key.

Use a signed-in coding agent

The computer-use route can use a locally signed-in Codex or Claude Code as the participant's model by setting actors[0].type: local-agent. humanish doctor reports installed and signed-in local agents.

That uses your existing plan and its limits. It is slower than a direct model API call, and model usage can be unpriced in the evidence. E2B still needs its own key and still bills for desktops. Do not carry a priced API-model cap over and assume it bounds subscription usage.

Read the local-agent setup and limitations before choosing this route.

Run evidence lives under gitignored .humanish/. No feedback command publishes it for you. Live screenshots are full fidelity by default and can contain anything the app displayed.

Use synthetic accounts and data. Keep private targets and local experiments in ignored lab files. Before sharing an artifact, run verify and review the actual content, including pixels.

verify detects secret and path patterns. Free-form personal or sensitive information is not fully detected. A share_ready grade makes a bundle eligible for feedback; it does not remove the need for human review.

For a study intended to produce share-as-is screenshots, policies.redactScreenshots: true blurs persisted frames at capture. That trades visual detail for safer evidence and is not a universal sensitive-data detector. See the public-safety boundary.

Recover after an interruption

After a crash, inspect the interrupted run and its resource receipt:

npx humanish runs
npx humanish cleanup --run latest --json

Once you have identified the interrupted run, reclaim its sandboxes:

npx humanish reclaim --run YOUR_RUN_ID --json

reclaim immediately attempts to stop the sandboxes recorded for that run. reclaim uses journaled exact IDs and needs E2B_API_KEY; it does not sweep unrelated resources in your provider account. See reclaim for the full flags.

humanish cleanup writes an inspection receipt. It does not itself authorize provider-resource deletion. Check your provider console if cleanup cannot be confirmed.

Choose telemetry

Humanish collects anonymous command usage by default. It does not send labs, subjects, personas, paths, or evidence.

npx humanish telemetry status
npx humanish telemetry disable

DO_NOT_TRACK=1 also disables telemetry. The telemetry document describes the collected fields.

Budgets and privacy