# Orbio Incognito setup

Incognito is an account-wide requirement for inference. The dashboard power button
saves this policy on Orbio's server. Closing setup does not turn it off. Turning it
off explicitly permits ordinary inference again. A new request uses the current
policy; requests already admitted finish under their admission policy.

## If your request was rejected

Do not retry the same plaintext request or turn off privacy automatically.
A privacy flag alone does not encrypt content. Encrypt in the server or agent
runtime that originates the request, before sending anything to Orbio.

1. Read account policy: GET https://api.orbio.so/api/v1/incognito with your existing Orbio API key.
2. Choose a supported private model: GET https://api.orbio.so/api/v1/incognito/models.
3. Use the local adapter to verify fresh attestation, encrypt your prompt,
   send the encrypted request, verify its signed receipt, and decrypt the answer.
4. Keep the same Orbio API key and base URL: https://api.orbio.so/api/v1.

## Private model catalogue

GET https://api.orbio.so/api/v1/incognito/models is the authoritative private catalogue. It lists two
confidential providers, and every entry names its provider:

- phala: Phala’s live confidential text models, behind Phala’s attested gateway.
- near: NEAR AI Cloud’s own attested chat models, each with its own enclave key.

Both follow each provider’s supported billing dimensions, optionally narrowed by an
operator subset. The same model id can appear under both; pick the entry, then pass
its provider and id to the adapter. Use its maxOutput value; do not substitute a
model from the normal OpenRouter catalogue. A model listing does not replace
per-request confidential routing and receipt verification.

Supported: encrypted text, buffered Chat Completions, model-specific output budgets.
Unsupported on this route: streaming, tools, image/audio/video inputs or outputs,
embeddings, Responses and Messages. Existing normal inference is unchanged when
account privacy is off. Incognito adds no request-rate or concurrency quota.
The current Vercel host enforces a 4.5 MB buffered payload limit.

## SDK

Install the adapter in the environment that makes requests:

```sh
npm install @orbiodotso/incognito@0.1.0-alpha.4
```

Configure ORBIO_API_KEY, PRIVATE_PROVIDER and PRIVATE_MODEL. The key is on the dashboard, or from orbio_get_key_status on the Orbio MCP. The adapter requires Node.js 22.15+.

- phala (the default): the adapter gets public key evidence directly from Phala
  without credentials, checks its hardware binding and that Phala’s gateway booted a
  reviewed OS release, and encrypts before sending inference through Orbio. Phala is
  the trusted confidential-compute provider.
- near: the adapter verifies NEAR’s Intel TDX quote, that the enclave booted a
  reviewed OS release running NEAR’s own application, and NVIDIA GPU attestation
  for the model’s own key; it encrypts to that key and checks the model enclave’s
  signature over the exact request and response. NEAR serves this evidence only to
  an API key, so it arrives through Orbio, which cannot forge it. To keep Orbio out
  of the evidence path, pass your own NEAR key as nearEvidenceKey (evidence only,
  never billed). nearComposeHashes optionally narrows NEAR to reviewed releases.

No software fingerprint setup is needed for either provider. Evidence that does not
verify stops the request before anything is sent.

```js
import { createIncognitoClient } from '@orbiodotso/incognito';
const client = createIncognitoClient({
  baseURL: 'https://api.orbio.so/api/v1',
  apiKey: process.env.ORBIO_API_KEY,
});
const result = await client.request({
  provider: process.env.PRIVATE_PROVIDER, // 'phala' or 'near'
  model: process.env.PRIVATE_MODEL,
  prompt: 'Explain this document.',
  maxTokens: 1024,
});
console.log(result.text); // Returned after verification and local decryption.
```

### Routing by mode: the privacy router

Name a mode instead of a model and Orbio picks the model and provider for you, without
ever reading the prompt.

- cheapest: the lowest cost for this request at each model’s published prices: a
  prompt of this size (about four bytes a token) plus the whole output budget.
- fastest: the lowest median end-to-end latency over the last day of Orbio’s own
  private traffic. Models with fewer than five requests that day come last, cheapest first.
- auto: both at once, the best combined rank on price and speed. With no latency
  record yet it is the same as cheapest.

How it works. Encryption is to one recipient, so a prompt sealed for one enclave can
never be redirected to another. Instead, the adapter asks for the mode’s top
candidates (sending only the prompt’s size), verifies each candidate’s evidence,
seals the prompt separately to every verified key (up to four), and sends all of
the sealed envelopes. Orbio ranks them again with current prices and latency and
forwards exactly one. It moves to the next only when the first failed before
anything was held or generated, or the provider refused it before generating. An
answer is opened only with the chosen candidate’s own evidence and key.

