Connect an AI app to OPG

1. Confirm the local Node version.
2. Initialize local config with the OPG API URL.
3. Complete platform-level browser login.
4. Confirm .opg/opg.config.json contains the base URL and profile.

node --version
opg init --base-url https://your-opg.example.com
opg login

Do not commit .opg/credentials.json, and never put OPG_PLATFORM_TOKEN in browser-side code.

1. Create or select the current app.
2. Run app-level login to obtain a Developer Grant.
3. Pull the manifest and confirm required capabilities are exposed.
4. Run a smoke check early to catch permission or runtime gaps.

opg app create demo --name "Demo App"
opg app use demo
opg login --app demo
opg manifest pull
opg smoke --app demo

Developer Grant plaintext should appear only during creation or login. CI can inject it through OPG_API_KEY.

1. Install the SDK.
2. Create an OPG client on the server.
3. Read the manifest at startup and gate features by capability.
4. Wrap OPG calls inside your backend API instead of exposing sensitive credentials to the browser.

npm install @jamba/opg-sdk

import {
  createOpgClientFromLocalConfig,
  createOpgPlatformClient,
} from "@jamba/opg-sdk";

const opg = await createOpgClientFromLocalConfig();
const manifest = await opg.sdk.manifest();

const platform = createOpgPlatformClient({
  baseUrl: process.env.OPG_BASE_URL!,
  platformToken: process.env.OPG_PLATFORM_TOKEN!,
});

Use createOpgClientFromLocalConfig() for local development. In CI or deployment, use OPG_BASE_URL, OPG_APP_SLUG, and OPG_API_KEY.

1. Configure providers and models in the platform control plane.
2. Call opg.ai.models() from the backend to confirm available models.
3. Use opg.ai.chat() or opg.ai.responses() to execute requests.
4. Persist usage id, cost, and failure reason for debugging and limits.

const models = await opg.ai.models();

const answer = await opg.ai.chat({
  model: "gpt-4.1-mini",
  messages: [
    { role: "system", content: "You are the assistant for this app." },
    { role: "user", content: "Summarize this customer request." },
  ],
});

console.log(answer.output_text ?? answer.text);

Do not store provider keys in the frontend. When users trigger AI work, the frontend should call your application API.

1. Submit the task and return task_id immediately.
2. Poll from the backend or process the job through a worker queue.
3. Store successful outputs in object storage and failure reasons in task records.
4. Show pending, running, succeeded, and failed states in the UI instead of blocking the request.

const task = await opg.video.generateAsync({
  model: "runninghub-video",
  prompt: "A clean product intro video for OPG",
});

const result = await opg.video.wait(String(task.task_id || task.id));
console.log(result.status, result.output_url);

Use opg.upload.presignedUrl() for large files. Do not send videos or large base64 payloads inside JSON requests.

1. Run opg smoke --app demo and confirm manifest, auth, AI, uploads, and video capabilities.
2. Confirm frontend code contains no provider keys, Developer Grants, platform tokens, or database URLs.
3. Paginate list APIs; short-cache manifests; long-cache static assets; never publicly cache user data.
4. Queue AI, video, messages, webhooks, and bulk sync work.
5. Record usage, cost, task status, audit events, and failure reasons.

opg smoke --app demo
opg manifest pull
opg usage inspect --app demo
opg task list --app demo --status failed

If this step fails, fix permissions, providers, queues, object storage, and callbacks before adding UI copy.