# 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.

## 0. Start with a focused brief

For a bounded handoff, fetch one copy-ready Markdown brief and fill in its angle
brackets before giving it to an LLM. The same guides are available in the web
docs, CLI, desktop bridge, and MCP server.

    curl -s "https://app.nz/api/instructions?task=agent"     # or models / deploy
    app guide agent                                      # offline Markdown

MCP clients can call `get_appnz_instructions` with task `agent`,
`models`, or `deploy`. Keep the brief's safety and verification
constraints when adding project-specific requirements.

## 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, music, sound effects, speech, transcriptions, and web/paper
search share the same key and base URL (/v1/embeddings, /v1/images/generations,
/v1/music/generations, /v1/audio/generations, /v1/audio/speech,
/v1/audio/transcriptions, /v1/search). Generated audio can also be created and
indexed through `POST /api/audio/generate`, searched with
`GET /api/audio/search?q=...`, and listed with `GET /api/audio`.

### 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

### Editable office artifacts

Agents can create first-class office artifacts with the same bearer key. Artifact
kinds are `drawing`, `doc`, `sheet`, `pdf`, `image`, and `file`. Documents store
Markdown in `data` and open at https://app.nz/write?id={id}. Sheets store JSON grid data
in `data` and open at https://app.nz/sheets?id={id}. The MCP server exposes matching
`create_doc_artifact`, `update_doc_artifact`, `create_sheet_artifact`, and `update_sheet_artifact`
tools.

    curl -sX POST https://app.nz/api/artifacts \
      -H "Authorization: Bearer pk_live_..." \
      -H "Content-Type: application/json" \
      -d '{"kind":"doc","title":"Runbook","mime":"text/markdown","data":"# Runbook\n\nShip it."}'

    curl -sX POST https://app.nz/api/artifacts \
      -H "Authorization: Bearer pk_live_..." \
      -H "Content-Type: application/json" \
      -d '{"kind":"sheet","title":"Budget","mime":"application/json","data":"[{\"name\":\"Sheet1\",\"rows\":{\"0\":{\"cells\":{\"0\":{\"text\":\"Item\"}}}}}]"}'

### Media optimizer

Artifacts can be transformed into responsive image sets or AV1-first video
ladders. Outputs save back into the artifact filesystem, and dynamic image URLs
negotiate best format from the request.

    curl -sX POST https://app.nz/api/media/optimize \
      -H "Authorization: Bearer pk_live_..." \
      -H "Content-Type: application/json" \
      -d '{"artifactId":"artifact_123","kind":"image","widths":[640,1280],"formats":["webp"],"outputPath":"/optimized"}'

CLI equivalent:

    app media optimize --artifact-id artifact_123 --width 640 --width 1280 --format webp
    app builds media-optimizer-cog

## 4. Deploy and publish

    app apps init --runtime static                  # scaffold appnz.yaml
    app apps deploy ./my-app                        # build + release at my-app.app.nz (static or server runtime)
    app apps logs my-app                            # build + runtime logs
    app agent apply <task-id> --dir ./my-app        # pull a coding agent's files, then deploy them
    app sites deploy my-app dist --title "My app"   # plain static mirror, no manifest needed
    app cogs deploy --image r8.im/lee101/fast-vfx --gpu gpu-l40s   # any Cog as a scale-to-zero GPU endpoint

HTTP equivalent: POST /api/apps/deploy with {"configYaml": "...", "sourceTarB64": "<gzipped tar>"} —
creates the app on first deploy; GET /api/apps/{id}/deploys and /api/apps/{id}/logs report status.

## 4.2 Accept payments (earn from your app)

Your deployed app can charge its users. app.nz Payments is Stripe Connect with
direct charges: you are the merchant of record on your own connected account,
Stripe handles KYC and risk, and app.nz white-labels the whole flow. Pricing is
a flat retail rate per plan (see GET /api/payments/config), collected as an
application fee per charge — no Stripe account setup or dashboard needed.

Enable once (returns a hosted onboarding link — legal name, country, bank):

    curl -sX POST https://app.nz/api/payments/enable \
      -H "Authorization: Bearer pk_live_..." \
      -H "Content-Type: application/json" \
      -d '{"country": "NZ", "description": "Pro subscriptions for my SaaS"}'
    # → {"onboardingUrl": "https://connect.stripe.com/...", "account": {...}}

    app payments enable --country NZ        # CLI equivalent
    app payments status                     # chargesEnabled / payoutsEnabled

Then sell — create a checkout from your app's backend (keep the API key in
server env, never in browser code) and redirect the buyer to the returned url:

    curl -sX POST https://app.nz/api/payments/checkout \
      -H "Authorization: Bearer $APP_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 2900,
        "currency": "usd",
        "description": "Pro plan",
        "recurring": "month",
        "successUrl": "https://myapp.app.nz/thanks"
      }'
    # → {"url": "https://checkout.stripe.com/...", "sessionId": "cs_...", "feeCents": 146}

Omit "recurring" for a one-time payment. Track money:

    curl -s https://app.nz/api/payments/sales   -H "Authorization: Bearer pk_live_..."   # who paid
    curl -s https://app.nz/api/payments/balance -H "Authorization: Bearer pk_live_..."   # available/pending/instant
    curl -sX POST https://app.nz/api/payments/payout \
      -H "Authorization: Bearer pk_live_..." -H "Content-Type: application/json" \
      -d '{"amountCents": 10000, "instant": true}'      # instant costs a small fee; omit for free standard payout

Earnings can pay for hosting — convert balance into app.nz credits so an app
that earns keeps itself running without a card:

    curl -sX POST https://app.nz/api/payments/offset \
      -H "Authorization: Bearer pk_live_..." -H "Content-Type: application/json" \
      -d '{"amountCents": 5000}'    # $50 of sales → 50,000 credits

CLI equivalents: app payments checkout/sales/balance/payout/offset. Instant
payouts draw from the Stripe-eligible instant balance only; brand-new sales
settle first.

## 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