What Orbio learns: which models a request was sealed to, which one answered, and the
prompt’s size, as it learns the model of a direct request. Never the prompt or the
answer. result.route says what was sealed to and which one answered.

```js
const routed = await client.request({ mode: 'cheapest', prompt: 'Explain this document.', maxTokens: 1024 });
console.log(routed.provider, routed.model, routed.route);
```

## MCP / agent

The user can begin with this prompt in a chat connected to Orbio MCP:

> Set up Orbio Incognito for me using the connected Orbio MCP. Read the setup guide, install the official adapter in my runtime, and enable private mode. Send “Reply with: private connection ready” as the first encrypted request, then show me the answer and verified receipt. Keep keys local. If you can’t run local commands, help me continue in my coding environment.

Call orbio_get_incognito on the hosted MCP for policy, capabilities and agent_setup.steps.
Check for terminal execution in the caller-controlled environment before installing.
A chat without that capability should provide a handoff to the user’s coding
environment; the hosted MCP cannot install or run this adapter itself. Run the
adapter in your own terminal environment, not inside hosted MCP tool arguments:

```sh
export ORBIO_BASE_URL='https://api.orbio.so/api/v1'
npx --no-install orbio-incognito doctor --provider "$PRIVATE_PROVIDER" --model "$PRIVATE_MODEL" --json
npx --no-install orbio-incognito request --input prompt.txt --provider "$PRIVATE_PROVIDER" --model "$PRIVATE_MODEL" --max-tokens 1024 --json
# Or let Orbio route by mode:
npx --no-install orbio-incognito request --input prompt.txt --mode cheapest --max-tokens 1024 --json
```

Only change the account policy when the user asks. The OAuth-only
orbio_set_incognito tool requires required and expectedVersion from current
policy discovery. A spending API key can read policy but cannot change it.
Never send prompts or private encryption keys to hosted setup tools.

## Direct API

Run the complete raw HTTP reference (no Orbio SDK needed):

```sh
curl -fSLO https://www.orbio.so/incognito/incognito-request.mjs
npm install @phala/aci-verifier@0.7.2
node --env-file=.env incognito-request.mjs prompt.txt
```

The script verifies public key evidence fetched directly from Phala, including the
reviewed OS release its gateway booted, encrypts locally,
POSTs to /chat/completions, fetches the signed receipt and session evidence,
checks the exact request/response binding, then decrypts with the local private
key. Orbio never receives that private key. This reference speaks Phala’s protocol;
use the adapter for NEAR, which follows NEAR’s documented E2EE: an Ed25519 model key
from GET https://api.orbio.so/api/v1/incognito/near/attestation?model=&nonce=, the headers X-Signing-Algo,
X-Client-Pub-Key, X-Model-Pub-Key and X-Encryption-Version, and the model enclave’s
signature from GET https://api.orbio.so/api/v1/aci/receipts/{completion id}.

The router over raw HTTP: GET https://api.orbio.so/api/v1/incognito/route?mode=&max_tokens=&prompt_bytes=&limit=
returns the ranked candidates (metadata only); POST https://api.orbio.so/api/v1/incognito/route takes
{ mode, candidates: [{ headers, body }] }, one sealed envelope per candidate, and the
answer names the envelope that answered in X-Incognito-Candidate and its provider in
X-Incognito-Provider.

## Billing

A private answer is charged what its provider states for it (Phala’s stated cost,
NEAR’s own per-request cost), never an estimate, and only if the answer was released
to you after its evidence verified. An answer withheld for any reason is never billed.

## Error codes

- private_encryption_required: account requires privacy; configure local encryption.
- private_model_unsupported: choose from /incognito/models.
- private_endpoint_unsupported: use encrypted, buffered text /chat/completions.
- e2ee_v2_required / invalid_e2ee_header: use the adapter's encryption format.
- private_key_changed: verify fresh attestation and encrypt a fresh request.
- private_identity_unverified: the provider’s evidence failed; nothing was sent.
- private_upstream_rejected: the provider refused the request.
- private_request_deadline: too little time was left to generate; nothing more
  was sent. Send a fresh encrypted request.
- Any withheld answer (its evidence did not verify) is never billed.
- invalid_route / invalid_route_query: use the adapter's routing (mode) options.
- private_policy_changed: reread policy before changing the setting again.

Private inference currently accepts one encrypted text message and buffered
responses. It does not silently route unsupported models, images or tools to
ordinary providers. Model limits and transport safeguards still apply. The
account setting enforces private inference; it does not encrypt a legacy client
by itself or make unrelated hosted MCP tools private.