Where your app runs
Your app runs on your server, people sign in at account.northlight.ai, and the agent work runs on each person's own Northlight runtime. Northlight does not host your app's code.
Your app runs on a server you choose. Northlight hosts two other things: the directory at account.northlight.ai, and each person's agent runtime. Northlight does not host your app's code, and there is no flow for deploying it to Northlight.
| Piece | Runs where | What it does |
|---|---|---|
| Your server | Anywhere you choose. Your laptop while you develop. | Your pages and logic. It holds the app's private signing key and a stored connection for each person. |
| The directory | https://account.northlight.ai, hosted by Northlight | Accounts, app registration (the console at /console), consent, tokens and the marketplace. |
| The person's runtime | Hosted by Northlight, one per person | Their agents, runs, files, documents and providers (sms, search and others), using their own AI subscription. |
"Build on Northlight" therefore means three things. Your app's agent work runs on the person's Northlight-hosted runtime. People sign in to your app with their Northlight account. And your app can be listed in the Northlight marketplace.
- Sign-in. Your
/auth/loginroute sends the person to the directory with your client ID and the scopes you ask for. The directory shows its consent page and returns them to your registered redirect URI with a one-use code. - Token. Your server exchanges the code for tokens. It proves it is your app by signing the request with its private key. No client secret exists. The result is a connection: a short-lived access token, a rotating refresh token, and the URL of that person's runtime. See Apps and sign-in.
- Calls.
oauth.client(userId)loads the stored connection, refreshes the access token when it needs to, and returns a client on that person's runtime. You callruns.*andproviders.*on it. See Connections and Runs.
The person's AI subscription pays for model calls, and what your app may do on their runtime is limited by the scopes they approved. See Scopes and grants.
What you operate
You operate your server, its sessions, its database and its ConnectionStore. You register the app in the console and keep its key pair. Northlight operates the directory and the runtimes; you do not run either, and there is no local Northlight to start. If you run crouter yourself and want a runtime of your own, that is a different path: see crouter.docs.northlight.ai.
The directory's discovery document at https://account.northlight.ai/.well-known/openid-configuration lists the endpoints, the S256 PKCE method and private_key_jwt as the only token authentication method (checked on production).
Use your coding agent
What npx @north-light/sdk init and skill install for Claude Code, Codex, Cursor and Copilot, where the skill lives, and how it stays in step with your SDK version.
Apps and sign-in
What registering an app creates, how an app proves who it is with a key pair, and the authorization-code flow with PKCE that OAuth2Client runs.