BKN Foundry: the Go ontology back end behind OpenBKN, installed with deploy.sh

What BKN Foundry solves, and who it is aimed at

The README frames OpenBKN as an ontology-driven business knowledge network: documents, systems, processes, rules and expert experience get modeled as an ontology, and that model is meant to give agents a business context they can execute against rather than merely read. BKN Foundry is the piece underneath that model. It is described as the technical foundation of OpenBKN, providing the knowledge network with unified data access, safe execution and governance.

The stated audience is teams connecting proprietary data to agents. The README names two pain points in that work, context engineering and safe execution, and positions Foundry as the answer to both. That framing matters because it rules out a large class of users. This is not a library you import into an application and call from a request handler. It is a set of services that run on a cluster, and the repository states plainly that it is a backend-only framework with no web UI. All interaction is through the CLI, the SDK or the API.

So the realistic adopter is a platform or data engineering group that already runs Kubernetes, has ontology content to publish, and wants agents to query and act on that content under some authorization scheme. A single developer experimenting on a laptop is a secondary case: the deployment guide says Linux is the supported target for full installs and treats macOS local development on kind as optional.

How the pieces fit: services, contracts and the API surface

The repository root shows the shape of the system. Alongside deploy/, docs/, help/ and migrations/ there are directories named adp/, bkn-safe/, bkn-trace/, comm-go/ and data-migrator/, plus tools/. The project description lists what the runtime is expected to cover: data, logic, actions, security governance and observability. The presence of a dedicated trace component and a dedicated safe component matches that split rather than contradicting it.

The API documentation pipeline is the most legible part of the architecture. The Makefile treats OpenAPI YAML under docs/api as the single source of truth, renders interactive HTML with redocly and Markdown with widdershins, and writes both into docs/api/_generated/, which is deliberately kept out of git. The published modules are listed by hand: bkn, context-loader, ontology-query, vega, execution-factory, mf-model-manager, agent-observability and bkn-agent. Two directories, bkn-safe and observability, are marked unpublished. The comment next to bkn-safe explains why: self-service reads and cluster-internal authorization and managed-proxy contracts are not published as general integration APIs. The observability directory simply has no publishable YAML, so rendering it would produce an empty group.

Two details in that Makefile are worth noticing because they show the maintainers thinking about drift. Unpublished modules are still linted, so service-to-service request and error schemas cannot change silently. And a reconciliation rule aborts the build if a module directory exists under docs/api without being registered in either list, which prevents documentation that exists in the repository but never reaches the site. Neither mechanism tells you whether the running services match the YAML; the Makefile keeps a separate contract inspection target for that, pointed at a development VM by default.

Installing BKN Foundry: preflight.sh, deploy.sh and onboard.sh

The quick start is a three-script sequence that runs on the target host. Clone the repository, enter deploy/, and make the scripts executable. The README recommends running the preflight check before the install; it verifies kernel and sysctl settings, containerd, kubectl, helm, Node and the BKN CLIs, and can repair what is missing. Each fix is opt-in unless you pass -y.

git clone https://github.com/openbkn-ai/bkn-foundry.git
cd bkn-foundry/deploy
chmod +x preflight.sh deploy.sh onboard.sh

sudo bash ./preflight.sh                # check-only (default)
sudo bash ./preflight.sh --fix          # check + interactive fixes
sudo bash ./preflight.sh --fix -y       # auto-approve every fix

Exit codes are documented: 0 means OK, 1 means any FAIL, 2 means only warnings. Use --report=/tmp/preflight.txt to keep a full log. If preflight reports failures you cannot resolve, stop here; the install assumes the host is ready.

Next, install the stack. Running deploy.sh without arguments prompts for the addresses; the explicit form skips the prompts. --access_address is the address clients use to reach OpenBKN services and may be an IP or a domain, while --api_server_address must be a real network interface IP because it is bound to the Kubernetes API server.

./deploy.sh openbkn install

./deploy.sh openbkn install \
  --access_address=<your-ip> \
  --api_server_address=<your-ip>

After it finishes, check the cluster and the service status. kubectl get nodes and kubectl get pods -A show the cluster state, and ./deploy.sh openbkn status reports on the deployment.

kubectl get nodes
kubectl get pods -A
./deploy.sh openbkn status

Then run the post-install bootstrap on the same host, since it needs kubectl to reach the cluster. onboard.sh registers an LLM and an embedding, patches the BKN ConfigMaps when the default embedding actually changes, and on a full install creates a business user named test, assigns every role returned by openbkn admin role list, and switches openbkn to that user. Re-runs are safe: existing models and BKN defaults are detected and skipped.

cd deploy
sudo bash ./onboard.sh
sudo bash ./onboard.sh --help

The README explains the sudo requirement: onboard.sh reads $HOME/.openbkn-ai/config.yaml, which sudo deploy.sh wrote into /root/.openbkn-ai/, and writes the openbkn auth token to $HOME/.bkn. Without sudo it falls back to the in-repo template deploy/conf/config.yaml and may resolve a different access URL. The macOS development path, bash deploy/dev/mac.sh onboard, does not need sudo.

