briven · docs

connect

how to connect to briven. shell first: briven setup = brand-new project · briven connect = existing project. both sign you in, mint project S3 keys when possible, and wire this folder. then SDK / HTTP / Auth / MCP.

doltgres-first + beta engine. product SQL (control + every project) runs on Doltgres (pre-1.0 — see limitations). files use MinIO S3. shell + SDK + HTTP are live; MCP is Pro/Team and project-scoped.

path 0 · from the shell (recommended)

two clear commands (do not mix):

  • briven setup / briven setup my-app — create a new cloud project + S3 + wire folder
  • briven connect / briven connect p_… — attach an existing project + S3 + wire folder

install the cli (or run one-off)

$ npx briven

or install as a dev dependency — full install options on the cli page. running bare briven with no linked folder also starts setup.

new project · briven setup

opens the browser to sign in, creates a new cloud project, mints CLI + storage keys, writes briven.json + scaffold, ready to deploy.

$ npx briven setup
$ npx briven setup --name my-app
$ npx briven setup my-app
$ npx briven setup --name my-app --template todo-app --region eu-west
  • briven setup — interactive name / region / optional template
  • --name my-app or positional my-app — create that project
  • --template todo-app — optional starter files only
  • to attach an existing id, use briven connect p_… — not setup
$ npx briven deploy
$ npx briven dev

existing project · briven connect

sign in (if needed), pick or pass a project, mint keys, wire this folder to that project.

$ npx briven connect
$ npx briven connect p_01HZ...
$ npx briven connect --project p_01HZ...
$ npx briven connect status

full lifecycle (copy-paste)

$ npx briven setup my-app   # new project
$ npx briven connect p_…    # OR existing
$ npx briven deploy

step-by-step pieces

smaller commands for scripts or power users (projects list/create/use, init, link).

$ npx briven projects list --remote
$ npx briven projects create --name my-app
$ npx briven projects create --name my-app --region eu-west
$ npx briven projects use p_01HZ...
$ npx briven projects use p_01HZ... --link
$ npx briven projects unlink p_01HZ...
$ npx briven init
$ npx briven link --project p_01HZ...
$ npx briven deploy
credentials. setup / connect store a platform user session and mint a project CLI key (+ storage key into .env.local when possible). briven logout clears everything; briven connect logout clears only the platform session. Auth browser keys are separate — see auth.

self-host? set BRIVEN_API_ORIGIN and BRIVEN_DASHBOARD_ORIGIN before setup. details on the cli page.

the three things you need (app / agent paths)

open your project in the dashboard and grab these from the project's overview / connect tab:

  • 1 · the API endpoint

    the base url your client talks to. for the hosted platform it is https://api.briven.tech. this is the apiOrigin the SDK takes. reactive subscriptions use the matching websocket origin wss://ws.briven.tech (wsOrigin).

  • 2 · your project id

    looks like p_01HZ…. it scopes every call to your project's data and functions.

  • 3 · an API key

    looks like brk_…. sent on every request as Authorization: Bearer brk_…. create one on the project's api keys page — the plaintext is shown once, so save it immediately.

path a · the @briven/client SDK (your app)

@briven/client is the framework-agnostic JavaScript client. it works in node, the browser, and any framework. (for react/svelte/vue with ready-made hooks, use the framework clients instead — same idea, less wiring.)

install

$ npm install @briven/client

create a client

import { createBrivenClient } from '@briven/client';

const briven = createBrivenClient({
  apiOrigin: 'https://api.briven.tech',     // thing 1 — the endpoint
  wsOrigin: 'wss://ws.briven.tech',         // optional, only needed for subscribe()
  projectId: 'p_01HZ...',                   // thing 2 — your project id
  token: process.env.BRIVEN_KEY,            // thing 3 — your brk_ api key
});

note: token can also be a function returning a string (or a promise of one) — handy when you mint short-lived tokens. in the browser, use a viewer-scope key; keep developer/admin keys server-side only.

call a function (node / one-shot)

// invoke runs a deployed function once over HTTP and returns a frame.
const frame = await briven.invoke('listNotes', { limit: 20 });

if (frame.ok) {
  console.log(frame.value);       // the function's return value
  console.log(frame.durationMs);  // server-side execution time
} else {
  console.error(frame.code, frame.message);
}

subscribe to live updates (react)

subscribe calls your handler once with the initial value, then again every time the rows the function touched change. it needs wsOrigin set.

'use client';
import { useEffect, useState } from 'react';
import { createBrivenClient, type InvokeFrame } from '@briven/client';

const briven = createBrivenClient({
  apiOrigin: 'https://api.briven.tech',
  wsOrigin: 'wss://ws.briven.tech',
  projectId: 'p_01HZ...',
  token: process.env.NEXT_PUBLIC_BRIVEN_PUBLIC_KEY, // viewer-scope brk_ key
});

export function Notes() {
  const [notes, setNotes] = useState<{ id: string; body: string }[]>([]);

  useEffect(() => {
    const sub = briven.subscribe('listNotes', {}, (frame: InvokeFrame) => {
      if (frame.ok) setNotes(frame.value as { id: string; body: string }[]);
    });
    return () => sub.close(); // unsubscribe on unmount
  }, []);

  return <ul>{notes.map((n) => <li key={n.id}>{n.body}</li>)}</ul>;
}

or skip the SDK — call the HTTP endpoint directly

the SDK's invoke is a thin wrapper over one endpoint. you can call it from anything that speaks HTTP:

curl -X POST \
  https://api.briven.tech/v1/projects/p_01HZ.../functions/listNotes \
  -H "Authorization: Bearer brk_..." \
  -H "Content-Type: application/json" \
  -d '{ "limit": 20 }'

# the request body IS the function's args object.
# response: { "ok": true, "value": ..., "durationMs": 12 }
#       or: { "ok": false, "code": "...", "message": "...", "durationMs": 3 }

the full HTTP surface — deployments, studio, usage, and more — is documented on the http api page.

path b · the MCP endpoint (AI agents)

MCP (Model Context Protocol) lets an AI coding agent — Claude Code, Cursor, Codex, Gemini CLI, and others — talk to your project directly: read your schema, query data, manage functions. briven exposes a streamable-HTTP MCP server at the /mcp path on your API endpoint.

beta + plan-gated. MCP access is a Pro / Teamfeature, off by default, and still rolling out. you enable it per project in the dashboard; the platform owner can also gate it globally. if you don't see the MCP panel, your plan or the platform flag is the reason.
  1. 1. in the dashboard, open your project, go to the MCP / connect panel, and turn MCP access on (Pro/Team only).
  2. 2. issue an MCP key. like API keys, the plaintext is shown once — it looks like pk_briven_mcp_… (a different prefix from the brk_ SDK keys). save it immediately.
  3. 3. the panel builds a ready-to-paste config for your agent. you can scope it read-only and pick which feature groups (docs, database, functions, storage, branching…) the agent may use.

add it to your agent

the connection is just a URL plus a bearer header. for example, with Claude Code:

claude mcp add --scope project --transport http briven \
  "https://api.briven.tech/mcp?project_ref=p_01HZ...&read_only=true"

or as a raw MCP client config, with the key in the Authorization header:

{
  "mcpServers": {
    "briven": {
      "url": "https://api.briven.tech/mcp?project_ref=p_01HZ...",
      "headers": {
        "Authorization": "Bearer pk_briven_mcp_..."
      }
    }
  }
}

note: the read_only=true query flag restricts the agent to reads; drop it to allow writes. features=database,functions narrows what the agent can touch.

what to read next