# Umbra (full agent context)

> Umbra is a private-prompt inference API on Apple Silicon. OpenAI- and
> Anthropic-compatible endpoints serve open-weight, uncensored, and community
> GGUF models that major hosts refuse. Prompts are not logged. Hardware
> attestation aims to prevent the Mac owner from reading them. Alpha.

This file supplements https://tryumbra.dev/llms.txt with API contracts,
routing semantics, and operator notes for AI agents. Keep under 500KB.

## API base

- OpenAI-compatible: `https://api.tryumbra.dev/v1`
- Anthropic-compatible: `POST https://api.tryumbra.dev/v1/messages`
- List models: `GET https://api.tryumbra.dev/v1/models`
- Provider health: `GET https://api.tryumbra.dev/v1/providers`
- Network stats: `GET https://api.tryumbra.dev/v1/stats`
- Coordinator attestation: `GET https://api.tryumbra.dev/v1/attestation`

Auth: `Authorization: Bearer umbra-...` on inference calls. Mint keys at
https://tryumbra.dev/console/keys after sign-in. Agent self-onboard (alpha,
rate-limited): `POST /v1/auth/signup` then `POST /v1/keys` with the session
bearer.

## Routing and trust

- Default `trust_level` floor is `hardware` when omitted.
- Tiers: `none`, `self_signed`, `hardware` (live for MDA Mac providers),
  `code_attested` (reserved; not independently verified yet).
- A model may appear in `/v1/models` while no provider is online. Inference
  then returns HTTP 503 with message
  `no provider meets trust_level and integrity for this model`.
- Integrity checks pin GGUF repo, revision, quant, and SHA-256 digest per
  catalog entry.

## Common HTTP errors

| Status | Meaning |
|--------|---------|
| 401 | Missing or invalid API key |
| 404 | Unknown model id |
| 503 | No eligible provider (offline, trust floor, or integrity mismatch) |
| 429 | Rate limit |

## Provider onboarding (Mac)

1. `curl -fsSL https://tryumbra.dev/install | sh`
2. `umbra login`
3. Install MDM enrollment profile from https://mdm.tryumbra.dev/mdm/enroll
4. `umbra host` (or managed host via `umbra host-run`)
5. `umbra status` — confirms coordinator admission

Docs: https://tryumbra.dev/console/setup and
https://tryumbra.dev/become-a-provider

## Trust documentation

- Attestation chain: https://tryumbra.dev/docs/attestation
- Threat model: https://tryumbra.dev/docs/threat-model
- Blog (privacy + attestation): https://tryumbra.dev/blog

## Legal

- Privacy: https://tryumbra.dev/privacy
- Terms: https://tryumbra.dev/terms
- Provider agreement: https://tryumbra.dev/provider-agreement

## Optional

- Try without signup: https://tryumbra.dev/try
- Live model catalog UI: https://tryumbra.dev/console/models
- Network stats UI: https://tryumbra.dev/console/stats