SDK Overview — bRRAIn Docs

The bRRAIn Platform SDK v1.2.0 is a typed Go client that extensions use to reach a brain pod's vault, ingestion, models, MCP tools, policy, audit and notifications.

SDK Overview

The bRRAIn Platform SDK is a typed Go client for building extensions that run on an organization's brain pod. One client gives your code governed access to the pod's platform services: the vault, policy-aware ingestion, models through the LLM Registry, MCP tools, the integration catalog, OAuth and vendor credentials, the Security Policy Engine, the audit chain and the Notifier.

| | | | --- | --- | | Module | github.com/Qosil/bRRAIn/pkg/platform-sdk | | Package | platformsdk | | Version | 1.2.0 (platformsdk.SDKVersion), semver-stable within 1.x | | Go | 1.25.9 or later | | Access | Private repository; access comes with a developer seat (five free per organization). See Installation. |

Where your code runs

An SDK-based extension is a binary that the brain pod's extension supervisor starts. The supervisor checks the extension's manifest.json, gives the process a port and a small, fixed environment, and reverse-proxies the routes the manifest declares to that port.

Person (Nexus, console, MCP client)
        |
  console proxy / brain pod routes
        |
  your extension  (started by the supervisor)
        |  platformsdk.Client
        v
  brain pod internal API
    vault · ingestion · LLM Registry and the Handler · MCP Gateway
    policy engine · audit chain · Notifier · integrations · credentials

The supervisor hands your process everything the client needs:

| Variable | Meaning | | --- | --- | | BRRAIN_INTERNAL_URL | The pod's internal API root. Pass it as Options.BaseURL. | | BRRAIN_INTERNAL_TOKEN | The shared secret the internal API checks. Pass it as Options.Token. | | BRRAIN_APP_SLUG | Your manifest's slug. The client reads it automatically. | | BRRAIN_APP_VERSION | Your manifest's version. | | the variable named in listen.port_env | The port your process listens on. |

There is no public SDK endpoint, no API key to generate and nothing to run beside your code. The client talks to the pod your extension is installed on.

The sub-clients

You build one *platformsdk.Client at start-up and call sub-client accessors on it. Every method takes a context.Context first.

| Accessor | Methods | What it reaches | | --- | --- | --- | | Vault() | Read, ReadBytes, ReadRange, Write, List, Stat, Move, Copy, Delete, Search, Grep | Vault files: Markdown, JSON, PDFs, images | | Ingestion() | Commit | Governed ingestion: the organization's size rule and security gate run before the write | | LLM() | Call, Models | Model discovery and calls through the LLM Registry; the Handler is the default | | LLMRegistry() | Register, Unregister | Adds or removes registry entries, for extensions that provision models | | MCP() | Tool | MCP tool calls, such as search_vault and Data Pipe queries | | Integrations() | List, Get, PayloadSchema, AllPayloadSchemas, Subscribe | The integration catalog and webhook subscriptions | | OAuth() | ResolveBearer | The organization's stored OAuth connections | | OperatorEnv() | Get, List, Put | Vendor credentials the operator configured | | Policy() | Check | The Security Policy Engine | | Control() | RoleOf | Role lookup in the Control Plane | | Audit() | Append | The tamper-evident audit chain | | Notifier() | Dispatch | Email and console notifications |

Every non-2xx response comes back as a *platformsdk.APIError carrying Method, Path, StatusCode and Body. See Error handling.

What the SDK is not

  • Not a database driver. There are no workspaces, records or graph objects to create. Knowledge is vault files with YAML frontmatter, written through Vault().Write or Ingestion().Commit and found with search.
  • Not a model host. The Handler, bRRAIn's own fine-tuned model, runs on the pod and is the default model. Commercial models are available only when the organization opts in through the LLM Registry.
  • Not multi-language. There is no official Node.js or Python package. See Other languages.
  • Not an anonymous download. The repository is private; access comes with a developer seat.

Where to go next

  1. Installation: get access and set up your Go module.
  2. Quickstart: write, read and list a vault file, and test it without a pod.
  3. Configuration and authentication: client options, the token and namespace isolation.
  4. Vault and ingestion, Search, Models, Governance, Vault paths and POPE tags.
  5. Error handling and Examples.

For a structured path with labs and an exam, take the bRRAIn Certified SDK Developer course. Every code sample in it compiles against SDK v1.2.0.