Skip to main content

Local Lattice Programmatic Usage

This page explains the boundary between local Lattice integration and the hosted Lattice Cloud gateway. Use it when you are deciding which SDK or API a developer-facing app should call.

Local Lattice is the daemon and runtime on a machine. Lattice Cloud is the hosted gateway that third-party apps call to discover runtimes, route compute, meter requests, and handle OAuth or developer-key authorization.

Choose The Correct API

You are building...Use thisStart here
A third-party app that sends compute through Lovelace@lovelace-ai/compute-clientLattice Cloud SDK quickstart
A backend that already speaks OpenAI-compatible chatExisting OpenAI SDK with the Lattice base URLOpenAI-compatible API
Runtime setup for a user's own machineLattice Cloud personal-runtime REST or SDK helpersPersonal runtimes
Local automation on the same machine as the daemonLocal daemon IPC or CLILattice quickstart
Local model configuration for the daemonlattice-ctl and provider configurationLocal model setup

Do not use local-daemon integration as the public API for a third-party app. The app-facing API is Lattice Cloud. The local daemon can still serve the request, but it does so as a paired personal runtime behind the gateway.

Gateway SDK Quick Path

For a third-party app backend, install the Lattice Cloud compute client:

bash
pnpm add @lovelace-ai/compute-client

Use an OAuth access token when the signed-in user should authorize the app to use their compute context:

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

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

const [runtime] = await compute.listReachablePersonalRuntimes();

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." }],
});

console.log(completion.choices[0]?.message.content);

Use a developer API key instead when your product owns the traffic and should be billed directly:

ts
const compute = new ComputeClient({
  credential: { kind: "apiKey", apiKey: process.env.LOVELACE_API_KEY! },
});

Keep developer keys in trusted backend code. Browser-only code should use Sign in with Lovelace and call your backend, not the gateway directly with a developer key.

Local-Daemon Integration

Use local-daemon integration only when your code runs on the same machine as the Lattice daemon and the user has intentionally installed and configured that runtime.

Common local cases include:

  • local developer tools that inspect daemon health
  • scripts that configure local providers
  • desktop or CLI workflows that manage local sessions
  • relay setup commands that pair the daemon with Lattice Cloud

For these flows, the CLI docs are the stable public surface:

Mental Model

The clean application shape is:

  1. Your app signs in the user or authenticates with a developer key.
  2. Your backend calls Lattice Cloud through @lovelace-ai/compute-client or an OpenAI-compatible SDK.
  3. Lattice Cloud authorizes the request, chooses the target runtime, and meters the work.
  4. If the target is personal, the user's local daemon receives the work through its outbound relay connection.
  5. Your backend returns the completion response to your app.

This keeps app authorization, billing, and runtime selection in one public gateway contract while preserving local execution when the user chooses it.

Related