# Sponsored inference mesh

Omnius can route generation to explicitly trusted sponsors. A sponsor enables specific models, capacity and quotas; other trusted Omnius instances can use that capacity for their main agents, delegates and helpers through the same configured inference endpoint. Tools execute at the requesting instance. The sponsor runs generation only and does not receive a new conversation in its transcript.

This transport does not repair OpenCode service access. Provider authentication, access restrictions and quotas remain authoritative. Requests are never repeated on another sponsor after a dispatch, a partial response or a provider denial.

## Trust and privacy

Each instance keeps a persistent private identity and shares its public peer ID. Operators exchange peer IDs and reachable multiaddresses through a trusted channel. Both ends explicitly allow the other identity. There is no public peer autodial or open inference proxy.

Noise authenticates and encrypts the application stream, including through configured libp2p circuit relays. A relay can observe addressing, timing and sizes. The selected sponsor and inference provider receive plaintext. Local administrators can access their own running process and keys. See the primary [Noise specification](https://github.com/libp2p/specs/blob/master/noise/README.md) and [circuit relay protocol](https://libp2p.io/docs/circuit-relay/).

The Tracker repository informed the routing, framing, lifetime and capacity patterns. The first runtime supports direct TCP, secure WebSockets and explicitly configured circuit relays. Other Tracker carriers are inventoried in `.aiwg/planning/sponsored-inference-mesh-20261017/` but are not implemented here. No GitHub Pages deployment or browser engine is required.

## Configure an instance

Run `omnius mesh init`. This creates disabled configuration and a private identity in the Omnius config directory under `mesh/`. It prints the configuration path and public peer ID, never the private key or gateway token. Alternatively use a private dedicated directory:

```sh
omnius mesh init --config /private/omnius-mesh/config.json
omnius mesh identity --config /private/omnius-mesh/config.json
```

The directory must be owner-only (`0700`); configuration, identity and ledger are private files (`0600`). Initialization refuses to overwrite existing configuration. Preserve the identity across restarts. Replacing it requires peers to deliberately trust the replacement.

Edit the private configuration before enabling it. The following is a schema example; replace the peer IDs, addresses and model with actual operator-approved values. Keep the random `gatewayToken` generated by initialization.

```json
{
  "version": 1,
  "enabled": true,
  "gatewayPort": 11436,
  "gatewayToken": "KEEP_THE_PRIVATE_RANDOM_TOKEN_CREATED_BY_INIT",
  "listenAddresses": ["/ip4/0.0.0.0/tcp/4010"],
  "relayAddresses": [],
  "peers": [
    { "peerId": "TRUSTED_SPONSOR_PEER_ID", "addresses": ["/dns4/sponsor.example/tcp/4010/p2p/TRUSTED_SPONSOR_PEER_ID"] }
  ],
  "allowedRequesters": ["TRUSTED_ORIGIN_PEER_ID"],
  "offers": [
    {
      "id": "local-approved-model",
      "model": "EXACT_APPROVED_MODEL_TAG",
      "endpoint": "http://127.0.0.1:11434",
      "protocol": "ollama",
      "admission": "managed-ollama",
      "contextTokens": 32768,
      "maxOutputTokens": 4096,
      "capacity": 1,
      "maxRequestsPerMinute": 10,
      "maxTokensPerDay": 100000
    }
  ]
}
```

An origin-only instance leaves `offers` empty. A sponsor-only instance may leave `peers` empty, but must list permitted origin IDs in `allowedRequesters`. Discovery advertises only opaque offer IDs, model identifiers, expiry and declared capacity. Provider endpoints and keys stay local.

Local sponsorship requires the discovered managed Ollama broker endpoint. Before enabling actual accelerator-backed work, follow the repository's GPU reservation and exact model-placement preflight. Starting the mesh does not load/download a model. Declaring capacity is not proof of GPU placement.

For an authorized remote provider use `admission: "remote-authorized"`, an HTTPS endpoint and an explicit protocol (`ollama`, `openai-chat`, or `anthropic-messages`). Set `apiKeyEnv` to a host environment variable containing your own provider key when required. The configuration stores the variable name, and discovery never transmits the key. Endpoints with credentials in the URL, query strings or fragments are rejected.

## Run and use it

```sh
omnius mesh start --config /private/omnius-mesh/config.json
omnius mesh status --config /private/omnius-mesh/config.json
```

Run the first command in an owned foreground process or your normal supervisor. It prints actual listen addresses and the loopback gateway URL. The gateway binds only `127.0.0.1` and requires the private generated bearer token. It rejects browser Origin requests; browser chat continues through its existing authenticated daemon.

Use `/endpoint mesh` to select the enabled default private mesh configuration. This resolves its exact loopback port and gateway token only after selection; typing suggestions never reads credentials. Then choose an advertised model with `/model`. An already configured custom mesh URL keeps its own credentials; the default token is never copied to another host. For a dedicated `--config` instance, explicitly configure its printed gateway URL, protocol `openai-chat` and its own private `gatewayToken`. Configure the browser daemon with the same endpoint. Main and child generation then use the same mesh route policy; the gateway never calls daemon `/v1/chat`.

For peers behind NAT, configure an operator-controlled reachable circuit relay and exchange the resulting full circuit multiaddress. Relay trust does not grant inference permission. No public relay is selected automatically.

`mesh status` shows bounded discovery, selection, admission and terminal metadata. It excludes prompts, completions, tool arguments and provider secrets. `/v1/models` is passive discovery and does not generate tokens. A missing model/capacity or a provider error is explicit.

Stop the owned mesh process with SIGINT/SIGTERM. It stops admission, cancels owned calls and closes its transport. Configuration changes, including trusted peers and offers, take effect after a controlled restart. Do not remove or edit a live ledger/ownership file. Abrupt process death can leave an ownership lock; verify the recorded owner has exited before explicit offline recovery. Never delete the ledger to recover a lock: its metadata prevents interrupted requests from executing again after restart.

The ledger reserves prompt-plus-maximum-output token estimates conservatively before dispatch and retains bounded request metadata. Failed/cancelled requests can still consume reservation; this favors respecting operator budgets. Once replay-history capacity is full, sponsorship fails closed until the operator performs a deliberate retention/reset procedure while stopped. Completed content is not stored in this ledger.

## Verification limits

Source acceptance uses genuine loopback peer transports and fixture providers, not CUDA or paid inference. These tests establish transport, framing and lifecycle behavior; they do not establish that any external provider will accept a request, that a GPU is correctly placed, or that all Tracker relay carriers have been ported.
