Lattice Cloud SDK Quickstart

This guide shows the user-authorized path for third-party apps. The app uses Sign in with Lovelace to obtain an OAuth access token with Lattice compute scopes, lists the user's authorized personal runtimes, and sends work to a selected runtime through Lattice Cloud.

Use this path when the user should explicitly authorize the app to use their Lovelace compute context. Use a developer API key instead when your product pays for compute and does not need the user's private runtime.

For the smallest migration from an existing OpenAI client, use the OpenAI-compatible API. For local workflows on your own machine, use the local Lattice quickstart.

Before You Start

You need:

A Lovelace developer account.
An OAuth client configured for Sign in with Lovelace.
A backend or trusted client boundary that can hold token refresh logic.
A user with at least one authorized personal runtime when you want user-owned compute.

1. Register The App

Create an OAuth client in the Lovelace developer portal. Configure the redirect URI your backend owns, then request only the Lattice scopes your app needs.

Most apps start with:

Scope	Use
`lattice:compute:inference`	List readable personal runtimes and send supported compute requests
`lattice:compute:workspace_only`	Keep eligible work on private capacity without marketplace fallback
`lattice:compute:marketplace`	Allow shared marketplace fallback when policy permits
`lattice:compute:catalog:read`	Read model and task catalog entries

Do not request lattice:compute:personal_runtime:manage unless your app is a trusted setup surface that creates, revokes, or bootstraps runtimes.

2. Send The User Through Consent

Start the standard Sign in with Lovelace authorization-code flow with PKCE. The consent screen shows the Lattice compute authority requested by your app. If the user denies consent, your app has no Lattice compute authority.

After callback validation, keep the token lifecycle in your backend or trusted client boundary. Browser-only code should not store developer API keys, bootstrap tokens, or daemon relay credentials.

3. Install The SDK

Install the public TypeScript SDK in the backend or service that calls Lattice Cloud:

bash

pnpm add @lovelace-ai/compute-client

The SDK defaults to the hosted gateway. Pass baseUrl only when your environment uses a different Lattice Cloud endpoint.

4. Create The Compute Client

Use the public TypeScript SDK with the user's OAuth access token:

import { ComputeClient } from "@lovelace-ai/compute-client";

const compute = new ComputeClient({
  credential: { kind: "oauth", accessToken },
});

The same SDK also accepts developer API keys, but the product meaning is different. OAuth represents a user-granted app relationship. Developer keys represent developer-paid traffic.

5. Discover Runtimes

List the personal runtimes the grant can read:

const reachable = await compute.listReachablePersonalRuntimes();

Show reachable runtimes as selectable execution targets. If no runtime is reachable, ask the user to reconnect a runtime instead of silently switching to marketplace capacity when your app requested private-only behavior.

6. Dispatch Work

Send work through the selected runtime:

const runtime = reachable[0];

if (runtime === undefined) {
  throw new Error("No reachable personal runtime is available.");
}

const completion = await compute.chatCompleteForPersonalRuntime(runtime, {
  messages: [{ role: "user", content: "Summarize this document." }],
});

The gateway receives one normal HTTPS request. If the selected runtime is reachable and authorized, the relay delivers sealed work to the user's outbound daemon and returns an OpenAI-compatible response.

7. Handle Failures By Code

Branch on structured error codes, not message text:

Code family	App response
`revoked_grant`, `insufficient_scopes`	Restart Sign in with Lovelace for the right grant
`personal_lattice_not_found`, `personal_lattice_execution_timeout`	Ask the user to choose or reconnect a runtime
`personal_lattice_relay_forbidden`, `personal_lattice_relay_unavailable`	Show a retry/reconnect state
Rate-limit codes	Back off using the response retry guidance

Revoked grants must fail before runtime discovery or dispatch. Private-only requests must not silently use marketplace capacity.

8. Verify With The Sample

The sample app page demonstrates token-provider integration, runtime discovery, runtime-targeted dispatch, offline handling, and revoked grant handling using only public SDK behavior.

Use it as the shape for a backend integration: the browser initiates Sign in with Lovelace and sends ordinary app input to your backend; the backend holds token refresh logic and calls Lattice Cloud.

Lovelace Developer Portal