Configure the server

The server handlers don’t read environment variables on their own. Your app passes them in once with configureNebulasServer(). You decide where the values come from: .env, a secret manager, or anywhere else.

1. Collect your values from Nebulas

Value	Where to find it	Needed for
Nebulas API URL	Your Nebulas instance’s base URL, such as https://api.nebulas.example.com	Forms (surfaces), conversation history, branding
A2A URL	<Nebulas API URL>/v1/orchestrator/a2a	Chat
API key	Nebulas → your organization’s API keys	Sent as x-api-key to Nebulas and the agent
Project ID	Nebulas → the project that should store conversations	Chat history
Service credentials	Depends on the auth strategy	Public sites without login

2. Put them in your environment

.env.local

A2A_URL=https://api.nebulas.example.com/v1/orchestrator/a2a
NEBULAS_API_URL=https://api.nebulas.example.com
NEBULAS_API_KEY=neb_xxxxxxxxxxxxxxxxx
NEBULAS_PROJECT_ID=66b0c1f2e4b0a1c2d3e4f5a6

Keep secrets on the server

Never put the API key or any credential in a NEXT_PUBLIC_* or VITE_* variable. Those are bundled into the browser JavaScript and anyone can read them.

3. Write one shared config module

Keep the configuration in one file and import it from every route that uses the kit:

src/lib/nebulas.ts

import { configureNebulasServer } from "@gnomondigital/nebulas-kit-core";

configureNebulasServer({
  a2aUrl: process.env.A2A_URL,
  nebulasApiUrl: process.env.NEBULAS_API_URL,
  nebulasApiKey: process.env.NEBULAS_API_KEY,
  nebulasProjectId: process.env.NEBULAS_PROJECT_ID,
  // Plus the credentials for your auth strategy. See "Authentication".
});

src/app/api/a2a/route.ts

import "@/lib/nebulas"; // runs configureNebulasServer before the handler is built
import { createA2AProxyHandlerWithServiceAuth } from "@gnomondigital/nebulas-kit-core/nextjs";

export const POST = createA2AProxyHandlerWithServiceAuth({
  apiKey: process.env.NEBULAS_API_KEY,
});

Next.js loads each route separately

Every route that uses the kit (/api/a2a, /api/a2a/config, /api/nebulas-surfaces/...) must import your config module. If a route skips it, that route may run with an empty config.

All options

Option	Description
a2aUrl	URL of the A2A agent. Required for chat.
nebulasApiUrl	Base URL of the Nebulas API. Required for surfaces, branding and project lookup.
nebulasApiKey	Sent as x-api-key.
nebulasProjectId	Project where conversations are created (in the default unique project mode).
nebulasProjectMode	"unique" (default) or "name-from-metadata". See Multi-tenant sites.
nebulasAuthStrategy	"session", "client_credentials", "resource_owner_password" or "service_account".
authProvider	"auth0" or "entra". Picks the identity provider for service auth.
auth0	{ domain, clientId, clientSecret, audience }
auth0ServiceUser	{ username, password } for Auth0 Resource Owner Password.
entraService	{ tenantId, clientId, clientSecret?, scope, certificatePem?, certificatePath?, privateKeyPem?, privateKeyPath? }
entraObo	{ tenantId, clientId, clientSecret?, scope } for Entra On-Behalf-Of.
serviceAccount	{ serviceAccountId, keyId, privateKeyPem?, privateKeyPath?, metadata?, metadataUrl?, sendMetadata? }
nebulasBrandName	Name of a Nebulas brand profile used to theme the chat. See Branding.
nebulasBrandModuleId	Only search for the brand in this module.
debug	Logs every Nebulas API response body. Turn it on only while debugging.

Next: pick an authentication strategy.