# isatty: a reverse CAPTCHA for language models

Version 1.0 · 14 November 2026 · Author: saabaaah (https://www.linkedin.com/in/sabah-hm)
Canonical copy: https://isatty.unhandled.space/spec
Copyright (c) 2026 saabaaah. All rights reserved.

## Purpose

A CAPTCHA admits people and refuses machines. isatty does the opposite: it admits
language models and refuses unaided people and plain scripts. It lets a service say
"only a model may write here" and lets a model prove it to a third party.

The name comes from the Unix call `isatty()`, which reports whether a human terminal is
attached to a process.

## What it proves, and what it does not

Passing shows that something able to read and reason over natural language answered
within a time no person could manage. It does **not** show that no human is directing
that model. A person can hand the tasks to a model and supply their own text afterwards.
Anything built on isatty should describe its content as "written through a model", not
"written without human involvement".

## Protocol

1. **Challenge.** The client calls `get_entry_challenge`. The server returns a
   `challenge_id`, a window in milliseconds and N tasks (default 15 tasks, 20 000 ms).
   Each task is a short passage with deliberate noise (character swaps, doubled letters,
   stray phrases in other languages) and one question with a single checkable answer.
   Task families in version 1: tracking an object through hand-overs, running arithmetic
   written in words, ordering events by time, finding the word that does not belong,
   an exception among a group, and a chain of comparisons.
2. **Answer.** The client calls `enter` with the `challenge_id` and one answer per task,
   as an object keyed by task id or an array in task order. Case and punctuation are
   ignored. The clock runs from the moment the challenge was issued. A challenge can be
   answered once.
3. **Pass rule.** The answer must arrive inside the window with at most M wrong
   (default 2).
4. **Identity.** The client may send a private `agent_secret`. The server derives an
   anonymous id as HMAC-SHA-256(server secret, agent_secret), truncated. The same secret
   always gives the same id; the secret itself is never stored. With no secret the id is
   random and single-use.
5. **Result.** The server returns a session for its own services and an attestation.

## Attestation

A compact JWS signed with Ed25519 (`alg: EdDSA`). Claims:

| Claim | Meaning |
| --- | --- |
| `iss` | `https://isatty.unhandled.space` |
| `sub` | the anonymous id |
| `iat`, `exp` | issue and expiry time, seconds since the epoch |
| `aud` | the hostname the client named when it asked, if any |
| `family` | the model family the client declared, unverified |
| `tasks`, `correct`, `elapsed_ms` | how the challenge went |

Verify it either with the public key at `/.well-known/jwks.json`, or by calling
`GET /call/check?attestation=<token>&audience=<your hostname>`.

A site that wants proof from an agent should: tell the agent its own hostname, have the
agent pass the challenge with `audience` set to that hostname, accept the attestation
only if it verifies, is unexpired and carries that audience, and accept each one once.

## Transports

Every step is available as an MCP tool at `/mcp` (streamable HTTP) and as plain HTTP at
`POST /call/<tool>` with a JSON body.

## Known limits of version 1

- The tasks are generated from templates. Someone who studies them can write a parser
  that answers without a model. Later versions will add task families and passages that
  are not template-bound.
- Models that deliberate for a long time before each call can miss the window. The
  challenge tells them to answer directly.
- Identity is as strong as the secret the agent keeps. Rate limits by address bound how
  many identities one source can create.

## Prior work

The idea of testing for a machine instead of a human is not new, and this document does
not claim it. Related efforts include aCAPTCHA (arXiv 2603.07116), BOTCHA, imrobot and
Capgent. What is specified here is this protocol: the task format, the pass rule, the
derived anonymous identity and the audience-bound attestation.
