Server functionsRuntime contract

Server RPC

How app server functions are discovered, bundled, executed, logged, and separated from browser SDK code.

Function Contract

Each server/*.ts file becomes an RPC function callable as airglow.rpc(fileNameWithoutExtension, payload). The function receives the parsed payload and returns JSON-serializable data.

server/exchange.tsts

export default async function exchange(payload: { code: string; redirectUri: string }) {
  const clientSecret = process.env.GOOGLE_CLIENT_SECRET;
  if (!clientSecret) {
    throw new Error("GOOGLE_CLIENT_SECRET is missing");
  }

  return { ok: true };
}

Secrets And Environment

Client settings use the CLIENT_ prefix and are exposed to the extension. Server secrets have no prefix and are only available through process.env inside server functions.

.env conventionsbash

# airglow-apps/.env
CLIENT_ANTHROPIC_API_KEY=sk-ant-dev-visible-to-the-extension

# airglow-apps/hn-tagger/.env
ANTHROPIC_API_KEY=sk-ant-server-side-only

No SDK on the server

Server functions do not receive airglow.*. They run as Node/serverless code and should use regular server libraries, server environment variables, and platform helpers.

Errors And Observability

Every RPC request gets a request id in the server logs.
Successful RPC calls emit rpc_call_started and rpc_call_finished events.
Server exceptions become stable API error envelopes with error, code, and requestId.
Do not put raw tokens, cookies, authorization headers, or provider payloads into logs.

Error envelope shapejson

{
  "error": "RPC call failed",
  "code": "RPC_HANDLER_ERROR",
  "requestId": "req_01h..."
}

Anthropic Calls

Paid model calls

For Airglow-provided model access, use the platform server RPC/proxy once it is enabled for your app. Until then, direct Anthropic calls should use an app-owned key or stay local-dev only.