Finally, reach the API from the machine you actually work on. The CLI lives in the separate bkn-sdk repository. Sign in as the user onboard.sh created, with the default password 111111 unless you overrode it, then list knowledge networks. The -k flag is used in the README's example login, which matters if your access address uses a self-signed certificate.

npm install -g @openbkn/bkn-sdk
openbkn auth login https://<node-ip> -u test -p '<password>' -k
openbkn bkn list

If you would rather not install globally, the README gives npx openbkn as the alternative. Either way, openbkn --help lists the commands and openbkn <command> --help documents a single one.

Where BKN Foundry is the wrong tool

The clearest limitation is stated by the project itself: there is no web UI. If your ontology authors and business users expect a browser to model, browse and edit knowledge networks, BKN Foundry does not provide one, and the README does not point to a separate console repository. Everything runs through the CLI, the SDK or the API, which means someone on your team has to be comfortable with a terminal and with HTTP clients.

The second constraint is the install path. The documented full install targets Linux and Kubernetes, and the deployment guide is the prerequisite document. There is no documented single-binary or Docker Compose route in the README; the macOS path is explicitly labeled as local development on kind and described as optional. A small team that wants to evaluate the ontology model without standing up a cluster has no short path here.

The third is maturity. The release list shows v0.1.1-alpha in June 2026, then v0.1.3 and v0.1.4 in August 2026. The version numbers and the alpha tag are the honest signal: this is early software, and the documentation set is still being filled in. The README links to help/en/install.md for the longer post-install sequence, which suggests the quick start is not the whole story. Nothing in the repository describes an upgrade procedure or a rollback path, so plan for that gap before you put it in front of users.

One more boundary is worth stating because it is easy to miss: bkn-safe is deliberately excluded from the published API site. Its self-service read endpoints and cluster-internal authorization and managed-proxy contracts are not offered as general integration APIs. If your integration plan depends on calling those endpoints directly, the published documentation will not cover you.

Alternatives: a general agent framework versus an ontology backend

The natural comparison is with agent frameworks such as LangChain or LlamaIndex. They solve a different half of the problem. Those projects give you orchestration in a process you control: you write Python or TypeScript, define tools, and wire retrieval into a prompt. BKN Foundry does not orchestrate agents at all. It exposes data access, action execution, authorization and tracing as cluster services with OpenAPI contracts, and expects some other client, including the bkn-agent module listed among its own published APIs, to consume them.

The practical difference shows up in what you maintain. With a framework, the semantic layer is your code and your prompts, and governance is whatever you build around it. With BKN Foundry, the semantic layer is an ontology published to the platform, and the governance surface is part of the deployment: the onboard script assigns roles, and the admin subcommands manage users, organizations, roles, models and audit logs. That is more machinery to run, and in exchange the rules live in one place rather than in each agent.

If you only need a retrieval pipeline over a handful of documents, the framework is the smaller commitment and you should take it. BKN Foundry starts to make sense when several agents, or several teams, need to query the same business model under the same authorization rules and produce the same audit trail.

Maintenance, upgrades and the multi-licence split

The repository is not archived, and the last push was on 2026-09-17, three days before this writing, which is consistent with a project under current work. The release cadence visible in the release list is roughly two months between v0.1.1-alpha in June and v0.1.4 at the end of August, with v0.1.3 landing on 2026-08-10. Release notes live in the release-notes/ directory, and the README links to them, so the changelog is the place to check what an upgrade actually changes.

The upgrade cost itself is not documented. There is no described procedure for moving an existing cluster from one version to the next, and no rollback instructions. The migrations/ directory at the repository root implies that schema changes are part of the story, but the README does not explain how they are applied or whether deploy.sh handles them. Treat that as an open question to resolve with the maintainers rather than an assumption.

The licence situation needs care. The README's badge points at a multi-licensed project, and the repository root contains three files: LICENSE, LICENSE-APACHE.txt and LICENSE-OPENBKN.txt. The presence of a project-specific licence alongside Apache means the terms are not uniform across the codebase. Which parts fall under which file is not something the README states, so read the files themselves before you plan a redistribution or a fork. This is a factual observation about the repository layout, not legal advice; if the split affects your product, take it to someone qualified.

Editorial conclusion

Adopt BKN Foundry if you run Linux and Kubernetes, need ontology-driven data, action and authorization services behind an agent, and are willing to drive everything through the CLI or the OpenAPI endpoints. Do not adopt it if you want a browser console, a single-binary install, or a project with a long release history; v0.1.4 shipped on 2026-08-31. Verify three things first: that your target host passes preflight.sh, that the multi-license split in LICENSE-APACHE.txt and LICENSE-OPENBKN.txt matches how you plan to redistribute the stack, and that the services you need are among the eight modules the API site actually publishes.

Frequently asked questions

Official sources

1. Issues
2. openbkn-ai/bkn-foundry on GitHub
3. README
4. Releases