8.0 KiB
FAQ
Is Hanzo Dev a harness?
No. A harness is what turns an LLM into an agent: it gives the model tools, a way to call them, runs them, and hands the results back. Claude Code is kind of a harness. It is an interface (the TUI, the Code tab in the desktop app) plus a harness underneath (the Anthropic Agent SDK). Codex is the same split: the app plus the Codex App Server. Hanzo Dev uses those harnesses. It is not a harness, and it does not work without one.
Chef = LLM. Kitchen = harness. Hanzo Dev = the restaurant that lets you bring whatever kitchen you want. Our MCP is a cookbook we hand the kitchen, but the chef won't open it unless you tell them to :) I wrote the long version here: What is a harness?
Bring your own: Claude Code, Codex, Cursor, Grok Build, OpenCode, Google Antigravity, Kiro, Pi, Muse Code, or fx. Provider setup
Why use Hanzo Dev instead of Claude Code or the Codex app?
We were inspired by the Codex desktop app, Conductor, Claude Desktop, and Cursor Glass, but none met our bar. What you get:
- Bring your own sub. Claude, Codex, and whatever else you already have installed.
- Best in class remote. Run
hanzo upon any box and drive it from anywhere. - Best in class mobile app.
- Truly 100% open source. If we go the wrong direction, fork it.
Every harness feels nearly identical in here, so you can stop worrying about harnesses and focus on building :) Install
Can I use Hanzo Dev with my Claude Code subscription?
Yes.
How much does Hanzo Dev cost?
Nothing. There's no way to pay us to use Hanzo Dev. You bring your own sub. It is free and open source (MIT). You still pay your provider like you already do. Hanzo Connect is free too, for now. Every account can connect up to 3 machines running Hanzo Dev. Phones and browsers that connect to them do not count. Need more? Link a paid Hanzo Chat account. More machines We don't want to charge for this, but if the bill gets unacceptable we may have to change course. If you hit limits or have issues, you can always fork it, self host, or use Tailscale. Install
Can I connect more than 3 machines with Hanzo Connect?
Yes. Link your Hanzo Chat account and Hanzo Connect raises your limit: up to 10 machines with Hanzo Chat Pro, or 100 with Premier. Open your account menu in Hanzo Dev, go to Hanzo Chat, and select Link Hanzo Chat. Sign in to Hanzo Chat and approve. The free Hanzo Chat plan keeps the normal limit of 3. More machines with Hanzo Chat
Why is my Claude 5-hour limit draining so fast?
It shouldn't anymore. Hanzo Dev drives Claude through Anthropic's Agent SDK, and Anthropic's 5h meter used to charge Agent SDK usage about 1.7x more than using Claude Code directly. Weekly limits were never affected. Since v0.1.7, Claude in Hanzo Dev drains your 5h limit at the same rate as Claude Code. Still seeing it? Update Hanzo Dev on the machine that runs your agents. My post on it · Tracking issue
How do I use Hanzo Dev remotely?
Your agents run wherever Hanzo Dev runs: your desktop, a server, a VPS. You connect to it from anywhere. I do this constantly. Less than 5% of my prompts run on my laptop. Run hanzo up on that machine and you get really good remote support. Hanzo Connect is the easy path. LAN pairing and Tailscale work too, and hanzo.bot is the web client. Remote access
How do I use Hanzo Dev on my phone?
Get the iOS or Android app, then connect it to your computer with Hanzo Connect or a pairing link. The phone is a remote. Your computer does the work and needs to stay on. Mobile setup · Remote access
Why does Hanzo Connect keep disconnecting?
Hanzo Connect is our built-in alternative to Tailscale for remote connections. If it keeps dropping, open Settings > Environments, find the machine, and select Details. The first part marked as failed is the cause. I will not be disappointed if you set up Tailscale as a fallback (I do this personally). Hanzo Connect troubleshooting
Will I get banned for using my subscription?
No. We work with all of the labs and Hanzo Dev is within the TOS of Claude Code, Codex, and Google Antigravity. We worked directly with SpaceXAI to collaborate on the Grok Build and Cursor integrations. Everything else uses official ACP bindings.
If it works in Hanzo Dev, you can trust it is safe.
Can I add a bunch of accounts for one provider?
I don't think Hanzo Dev is the right place to manage a pile of accounts. If we add an auto-switcher, we are risking TOS bans for our users.
A separate work account is fine. Setup for two: Codex · Claude. For a bigger pool, manage them outside Hanzo Dev with a self-hosted proxy like CLIProxyAPI. I walked through how I use 6 Claude subs and 3 Codex subs in this video, and wrote up the setup in this guide. Hand it to your agent and it will walk you through it. Early apologies if it gets you banned 💀 After you set up a hub, Hanzo Dev can show its pooled limits under Usage. Connect a hub
Can I use an API key or OpenRouter instead of a subscription?
Yes. Add another provider instance in Settings and give it its own keys and endpoint. Claude has a full OpenRouter recipe. Your subscription setup stays untouched. OpenRouter · Provider instances
Does Hanzo Dev support local models?
No. Hanzo Dev is a serious developer tool. Locally runnable models are not capable of meaningful engineering work.
Does my code go to Hanzo servers?
No. Your code and prompts go from your machine to your provider (Anthropic, OpenAI, etc.), not to us. With Hanzo Connect, traffic rides a Cloudflare tunnel (cloudflared on your machine). Our relay sets up the link. It does not proxy your HTTP or WebSocket sessions. Hanzo Dev does send basic product usage events (provider, model, token totals, that kind of thing). No prompts, no file contents. That is the same on Tailscale, LAN, or Hanzo Connect. Set HANZO_DEV_TELEMETRY_ENABLED=false if you want it off. Product usage data
Worktrees are eating my disk. How do I clean them up?
Open Settings → Worktrees → Cleanup and turn on automatic worktree cleanup. You can also run it now from there. Worktrees add up fast. One user cleared 500 GB. Storage cleanup
Is there voice input?
Yes. On iPhone and Android, dictation uses on-device speech by default; you can opt in to a paired environment instead. Web and desktop require you to choose an environment first. The transcript goes into your draft for review. See Voice input.
Does it work on Windows, Mac, and Linux?
Yes, all three. Desktop app, CLI, the works. One catch: there is no hanzo binary for Intel Macs, so use the desktop app there. Windows folks can also run agents inside WSL. Install
Why is my provider not showing up?
Almost always, the CLI is not installed or not on the PATH of the machine that runs the server. (Not your phone. The computer.) Log in on that machine first, like codex login or claude auth login. Still missing? Point Binary path at it in provider settings. Version managers love to cause this one. Provider setup