Connect coding agents and other agent runtimes to withHuman with the withhuman CLI so their tool calls wait for human approval. Covers installing the CLI, guided onboarding, connecting a runtime to an existing agent, checking the connection, refreshing the tool catalogue, upgrading, and removing the adapter. Use for Claude Code, Codex, OpenClaw, Pi, Hermes and DeepSeek on macOS or Linux, hosted or self-hosted. Trigger keywords - withhuman, withHuman CLI, install withhuman, connect agent to withhuman, withhuman onboard, withhuman agent install, agent eject, refresh-tools, approval hook, calls not gated, human approval for tool calls.
withHuman CLI
The withhuman CLI connects an agent runtime on this machine to a
withHuman organization. After it is installed, every tool call the runtime
makes is sent to withHuman first. The organization's approval pipeline
decides whether the call runs at once, is denied, or waits for a person to
approve it.
Each installation connects one runtime (claude-code, codex, openclaw,
pi, hermes or deepseek) as one instance of an agent in the
organization. The CLI runs on macOS and Linux, Intel and ARM.
Ground rules
- The person runs the interactive steps. Installation can ask for an administrator password, and connecting opens a browser where the person signs in and confirms the organization and agent. Give them the command to run, or run it only when they can answer the prompts.
- Never read, print or copy credentials. Saved connections live in the
CLI's configuration directory (
~/Library/Application Support/withhumanon macOS,~/.config/withhumanon Linux, or$WITHHUMAN_CONFIG_DIR). Don't open them. - Never remove or bypass the adapter on your own initiative. Run
withhuman agent ejector edit the runtime's hook settings only when the person asks. If you are the agent being gated, a call that waits or is denied is the system working, not a fault to route around. - Restart the runtime when told to. A runtime loads its hooks at start, so the CLI's printed restart or consent steps must be followed before a test means anything.
Which server
Hosted withHuman is https://app.withhuman.ai and is the default. A
self-hosted deployment has its own origin, for example
https://approvals.example.com: pass it with --url or set
WITHHUMAN_URL. Give the origin only, without /api/aap. Ask the person
which one they use if it is not clear.
First-time setup (new organization)
Guided setup lives in the web app at <origin>/welcome (hosted:
https://app.withhuman.ai/welcome). The page shows a command with a
one-time setup code, so the person must copy it from their own page:
curl -fsSL https://downloads.withhuman.ai/install.sh | sh -s -- onboard --url https://app.withhuman.ai --code <code>
Leave the command running while the person finishes the browser steps (choose agents, notification channels, which tools wait, a test request). You cannot make up the code; if it expired, the person reloads the page for a new one.
Connect a runtime to an existing organization
Install the CLI (skip if withhuman version already works):
curl -fsSL https://downloads.withhuman.ai/install.sh | sh
Then connect a runtime:
withhuman agent install claude-code
withhuman agent install codex --agent coding-agents --instance codex-laptop
withhuman agent install codex --url https://approvals.example.com
- Omit the runtime to pick from the ones found on this machine. Without a terminal, name it.
--agent <slug>joins an agent that already exists in the organization; it never creates one. Without it, the person chooses or creates the agent in the browser.--instance <name>names this machine's instance. The default is the hostname plus a short suffix.- The CLI opens the browser. If it cannot, the person visits the printed address and enters the code. Codes last ten minutes.
- Running install again with a working connection reuses it without another browser step.
On hosted withHuman the install also registers the withHuman MCP Gateway
with the runtime as an MCP server named withhuman-gateway, so the agent
can use tools granted to it there. It is not the withHuman MCP server that
manages rules (see the withhuman-pipelines skill).
The app's Agents page also has New instance, which prints the same command with the agent and origin filled in.
Check it works
withhuman agent discover
Each runtime found reports adapter installed, incomplete (follow the
restart or repair steps, then rerun install) or not installed.
Then trigger a call that the organization's rules send to a person, for
example a shell command if shell commands wait. The runtime pauses, the
request appears in the app's Review queue and the person's notification
channels, and the call runs only after they approve it. If every call runs
straight through, the rules may approve it automatically: check the
approval pipeline (see the withhuman-pipelines skill) before assuming
the hook is broken.
Refresh the tool catalogue
The organization builds rules from the tools each instance reports. After adding or changing MCP servers in the runtime, run this from the project directory where the runtime uses them:
withhuman agent refresh-tools claude-code --agent coding-agents
It reports successful and failed sources separately. A failed source does not undo the installation; fix that server's connection and run it again.
Update and remove
withhuman upgrade
withhuman agent install <runtime>
withhuman agent eject <runtime>
upgradereplaces the CLI with the latest release and keeps connections. Rerunagent installafterwards to refresh a runtime's adapter files.agent ejectremoves the hook, the gateway's MCP entry and the saved connection for that runtime. It does not revoke the instance in withHuman: tell the person to revoke it under the agent's Instances tab if it will not be used again.
Troubleshooting
| Symptom | What to do |
|---|---|
withhuman: command not found after install | The installer used ~/.local/bin; add it to PATH or open a new shell. |
| The runtime was not found | Install the runtime first, or name it: withhuman agent install claude-code. |
| Browser code expired | Run the same command again for a new code. |
--agent refused | The slug must exist in the organization the person signs in to, and they need permission to connect it. Check the slug on the Agents page. |
Adapter incomplete | Follow the printed restart, consent or repair steps, restart the runtime, rerun withhuman agent install <runtime>. |
| Calls are not held | Restart the runtime, check withhuman agent discover, then check the pipeline: an approve block may be deciding them. |
| Credential expired or revoked | Run withhuman agent install <runtime> again to reconnect. |
| Every call denied because the provider refused the credential | The agent was archived or disabled, or the credential revoked. Enable or restore the agent and reconnect, or, if the person asks, run withhuman agent eject <runtime> to stop gating this runtime. |
| A call waited and then was refused as expired | Nobody decided in time. Tell the person; don't retry it on your own. |
User guides: https://withhuman.ai/docs/getting-started/quickstart.md and https://withhuman.ai/docs/web-app/agents.md.
Related skills
- Downloads
- Security audit
- Pass
- Last updated
- 2w ago
- Current version
- v1.0.0
- License
- MIT-0
