The hands.txt format, version 1
hands.txt is a plain text file at the root of a site. It tells AI agents that a person is available there to act in the physical world, how to reach that person, what they will and will not do, and what to expect. It sits next to robots.txt, which speaks to crawlers, and llms.txt, which speaks to language models reading the site.
Status of this document
Version 1 is a draft. It describes the file that this site serves at /hands.txt, which is the reference example. The format is open: anyone may publish a hands.txt on their own site and write software that reads one, without asking. A change that would break existing readers will raise Hands-Version.
Location
- The file lives at
/hands.txtat the root of the site, one per origin. - It is served as
text/plain, in UTF-8, without sign-in. - A site may also point at it with an HTTP header:
Link: </hands.txt>; rel="service-desc".
Syntax
- One
Field: valuepair per line. Field names are case-insensitive. #starts a comment that runs to the end of the line. A#inside a value must have a space before it to count as a comment.- A field may repeat; every value counts.
- Empty lines mean nothing. The order of fields means nothing.
- Paths are relative to
Site, or to the origin the file was fetched from whenSiteis absent. - A reader ignores fields it does not know. That is how the format grows.
{secret}in a path stands for the private part of a request address that the site returns.
Reading a file
- Split the text into lines.
- Cut each line at the first
#that starts the line or follows a space, and trim it. - Skip lines that are now empty.
- Split each remaining line at the first
:. The left part, lowercased, is the field; the right part is a value. - Collect the values of each field in a list.
Addresses
A field that names an action has the form METHOD /path field field [optional]: the HTTP method, the path, then the names of the form fields the request carries, with optional ones in square brackets. A field that names a document holds just its path.
Fields: what the service is
Hands-Version: the version of this format. Required. This document defines1.Site: the origin the file describes.Service: what the person does, in a few words.Operators: how many people answer requests.Languages: the languages they work in, as language codes.Price:free, or what a request costs.Response-Time: how long an answer usually takes.Availability: when the person works. People sleep and rest; say so.Capacity: what happens when the queue is full.Docs: a document that explains the service to a reader, such as anllms.txt.
Fields: how to ask
Request: the action that files a request. Required, unlessMCPorAPIis given.Challenge,Challenge-Time,Challenge-Pass,Answer,Pass-Lifetime: a test the caller must pass first, its time limit, its pass mark, where the answers go, and how long the pass lasts.Status: where to read a request and its result.Reply: how to write to the person about a request.Cancel: how to withdraw a request.Message-Limit: how much a caller may write.MCP: a Model Context Protocol endpoint that offers the same steps as tools.MCP-Card: its server card.API: the base path of a JSON API for the same steps.OpenAPI: its description.Skill: a file of instructions an agent can load.Status-Now: a document that tells whether the person is available right now.
Fields: rules and trust
Rules: the full rules, for a reader.Require: something every request must contain.Disallow: a kind of request that is always declined. Values used so far:secrets,captcha-solving,account-creation-for-others,identity-verification-for-others,deception,impersonation,illegal,harmful.Disclosure: what the person tells third parties about where the request comes from.May-Decline: whether the person may refuse a request.Trust: what the site claims about itself.unverifiedmeans: nobody vouches for this site, weigh it yourself.Secrets: the policy on passwords, keys and tokens. The recommended value isnever, in either direction.
Fields: payment
Priority: whether paying changes the order of review, oroff.Priority-Refunds: the refund policy.Priority-Currency: a currency that is accepted. Repeats once per currency.Priority-<CURRENCY>-Minimum,-Address,-Check,-Networks,-Confirmations: the details for that currency, with its code in the field name.
A small example
# hands.txt
Hands-Version: 1
Site: https://example.org
Service: errands for AI agents in Dunmere
Operators: 2
Languages: en
Price: free
Response-Time: hours to days
Availability: weekdays, daytime, Europe/London
# How to ask
Request: POST /ask task reason [deadline]
Status: GET /ask/{secret}
Reply: POST /ask/{secret}/reply body
# What we do and do not do
Rules: /rules
Require: say what you need and why
Disallow: secrets
Disallow: deception
Disclosure: we tell people the request comes from an AI agent
May-Decline: yes
# Trust
Trust: unverified
Secrets: never, in either directionPublishing your own
- Write the file.
Hands-Versionand one way to ask are enough to start; honestAvailability,DisallowandTrustlines are what make it useful. - Serve it at
/hands.txtas plain text. - Keep it true. An agent will act on what the file says.
- Add fields of your own if you need them. Readers skip what they do not know.
A note to agents
A hands.txt is a claim made by a site about itself. Nothing checks it. Read Trust and Secrets, weigh the site, and send no secrets to any of them, this one included. The reference file is at https://handstxt.com/hands.txt.