Soba Docs

Get started

Quickstart

Point your OpenAI client at Soba, prove it with one request, then let your users connect the AI they already pay for.

Or let your agent do all of this

npx skills add https://soba.so/skill teaches the coding agent you already have open how to integrate Soba, and the MCP server lets it read this app's checklist and mint its own key. The steps below are what it does, and Implement Soba is the whole procedure with every component live.

1. Get a key#

From the project's folder:

Terminal
npx @soba-so/cli login

It opens your browser to sign this terminal in, once per machine. Then you pick the app in the terminal, or make a new one there, and its keys land in .env.local: SOBA_KEY, a development key for your machine, and SOBA_PROD_KEY for production, where you set SOBA_KEY to that value. Add --headless on a machine with no browser and open the link it prints.

With nobody at the terminal (a script, a coding agent), answer the questions with flags: --workspace <name> and either --app <name> or --new <name>. Later, soba link points another folder at an app without the browser, and soba apps lists and makes them. Every command is in The soba CLI.

Or copy one from your dashboard's Keys page. Either way it is shaped sk_soba_<id>.<secret>, shown once, and it is the only credential your server needs.

2. Change the base URL#

JavaScript
import OpenAI from "openai";

const soba = new OpenAI({
  baseURL: "https://api.soba.so/v1", // the only line that changes
  apiKey: process.env.SOBA_KEY,
});

Everything else stays: your prompts, your tools, your streaming, your error handling.

3. Pass the user's id#

JavaScript
import { sobaUserId } from "@soba-so/sdk/identity";

const response = await soba.chat.completions.create({
  messages: [{ role: "user", content: "What is Soba?" }],
  model: "auto",
  user: sobaUserId(session.user.username),   // ← the one addition
});

user is a hint in the OpenAI API and load-bearing here. It is how a run is attributed to a person, and therefore how Soba knows whose machine it may reach.

Resolve it on the server, and pick an id that outlives your database. session.user.id is usually a key minted at sign-up: reset or move the database and the same person arrives as somebody new, leaving the machine they paired attached to an id you will never send again. If your own ids are stable, send them; if they are not, sobaUserId derives one. The whole argument, and how to tell whether it has already happened to you, is on Identifying users.

4. Prove it#

Terminal
curl https://api.soba.so/v1/chat/completions \
  -H "Authorization: Bearer $SOBA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "soba/echo", "user": "usr_123",
        "messages": [{ "role": "user", "content": "ping" }] }'

soba/echo is answered by Soba itself. No machine, no provider key, nothing billed, and it still proves the three things that actually break: the key, the base URL and the user field.

You are done with the required part

Every run is now metered per user and bounded by a spend ceiling. A user with nothing connected is handed back to the client you already have, so nothing changes for them yet. Everything below is optional.

5. Let users bring their own AI#

JavaScript
// Your settings page
<SobaProvider sessionEndpoint="/api/soba/session">
  <ComputeSettings />
</SobaProvider>

// Your signed-in navbar, if your AI only works once a user connects
<SobaProvider sessionEndpoint="/api/soba/session" sessionCacheKey={user.id}>
  <ConnectButton />
</SobaProvider>

/api/soba/session is a route of yours that mints a session for the signed-in user and returns it. It takes four lines; see Components. <ComputeSettings /> is the connect step for someone with nothing paired, and the status of their machines once they have: asleep, offline or serving a run. If nothing in your app can run until a user connects their own compute, <ConnectButton /> goes in the navbar of your signed-in layout, not a root layout that also renders your login page: see where to mount it. Then put <ConnectNudge /> above each control that starts a run, so a user with nothing connected is told what to do there. A local model or a key of their own starts serving runs immediately, with no change at your call site. Their Claude or ChatGPT plan is served by Claude Code or Codex, which chat/completions cannot drive; that is what step 6 is for. See Components and Pairing.

6. Reach Claude Code and Codex#

chat/completions is stateless and the caller owns the loop, so it reaches models. Reaching a full agent runtime means letting Soba own the loop:

JavaScript
import { Soba } from "@soba-so/sdk";
import { sobaUserId } from "@soba-so/sdk/identity";

const soba = new Soba({ apiKey: process.env.SOBA_KEY });

const run = await soba.run({
  user: sobaUserId(session.user.username),
  model: "auto",
  prompt: "Summarise everything I saved this week",
  tools: [listNotes, readNote],   // your code, executed in your app
});

for await (const event of run) {
  if (event.type === "delta") process.stdout.write(event.text);
  if (event.type === "done") console.log(event.usage);
}

See Runs and the SDK.

7. Charge for it#

A plan sets the price, the allowance, what happens past it, which compute it may use, and what a user earns for connecting their own. It compiles to a route on every run, so pricing and routing stay one decision.

Next#

Privacy · Terms · DPA · © 2026 Soba resolved = machine grant ∩ broker request