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.