Install & Environment

Packages

pnpm add @vel4ai/sdk
pnpm add @vel4ai/ai-sdk ai

@vel4ai/sdk is the core server-side SDK. Add @vel4ai/ai-sdk only to routes that use AI SDK.

Required Environment Variables

Variable	Required	Purpose
VELA_APP_ID	Yes	App identifier issued by the Vela console
VELA_APP_TOKEN	Yes	Server-side SDK credential
VELA_BASE_URL	No	Optional override for local or preview API targets

When VELA_BASE_URL is not set, the SDK uses https://api.vel4.ai. New implementations should prefer appToken; appKey remains a compatibility alias for existing code.

import { createVelaClientFromEnvironment } from "@vel4ai/sdk";

declare const process: { env: Record<string, string | undefined> };

export const velaClient = createVelaClientFromEnvironment({
  env: process.env,
});

Setup Diagnostics

Fetch API-compatible routes can return all missing environment variables before creating the client. Secret values are not returned, only variable names.

import {
  createVelaEnvironmentDiagnosticsResponse,
  getVelaEnvironmentDiagnostics,
} from "@vel4ai/sdk";

declare const process: { env: Record<string, string | undefined> };

export function checkSetup(): Response | null {
  const diagnostics = getVelaEnvironmentDiagnostics({ env: process.env });

  return diagnostics.ok ? null : createVelaEnvironmentDiagnosticsResponse(diagnostics);
}

Env-Driven Demo Boundary

Only local demos should use the shortcut that reads execution scope from these variables.

Variable	Purpose
VELA_CUSTOMER_TENANT_ID	Customer tenant for a local demo
VELA_DELEGATION_ID	Delegation for a local demo
VELA_REQUESTED_MODEL	Optional initial requested model

Production apps should not make these required application environment variables. Resolve execution scope from the app-owned database, session, or Hosted Connect return URL.