SDK Installation — bRRAIn Docs

Get access to the bRRAIn Platform SDK through a developer seat, set up a Go module against it, and prove the build works.

Installation

The Platform SDK is a Go module in a private repository. Installing it means getting access, checking out the repository, and pointing your module at it with a replace directive.

Requirements

  • A developer seat. Every bRRAIn organization has five free SDK developer seats, counted separately from platform users. Repository access comes with the seat.
  • Go 1.25.9 or later. The SDK's own go.mod declares go 1.25.9.
  • Git access to the bRRAIn repository with the credentials tied to your seat.

1. Request access

Ask your organization's administrator for one of its developer seats. If you are a partner building for a customer, the seat comes from the organization you are building for or from your own organization's allocation. If your organization needs more seats, contact bRRAIn.

Use one seat per person. A shared credential loses attribution and stops working for everyone when its owner leaves.

Because the repository is private, go get through the public module proxy cannot fetch the SDK. Any guide that tells you to go get the SDK anonymously is wrong.

2. Check your toolchain

go version   # go1.25.9 or later

3. Check out the repository and create your module

git clone git@github.com:Qosil/bRRAIn.git ../bRRAIn
mkdir hello-notes && cd hello-notes
go mod init example.com/hello-notes

Edit go.mod so it requires the SDK and replaces it with your checkout:

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

The repository does not publish a tag for the pkg/platform-sdk module, so the version in the require line is a placeholder that the replace directive satisfies. First-party extensions consume the SDK the same way.

Use a relative replace path. An absolute path works on one machine and breaks on every other one, including CI.

4. Prove it builds

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())
}

The import path ends in platform-sdk but the package is named platformsdk; the explicit alias makes that obvious.

go mod tidy
go run ./cmd/sdkversion
go vet ./...
go list -m github.com/Qosil/bRRAIn/pkg/platform-sdk

Expected output, abbreviated:

platform sdk 1.2.0
sub-clients: [operatorenv oauth integrations.registry ... control.role ingestion.commit]
github.com/Qosil/bRRAIn/pkg/platform-sdk v0.0.0-00010101000000-000000000000 => ../bRRAIn/pkg/platform-sdk

The => confirms the replace directive is in effect. The sub-client list is the set the supervisor checks your manifest against when it starts your extension.

5. Record what you built against

With no tag, you answer "which SDK did we build with?" yourself:

  • Record the repository commit of your checkout in the release notes of every build you ship.
  • Record platformsdk.SDKVersion at that commit. It is the value you declare as platform_sdk.min_version in your manifest.
  • Update the checkout deliberately: read what changed under pkg/platform-sdk, rebuild and rerun your tests.

6. Make CI match your laptop

Your CI job must check out the bRRAIn repository at the path the replace directive expects (a sibling directory named bRRAIn in the example), using a credential tied to a developer seat and kept in the CI system's secret store. Then run go build ./..., go vet ./... and go test ./.... Never put a token in the repository, in go.mod, or in a script that prints it.

Troubleshooting

| Symptom | Cause | Fix | | --- | --- | --- | | go tries to download the module: proxy.golang.org ... 404 Not Found or invalid version: git ls-remote ... | Go tried to download the module: the replace line is missing or misspelled | Add or correct the replace line, run go mod tidy, check for => in go list -m | | replacement directory ../brrain/pkg/platform-sdk does not exist | Wrong path or case; paths are case-sensitive on Linux | The checkout directory is bRRAIn | | go.mod requires go >= 1.25.9 | Toolchain too old | Upgrade Go | | Permission denied (publickey) on clone | No repository access yet | Request a developer seat |

Next