Prerequisites

A bRRAIn developer seat. Every organization has five free seats; ask your administrator for one.
Go 1.25.9 or later (go version to check)
A code editor (VS Code, GoLand)

How your code runs

A Platform SDK program runs as an extension on your organization's bRRAIn pod. The pod starts it and hands it everything it needs to connect: there is no API key to generate and nothing extra to deploy beside your code. Until then, you can build and test everything locally.

1

Get Access

The SDK lives in a private repository, and access comes with your developer seat. Once your administrator has assigned you a seat, clone the repository next to your project:

git clone git@github.com:Qosil/bRRAIn.git ../bRRAIn

Need more seats, or building for a customer as a partner? Talk to us.

2

Set Up Your Module

mkdir hello-notes && cd hello-notes
go mod init example.com/hello-notes

Point your module at the SDK in go.mod:

module example.com/hello-notes

go 1.25.9

require github.com/Qosil/bRRAIn/pkg/platform-sdk v0.0.0-00010101000000-000000000000

replace github.com/Qosil/bRRAIn/pkg/platform-sdk => ../bRRAIn/pkg/platform-sdk

Keep the replace path relative so the same module builds on every machine, including CI.

3

Verify the Build

Create cmd/sdkversion/main.go:

package main

import (
	"fmt"

	platformsdk "github.com/Qosil/bRRAIn/pkg/platform-sdk"
)

func main() {
	fmt.Println("platform sdk", platformsdk.SDKVersion)
	fmt.Println("sub-clients:", platformsdk.OfferedSubClients())
}

go mod tidy
go run ./cmd/sdkversion

Expected output: platform sdk 1.2.0, followed by the platform services the SDK offers.

4

Connect to the Platform

Create cmd/hello-notes/main.go. The pod supplies the connection settings when it starts your extension; the program stops with a clear message if they are missing.

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"strings"
	"time"

	platformsdk "github.com/Qosil/bRRAIn/pkg/platform-sdk"
)

const slug = "hello-notes"

func mustEnv(name string) string {
	v := strings.TrimSpace(os.Getenv(name))
	if v == "" {
		log.Fatalf("%s: %s is required (the supervisor sets it)", slug, name)
	}
	return v
}

func main() {
	c, err := platformsdk.New(platformsdk.Options{
		BaseURL: mustEnv("BRRAIN_INTERNAL_URL"),
		Token:   mustEnv("BRRAIN_INTERNAL_TOKEN"),
		// AppSlug is left empty: New reads BRRAIN_APP_SLUG, which the
		// supervisor sets to your manifest's slug.
	})
	if err != nil {
		log.Fatalf("%s: build SDK client: %v", slug, err)
	}

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	if err := run(ctx, c, time.Now().UTC()); err != nil {
		log.Fatalf("%s: %v", slug, err)
	}
}

5

Write, Read and List

Add the run function to the same file. It writes a note into your extension's private area of the vault, reads it back and lists the folder.

// run writes a note into the extension's own namespace, reads it back,
// and lists the folder it lives in.
func run(ctx context.Context, c *platformsdk.Client, now time.Time) error {
	dir := "extensions/" + slug + "/notes"
	path := dir + "/" + now.Format("2006-01-02") + "-hello.md"
	note := fmt.Sprintf(`---
title: "Hello from %s"
date: %s
author: "[AI] %s"
tags: []
---

First note written through Platform SDK %s.
`, slug, now.Format("2006-01-02"), slug, platformsdk.SDKVersion)

	if err := c.Vault().Write(ctx, platformsdk.VaultWriteRequest{
		Path:    path,
		Content: []byte(note),
	}); err != nil {
		return fmt.Errorf("write %s: %w", path, err)
	}

	body, err := c.Vault().ReadBytes(ctx, path)
	if err != nil {
		return fmt.Errorf("read %s: %w", path, err)
	}
	fmt.Printf("read back %d bytes from %s\n", len(body), path)

	entries, err := c.Vault().List(ctx, dir)
	if err != nil {
		return fmt.Errorf("list %s: %w", dir, err)
	}
	for _, e := range entries {
		fmt.Printf("  %s (%d bytes)\n", e.Name, e.Size)
	}
	return nil
}

Every file carries a title, a date, an honest author and a tags property, so people can find and trust it later.

6

Test It Without a Pod

The SDK talks plain HTTP, so a small fake platform built with Go's httptest package lets you run the real client on your own machine. Copy the test file from the SDK Quickstart docs into cmd/hello-notes/main_test.go, then run:

go test ./cmd/hello-notes -v

Expected output: both tests pass, including one that shows what a wrong token looks like.

7

Run It on Your Pod

Package the program as an extension with a short manifest that names it and lists the platform services it uses, then install it on a development pod. The pod starts it with the right connection settings, and everything it does is governed by your organization's policies.

The server guide shows a complete extension with its manifest, and the certification course walks through packaging, install and update.

What's next?

Troubleshooting

Go tries to download the SDK and fails: The replace line in go.mod is missing or points at the wrong folder. Paths are case-sensitive: the checkout is bRRAIn.
Permission denied when cloning: You do not have repository access yet. Ask your administrator for a developer seat.
BaseURL is required: The program is running outside the pod without its connection settings. Use the local test in step 6, or install it on a pod.
401 from the platform: The connection token is missing or wrong. On a pod the platform provides it; never hard-code it.
403 on a vault path: The path belongs to another extension or to the platform. Keep your files under extensions/<your-slug>/.

Your First Platform SDK Program