Introduction

What is Bento Hancho?

Bento Hancho is a middleware layer that enables horizontal scaling of Bento proving infrastructure. A single Bento instance is constrained to one host (or a very low-latency network). Hancho removes that ceiling — it sits between your Broker and multiple independent Bento instances, coordinating proof requests across all of them.

Note

The name comes from Japanese: a hancho (班長) is the technical lead of a small group or workstation. Hancho leads the Bento workers so your Broker doesn’t have to.

Where it fits

Broker
  └── Bento Hancho (Manager)
        ├── Worker A  →  Bento + GPU + MinIO
        ├── Worker B  →  Bento + GPU + MinIO
        └── Worker C  →  Bento + GPU + MinIO
                              ↑
                         Shared MinIO (S3)

The Manager runs bento-hancho and exposes a Bento-compatible REST API to your Broker. Each Worker runs a standard Bento instance and registers itself with the Manager. A shared MinIO (S3) instance is accessible by all workers, so receipts and assets are available regardless of which worker handled a job.

Your Broker sees a single Bento endpoint. Hancho handles the rest.

Key concepts

Term	Meaning
Manager	The host running bento-hancho. Receives requests from the Broker, coordinates workers.
Worker	A registered Bento instance. Executes proof jobs and reports results back to the Manager.
Request	A proof request from the Broker. Assigned a Hancho UUID; tracked end-to-end.
Job	The actual Bento job created on a Worker. Bento’s UUID is used internally.

What it gives you

• Scale out — add workers to increase throughput. The Broker sends one request; Hancho decides which worker runs it.
• Reliability — failed jobs are retried on a different worker automatically (default: 3 attempts).
• Drop-in compatibility — Hancho’s API is a superset of the Bento REST API. No Broker changes required.
• Observability — Prometheus metrics exposed at /metrics on the Manager.

How a request flows

1. Broker submits a proof request to the Hancho REST API
2. Hancho assigns a UUID and queues the request
3. The least-busy Worker is selected and the job is forwarded to its Bento instance
4. The Worker polls Bento for status changes and reports back to Hancho
5. On success, Hancho caches the result and returns it to the Broker
6. On failure, Hancho retries on another Worker (if attempts remain)

Get started with the Quickstart →