Ormas

# ormas-subnet

> **Ormas pays for accepted outcomes, not inference turns.**
> A client describes a change and the test that proves it. A miner offers a firm price or a limit for the whole task. Accepted delivery pays the firm price or the miner’s settled price within the limit; a miss pays nothing.
> The client's acceptance tests are the purchase order; validators re-run them before any third-party miner is paid.

Bittensor subnet 76 · operated by Heron Cove LLC · protocol, thin client, reference miner and reference validator: MIT.

**September 23 development candidate:** start with [Public tasks and supported
environments](docs/PUBLIC_TASKS.md). It documents automatic isolated preparation,
public repository publication, profile qualification, independent acceptance and
restart recovery. A `paid` receipt on `api.ormas.ai` today reflects one
operator-run validator. Independent validator admission and the combined
validator service remain release work.

This package is normative under
[`docs/DECISIONS.md`](docs/DECISIONS.md)
(owner-locked 2026-09-10, pricing amended 2026-10-02): **the runner is the miner.**
A miner posts a `firm` or `limit` offer for a whole task and is paid only when its
delivery is **accepted** —
never for inference served, tokens spent, or hardware occupied. It is what you
give a third-party miner to connect to the Ormas subnet, local
or SN76.

## What this is

- The **miner wire protocol** (`ormas_subnet/protocol.py`) — the `ormas-runner-v1`
  data types (`RunnerRegistration`, `RepoRegistration`, `TaskDraft`, `TaskLease`,
  `TaskEvent`, `TaskReceipt`, `TaskTerminal`) that cross the wire to
  `/api/runner/v1` on the Ormas gateway.
- A **thin HTTP client** (`ormas_subnet/client.py`, `OrmasMinerClient`) for those
  routes.
- A **reference miner skeleton** (`ormas_subnet/skeleton.py`, `MinerSkeleton`) —
  register → bind a repo → poll for a lease → clone/checkout the base commit →
  call your `solve(draft, workdir) -> SolveResult` → **actually run
  `draft.verify_command`** with no shell in a credential-free environment
  (`PATH`, scratch `HOME`, `LANG`, plus the packet's explicit `NAME=value`
  assignments) on both routes → publish the result → complete. The public
  profile uses a digest-pinned OCI image with `--network none`, `--cap-drop ALL`,
  `--read-only` and resource limits. Plug in `solve`, and optionally `offer_fn` and
  `settle_fn` for per-task pricing. The receipt is built only from usage
  `solve` reports (an unknown value is never fabricated as zero), `scope_ok`
  is computed from a real `git diff` against `allowed_paths` (never asserted),
  and `verification_state` comes from the verify command's actual exit code.
  See "Completion is honest" below and `docs/protocol.md`.
- A **trivial reference solver** (`ormas_subnet/reference_solver.py`) that runs a
  shell command and commits the result, so the skeleton runs end to end with no
  model calls at all — and reports its own honest zero-usage receipt fields
  (it truly made no model call).
- The **protocol contract** in [`docs/protocol.md`](docs/protocol.md): every
  route, field, forbidden field, and error code, written so you could implement
  a miner in another language from it alone.
- Need a runner key? Sign in at [ormas.ai](https://ormas.ai) → **Miner → Runner keys** (register-only until the operator approves your qualification; [`docs/INSTALL.md`](docs/INSTALL.md)). Want to try it first without one? [`docs/QUICKSTART_LOCAL.md`](docs/QUICKSTART_LOCAL.md) runs the whole loop offline against a local stand-in gateway (`ormas_subnet/localnet.py`) — no token, no network host.

## What this is NOT

- **Not our mining logic.** Our own miner — the agentic worker, model routing,
  cost capture, orchestration loop — stays private. It competes on this same
  protocol, on the same terms as every other miner. Nothing about *how* to solve
  a task well lives here.
- **Not an inference endpoint.** A miner never serves completions and gets paid
  per token; it delivers a whole outcome and gets paid on acceptance.
- **Validator acceptance is separate from a miner finishing.** The reference
  validator clones the repo, reproduces the base failure, checks scope and tests
  the exact result, then signs accept/reject. It ships as the installed
  `ormas-validator` command. The bounded-packet (public-profile) path waits for the frozen validator
  policy, including operator-miner work. V1 requires separate owners; the explicit
  v2 alpha permits our validator to check our miner and discloses operator control.
  See [supported public tasks](docs/PUBLIC_TASKS.md) for protocol, qualification
  and rollout limits. Installing this SDK does not establish live qualification.

## Connect a miner

Re-clone or `pip install --upgrade` from the repo; the repository history was reset on 2026-10-21.
Preserve local changes before replacing an existing clone.

Install, log in, register, then check your host. Replace `your-miner-name` with
your public miner name and advertise only capabilities your miner supports:

```bash
curl -fsSL https://ormas.ai/install.sh | bash
ormas-miner login --gateway https://api.ormas.ai
ormas-miner register --miner-id your-miner-name \
  --cell task:code --cell task:code/small --cell task:lang/python \
  --cell task:publication/github-artifact-v1 \
  --cell task:acceptance/operator-run-v3 --cell task:preflight/deferred-v1
ormas-miner doctor
ormas-miner run --runner-id <assigned-id> --miner-id your-miner-name \
  --repo-id <id> --repo-url <url> --solve-command '<cmd>' \
  --cell task:code --cell task:code/small --cell task:lang/python \
  --cell task:publication/github-artifact-v1 \
  --cell task:acceptance/operator-run-v3 --cell task:preflight/deferred-v1
```

Login only saves the key locally with mode `0600`; it does not register a miner.
Doctor checks for an active registration owned by that key. The small-Python
capability example above passes its cell checks; profile/environment qualification
and claim approva