---
name: aircode-ai-gateway
description: Integrate a personal application's backend with its owner's AirCode Ø AI gateway using an instance URL, application token and live model discovery. Use for text-only Chat Completions or explicitly requested project-scoped remote sessions with live events. It does not authenticate the owner client.
---

# AirCode Ø AI gateway

Read the [API guide](https://aircodezero.com/docs/ai-gateway.md) before coding.
Use the [OpenAPI schema](https://aircodezero.com/docs/ai-gateway/openapi.json)
when configuring an HTTP tool or validating payloads. Both are public; the
documentation website is not the inference endpoint.

Use the owner's authorized instance Base URL and application token from private
environment variables `AIRCODE_AI_BASE_URL` and `AIRCODE_AI_TOKEN`. If either
is missing, ask the owner to configure it in the application's secret settings.
Do not request that a token be pasted into a public document or shared prompt.
The Base URL must be the issuing instance and end in `/api/ai-gateway/v1`.
Do not fall back to a hosted provider endpoint when it is missing.

1. Send `GET {BASE_URL}/models` with `Authorization: Bearer {TOKEN}`. Never send
   the token to aircodezero.com, a redirect destination or an unrelated origin.
2. Use the exact model `id` selected by the owner, without re-encoding it.
   Discover optional `efforts` from that model. An unavailable selection needs
   a refreshed catalogue and an explicit replacement, not a silent fallback.
3. Send `POST {BASE_URL}/chat/completions` with JSON `model` and `messages`.
   Roles are `system`, `developer`, `user`, `assistant`; content is text only.
   Include a non-empty user message and pass conversation history on each call.
   Do not add tools, images, sampling parameters, token limits or storage.
4. Read `choices[0].message.content`. Preserve missing usage/cost as unknown.
   If streaming, handle SSE comments, complete data frames, errors and `[DONE]`.
   The current stream delivers the complete validated answer at the end; never
   describe it as progressive token streaming.
5. Disable automatic generation retries. Distinguish local concurrency/rate
   refusal, provider quota, expired/revoked token, missing model and a disabled
   instance. `resets_at: null` means the provider published no reset time.

Examples for Bash/cURL, Python and JavaScript are in the guide. Run them only
within the owner's requested task. Never put a credential in source, a skill,
command-line arguments, logs or URLs; examples obtain it from the environment.
Keep invocation on the application's backend, not in browser or mobile code.

Ordinary tokens grant text generation only. They cannot open sessions or
terminals. All gateway tokens are excluded from owner login, settings, other
owner conversations and token management.

## Interactive remote sessions

Only when the owner asks to run a session on their other instance, read
https://aircodezero.com/docs/remote-sessions.md and
https://aircodezero.com/docs/remote-sessions/openapi.json. Require a token with
explicit remote-session scope. GET /session-catalog returns its one authorized
project and current engine/model/effort/permission options. The project and
agent tools run remotely; never claim local project synchronization.

POST /sessions with a stable UUID intention and the owner's selected catalogue
values. Retain the returned id. Follow POST /sessions/{id}/events with an offset
cursor; parse complete SSE frames across chunks. Reconnecting reads only. Send
input, current interaction responses and commands with stable per-session
intention ids. Never retry an uncertain effect with a new id or resend a prompt
on network reconnection. GET /sessions can recover a launched conversation.
Chat follows the provider's transcript cadence; Terminal uses raw WebSocket
output. Do not promise token-level transcript updates for every provider.
Closing the reader leaves the agent running; an explicit close command stops
it. Tools use launch permissions. Session scope is not an OS sandbox.
Reading this skill does not authorize account changes, sharing, publication,
provider installation or real compatibility benches.