# app.nz — build an agent

app.nz is the AI agent cloud. This file is self-contained: read it top to bottom
and you can integrate the OpenAI-compatible gateway, launch a cloud coding agent,
and deploy — using one API key.

## 1. Authentication

Create a key in the dashboard or with the CLI, then send it as a bearer token on
every request. The base URLs:

- Control plane: https://app.nz
- Model gateway (OpenAI-compatible): https://app.nz/v1

    Authorization: Bearer pk_live_...

Get a key from the CLI:

    curl -fsSL https://app.nz/cli.sh | sh
    app login --api-key pk_live_...
    app keys create --name "my agent"

## 2. Call any model (OpenAI-compatible)

Point any OpenAI SDK at the gateway. Use `app/auto` to let the router pick a
model from the prompt, a variant (`app/auto-code`, `app/auto-fast`, `app/auto-cheap`, `app/auto-reasoning`, `app/auto-vision`, `app/auto-image`)
to bias it, or `provider/model` to pin a specific upstream model.

    curl -s https://app.nz/v1/chat/completions \
      -H "Authorization: Bearer pk_live_..." \
      -H "Content-Type: application/json" \
      -d '{
        "model": "app/auto",
        "messages": [{"role": "user", "content": "Explain CRDTs in one paragraph."}],
        "stream": false
      }'

Python (OpenAI SDK), same code you already have — only base_url and api_key change:

    from openai import OpenAI
    client = OpenAI(base_url="https://app.nz/v1", api_key="pk_live_...")
    r = client.chat.completions.create(
        model="app/auto-code",
        messages=[{"role": "user", "content": "Write a Go function to reverse a slice."}],
    )
    print(r.choices[0].message.content)

Anthropic-compatible messages (supports thinking) live at https://app.nz/v1/messages.
Embeddings, images, speech, transcriptions, and web/paper search share the same
key and base URL (/v1/embeddings, /v1/images/generations, /v1/audio/speech,
/v1/audio/transcriptions, /v1/search).

### Bring your own provider key (BYOK)

Keep using your own upstream key while routing through app.nz. Store it once per
provider; from then on the gateway uses your key for that provider (it takes
precedence over the platform key) so calls bill against your provider account.
One active key per provider — re-POSTing replaces it.

    # Store your OpenAI key (swap provider for anthropic, google, groq, ...).
    curl -sX POST https://app.nz/api/gateway/provider-keys \
      -H "Authorization: Bearer pk_live_..." \
      -H "Content-Type: application/json" \
      -d '{"provider": "openai", "api_key": "sk-..."}'

    curl -s https://app.nz/api/gateway/provider-keys -H "Authorization: Bearer pk_live_..."   # list (masked)
    curl -sX DELETE "https://app.nz/api/gateway/provider-keys?id=..." -H "Authorization: Bearer pk_live_..."  # revoke

After storing it, ordinary `/v1/chat/completions` calls to that provider use your
key automatically — your code does not change.

## 3. Launch a cloud coding agent

Hand a repo and a plain-English prompt to an agent; it branches, codes, tests,
and opens a pull request. `GET /api/agents/config` (no auth) returns the option
lists so a UI can render the form before sign-in.

    curl -sX POST https://app.nz/api/agents/tasks \
      -H "Authorization: Bearer pk_live_..." \
      -H "Content-Type: application/json" \
      -d '{
        "prompt": "fix the failing CI test and open a pull request",
        "repo": "acme/api",
        "model": "app/auto-code",
        "reasoningEffort": "high",
        "skills": ["jj", "visualbench"],
        "spendCapUsd": 2.00,
        "autoMergePr": false
      }'

Then poll the normalized trace (steps, messages, diff, PR):

    curl -s https://app.nz/api/agents/tasks/{id} -H "Authorization: Bearer pk_live_..."

### One API, every provider (Agents SDK)

Set `source` to choose who runs the task — `openpaths` (default, our cloud
with our credentials), `devin`, `cursor`, or `codex-cloud`. Every provider's
result normalizes back into the same task trace.

    curl -sX POST https://app.nz/api/agents/tasks \
      -H "Authorization: Bearer pk_live_..." \
      -H "Content-Type: application/json" \
      -d '{"source": "devin", "prompt": "fix failing CI and open a PR", "repo": "lee101/edukids", "baseBranch": "main"}'

CLI equivalent:

    app agents-sdk run "fix failing CI and open a PR" --source devin --repo lee101/edukids
    app agents-sdk providers        # which providers are configured

## 4. Deploy and publish

    app deploy --app my-ai-app --region fsn1        # ship a container to CPU/GPU
    app cogs deploy --image r8.im/lee101/fast-vfx --gpu gpu-l40s   # any Cog as a scale-to-zero GPU endpoint
    app sites deploy my-app dist --title "My app"   # static site live at my-app.app.nz

## 4.5 Rent compute and SSH in

Provision a machine, then SSH into it. Register your public key once
(`app ssh-key add` / `POST /api/user/ssh-keys`) — it is injected at boot so
`app ssh <id>` works with no extra setup. `GET /api/gpu-types` lists machine ids/prices.

    # Provision (cpx21 CPU box, or a GPU like gpu-a100)
    curl -sX POST https://app.nz/api/instances \
      -H "Authorization: Bearer pk_live_..." \
      -H "Content-Type: application/json" \
      -d '{"machineType": "cpx21", "label": "scratch"}'

    curl -s https://app.nz/api/instances -H "Authorization: Bearer pk_live_..."          # list (with running cost)
    curl -s https://app.nz/api/instances/{id}/ssh -H "Authorization: Bearer pk_live_..." # {host,user,port,command}
    curl -sX DELETE "https://app.nz/api/instances?id={id}" -H "Authorization: Bearer pk_live_..." # terminate

CLI equivalent:

    app instance create --type cpx21 --label scratch
    app instance list                 # status + cost
    app ssh <id>                      # log straight in (root@host)
    app ssh <id> -- uname -a          # run one command
    app instance terminate <id>

### Usage and billing (models + servers)

One call returns model spend, server running-cost, and credit balance — the
whole bill, automatable:

    curl -s https://app.nz/api/usage -H "Authorization: Bearer pk_live_..."
    app usage          # or: app billing usage

## 5. Conventions

- Auth: `Authorization: Bearer pk_live_...` on every non-public route.
- Bodies and responses are JSON; successful writes return `{ "success": true, ... }`.
- Errors return a non-2xx status with `{ "error": "message" }`.
- Full HTTP reference: https://app.nz/docs
- Model directory: https://app.nz/models
- Index for agents: https://app.nz/llms.txt