Skip to content
open1sPublic

About

BOS — A Rust-native AI Agent Platform. One Runtime, Multiple Interfaces, One Extensible Agent Workspace. Build with Rust, Python, and JavaScript; develop and operate agents in BSH, the native GPUI workspace.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

English · 中文

BOS — Rust-Native Agent Runtime and Distributed Platform

BOS — Brain Operating System

Distributed Composable Agent & Capability Platform

Compose agents, tools, runtimes and resources into purpose-built workspaces.
Connect independent BSH nodes to collaborate across machines and trust boundaries.

Conceptual BSH product visual: a task-specific workspace composes scoped capabilities and collaborates with independently governed remote nodes. Not an application screenshot.

Python SDK JavaScript SDK Rust CI Binding parity License

What is BOS? · BSH platform · Architecture · Quick start · Documentation


Release 4.1.1 — tool and skill discovery in the prompt, a workspace ignore file every file tool honours, and rendered file previews. See the changelog for the full set.

What is BOS?

BOS is a Rust-native foundation for building, composing and operating AI agents as a distributed system.

At its center is BSH: not merely a desktop agent workspace, but the product direction for a Distributed Composable Agent & Capability Platform. A BSH node is being evolved into an AI-native capability container that assembles agents, tools, extensions, models, context and resources into purpose-built workspaces. Multiple independent BSH nodes can then be connected as a federation, allowing agents and capabilities to be discovered, delegated to and composed across machines—without collapsing their runtime or security boundaries.

BOS provides the shared execution foundation and developer interfaces. BSH turns that foundation into an environment for composing and operating local and distributed agent systems.

Layer Responsibility
BOS Runtime Rust-native agent execution, tool dispatch, model integration, messaging and runtime controls
BSH Node The desktop/runtime host for workspaces, agents, extensions and local resources; the full composable container is the BSH 2.0 target
Composition Engine Target subsystem: resolves, validates and activates task-specific capability sets independently of agent reasoning
Ferris Extension Framework Packages, loads and governs extensions across supported execution providers
Federation Target subsystem: connects independent nodes and exposes explicitly authorized remote capabilities and agent services
Rust / NBOS / JSBOS Native, Python and JavaScript interfaces to the shared BOS implementation

The platform in one sentence

One Runtime. Composable Workspaces. Collaborative Agents. Federated Capabilities. Independent Trust Boundaries.

BSH platform

BSH has two complementary roles.

BOS and BSH value proposition: Rust-native foundation, composable workspaces and federated autonomous nodes.

BSH is evolving the BOS foundation into a practical operating environment: compose capabilities for a task, run them in a governed workspace, extend the platform, and connect independent nodes when collaboration requires it.

1. A composable capability container

In the BSH 2.0 target model, a node assembles only the capabilities needed for a particular purpose. Each workspace receives a tailored capability view instead of exposing every installed tool to every agent.

A composition may include:

  • Agents — task-focused agents, specialist roles and delegated workers.
  • Tools and skills — built-in tools, user-defined tools, skills and MCP integrations.
  • Extensions — host contributions and isolated extension packages managed through Ferris.
  • Models and policies — model providers, routing choices, permissions and execution constraints.
  • Context and resources — project files, memory, services and other explicitly granted resources.
  • Workflows — reusable task compositions and coordinated agent activities.

Composition is a first-class platform concern, not a side effect of agent prompting. The Composition Engine is designed to remain independent of the ReAct/agent reasoning engine. AI can propose a composition; the runtime validates compatibility, dependencies, permissions and resource limits before activation.

How BSH composes agents, models, tools, extensions, context and resources into a validated task-specific workspace.

2. A distributed agent and capability platform

A BSH installation is an autonomous node. Multiple nodes can form a federation and collaborate while retaining their own identity, runtime, policies, secrets, files and audit records.

The intended federation model supports:

  • Node and capability discovery — discover peers and the capabilities they advertise.
  • Remote capability invocation — use a remote capability through a local, policy-aware interface.
  • Agent delegation — assign a bounded task to an agent on another node and receive its result.
  • Multi-agent collaboration — coordinate specialists across nodes when a task benefits from distributed expertise or resources.
  • Resource-aware collaboration — request access to selected services or resources without copying an entire node's environment.
  • Independent governance — authorize at both the requesting node and the provider node; either side can deny or revoke access.

Federation is not a shared super-process. A coordinator may help with rendezvous, discovery or scheduling, but it does not become the execution authority for peer nodes. Remote capabilities remain remote, and discovery never implies trust.

Federation connects autonomous BSH nodes through bounded requests and independent authorization at both ends.

Implementation status: BOS already provides the Rust runtime, agent/tool execution, messaging foundations, BSH desktop host, Ferris extension framework and MCP integration. The full BSH composition and federation model is the platform's architectural direction and is being developed in stages. Do not interpret the target federation capabilities above as a claim that every feature is already generally available.

What can you build with BSH?

BSH is designed around purpose-built workspaces, not one universal agent with every tool enabled. The following scenarios show how the same BOS foundation can be composed for different jobs. They are illustrative composition blueprints, not claims that these exact presets ship out of the box.

Research Workspace

Research workspace blueprint combining a research agent, project sources, document tools, analysis capabilities and evidence-led outputs.

Bring a research brief, project documents and selected source integrations together with an agent and analysis tools. The workspace can be configured to collect evidence, extract information, compare findings and produce a structured report. Source search and specialist analysis integrations are supplied by the tools and extensions configured for that workspace.

Software Engineering Workspace

Software engineering workspace blueprint combining repository context, an engineering agent, file tools, terminal, browser and extensions.

Give a coding agent the repository context and a focused toolset: file discovery and batch reads, structured edits, terminal operations, browser access and relevant extensions. BSH's desktop already provides the operator surfaces — editor, diffs, terminal and browser — while dedicated tools and execution policies govern what the agent can do. A developer remains responsible for reviewing changes and test results.

Distributed Multi-Agent Workspace

Target distributed multi-agent scenario with a requester node delegating bounded tasks to autonomous research and engineering provider nodes.

A coordinating workspace can delegate bounded research or engineering tasks to specialist agents hosted by other BSH nodes, then combine their results. Each node keeps its own runtime, secrets, policies and audit trail; remote work requires explicit authorization at both ends.

**Roadmap status:** the distributed scenario illustrates the BSH Federation target architecture. Node enrollment, discovery, remote capability invocation and cross-node delegation are being developed in stages; this is not a claim that the complete workflow is currently available.

Architecture

BOS separates the shared execution foundation, local composition and cross-node collaboration.

BSH distributed platform: autonomous nodes contain composable workspaces and collaborate through federation while retaining independent trust boundaries.

Local node architecture

Within one BSH node, the platform is organized around distinct responsibilities:

Internal architecture of one composable BSH node, from composition and workspace runtime to scoped capabilities and providers.

Subsystem Responsibility
Agent Runtime Runs agents and reasoning loops, manages sessions and coordinates tool calls
Capability System Describes available operations and mediates access to providers
Composition Engine Target: resolves a task-specific composition and produces a workspace capability view
Workspace Runtime Target: activates and governs a composition with its context, resources and lifecycle
Ferris Manages extension packages, providers, lifecycle and execution boundaries
Policy and Audit Applies current authorization and execution controls; the unified composition-wide policy/audit model is a target
Bus and Adapters Provides messaging and integration seams for local and external systems

Agent Intelligence Runtime

BSH treats Skill Intelligence and Tool Intelligence as sibling subsystems under the Agent Runtime. They solve different problems and should coordinate through shared task intent and governance rather than being collapsed into one catalogue:

  • Skill Intelligence — what expertise and procedures should guide the task? It discovers and ranks Skills, resolves dependencies, validates provenance and trust, loads selected instructions on demand, activates them within the task/session scope, and composes their instructions into bounded model context.
  • Tool Intelligence — what operations can safely advance the task? It discovers and ranks tools/capabilities, filters candidates against the current workspace view, plans capability use, exposes only the necessary schemas, invokes through the authorized runtime, and evaluates results.
  • Shared task intent — why and under what constraints? Intent, conversation context, workspace, constraints and context budget guide both subsystems. Either subsystem must be able to decide that no Skill or no Tool is needed.
  • Unified Capability & Security Runtime — what is actually allowed to happen? Composition, authorization, provider resolution, lifecycle, cancellation and audit remain authoritative runtime responsibilities. Discovery relevance or Skill activation never grants execution permission.
  • Execution Layer — where does the operation run? Local tools, MCP adapters, Ferris providers, WASM components and remote BSH nodes execute behind explicit provider and trust boundaries.

BSH Agent Intelligence Runtime: shared task intent coordinates sibling Skill Intelligence and Tool Intelligence subsystems, which use a unified capability and security runtime before execution.

The intended lifecycle is Task Intent → Discover → Plan → Validate → Load / Expose → Activate / Invoke → Observe → Evaluate → Cleanup. Skill instructions and tool schemas are loaded progressively and only when needed; the full Skill and Tool catalogues should not be injected into every model request. Task-scoped state, context budgets and provenance must remain isolated across concurrent tasks and delegated agents.

Implementation status: BOS already has the find_skill / load_skill and find_tool discovery primitives, deferred tool-schema exposure, and important capability-runtime foundations. The diagram describes the target integrated architecture; end-to-end orchestration, workspace-authoritative tool discovery, bounded cumulative schema composition and unified effectiveness evaluation are still being evolved. Track the requirements in Skill Intelligence issues #273–#283 and Tool Intelligence issues #284–#287.

Federation architecture

Federation connects nodes; it does not merge them.

Plane Responsibility
Identity and Trust Node identity, enrollment, trust establishment, revocation and peer authentication
Discovery and Control Peer discovery, capability advertisements, policy metadata and coordination
Delegation and Collaboration Bounded task delegation, remote agent interaction, leases and task state
Data and Execution Authorized remote invocation and minimal exchange of task inputs and results

The federation protocol is transport-agnostic. Transports such as Zenoh may be used as implementation substrates, but transport connectivity alone does not establish identity, authorization or trust.

BSH extension and agent model

BSH extension framework and agent execution model, showing host services, extension runtimes, agent engine, context, tools, runtime environment and governance.

The extension framework is a host-integrated subsystem. It supplies capabilities to BSH through explicit contracts; it is not a second agent runtime. MCP is an integration protocol and adapter, not the canonical capability model of the platform.

Why BOS?

  • Rust-native execution. A shared implementation underpins native applications and language bindings.
  • Composable by design. Assemble task-specific workspaces from agents, tools, extensions, models, context and resources.
  • Agent-oriented runtime. ReAct execution coordinates model responses, tool calls, observations and lifecycle hooks.
  • LLM-aware tools. Tool contracts, schemas and bounded outputs help models select and use capabilities effectively.
  • Extensible execution. Ferris supports multiple extension providers, including declarative, process, WebAssembly Component, Extism, MCP and built-in integrations.
  • Distributed communication foundation. The bus provides publish/subscribe, query/response and RPC patterns for system components.
  • Policy at execution boundaries. Capability authorization, sandboxing, limits and audit controls are treated as runtime responsibilities.
  • Language interoperability. Rust, Python and JavaScript interfaces use the same underlying implementation.

BOS developer foundation

BOS keeps the core implementation in Rust and exposes it through native Rust, Python and JavaScript interfaces. BSH is the operator workspace built on the same foundation.

BOS shared Rust-native foundation powering Rust, Python and JavaScript integrations and the BSH application.

Quick start

Choose the interface that fits your application.

Python

pip install nbos
from nbos import BrainOS, tool

@tool("Add two numbers")
def add(a: int, b: int) -> int:
    return a + b

async with BrainOS() as brain:
    agent = brain.agent("assistant").register(add)
    print(await agent.ask("What is 2 + 2?"))

Guide: Python user guide

JavaScript / Node.js

npm install @open1s/jsbos
import { BrainOS, ToolDef } from "@open1s/jsbos";

const add = new ToolDef(
  "add",
  "Add two numbers",
  (args) => args.a + args.b,
  { type: "object", properties: { a: { type: "number" }, b: { type: "number" } }, required: ["a", "b"] },
);

const brain = new BrainOS();
await brain.start();
const agent = await brain.agent("assistant").register(add).start();
console.log(await agent.runSimple("What is 2 + 2?"));
await brain.stop();

Guide: JavaScript user guide

Rust

Use the runtime crates directly from the workspace:

use agent::{Agent, AgentConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = AgentConfig::default()
        .name("assistant")
        .model("gpt-4o")
        .base_url("https://api.openai.com/v1")
        .api_key(std::env::var("OPENAI_API_KEY")?);

    let agent = Agent::from_config(config);
    println!("{}", agent.run_simple("Hello").await?);
    Ok(())
}

Guide: Rust user guide

Run BSH

git clone https://github.com/open1s/bos
cd bos
cargo build --release -p bsh
./target/release/bsh

BSH requires Rust 1.97+ and Zig 0.16 to build its Ghostty terminal integration. On macOS, a development app can also be packaged with ./crates/bsh/make-dev-app.sh. See the Rust workflow for Linux build dependencies.

Install BSH

Prebuilt installers are published on the releases page. Available formats and platform coverage are listed with each release. Each release carries SHA256SUMS.

Linux ships one AppImage per architecture:

chmod +x bsh-<version>-linux-x86_64.AppImage
./bsh-<version>-linux-x86_64.AppImage

The image carries bsh and the libraries your distribution is not guaranteed to have. It needs glibc 2.35 or newer and WebKitGTK 4.1, and names the package to install when that is missing. On a host without FUSE 2, run it with --appimage-extract-and-run; --integrate adds a menu entry and --uninstall removes it.

The tag-driven build, signing and notarization setup is documented in docs/bsh-release.md.

BSH desktop environment

BSH provides a native GPUI environment for developing, using and operating agents. It is also the operator interface for local and, as federation capabilities mature, distributed workspaces.

  • Workspaces and sessions — organize projects and persistent conversations.
  • Agent-first interaction — streaming responses, task plans, queued messages and visible subagent activity.
  • Integrated terminal — Ghostty terminal surface with command-policy checks.
  • Browser pane — embedded WebView for browsing alongside an agent.
  • Code editor — file tree, tabs, diffs and tree-sitter language grammars.
  • Settings and credentials — provider configuration and an encrypted vault.
  • Bilingual interface — English and Chinese.
  • Extensions — add tools, commands, panels, prompts, contexts, skills, themes, language services, agent roles, workflows, storage and hooks.
  • Review and audit — file changesets with structural diffs, findings and decisions, plus an audit timeline over the same tool calls.
  • Run trajectory — a run navigator, step timeline, progress and a per-step inspector for every turn.

BSH interface preview

Screenshot placeholders — not real application captures. Replace these assets with screenshots from a running BSH build before using them as product evidence.

Main workspace Agent session
BSH workspace placeholder BSH agent session placeholder
Extension manager Model and settings
BSH extension manager placeholder BSH settings placeholder

Replacement instructions: BSH screenshot guide.

Ferris Extension Framework

Ferris is the extension framework used by BSH. It separates extension package and lifecycle management from the host's agent reasoning engine. BSH adapts extension-provided functionality into host capabilities through explicit contracts and permission checks.

Provider Intended use
Declarative JSON-defined tools, panels, prompts and themes
Process Existing programs and services communicating through JSON-RPC
WASM Component Portable components using the WebAssembly Component Model and WIT
Extism Existing Extism plugins
MCP Reuse an MCP server through an adapter
Built-in First-party Rust functionality linked into the host

Create and validate a package:

bsh ext new com.acme.hello --dir hello
bsh ext validate hello
bsh ext mock hello echo '{"text":"hi"}'
bsh ext install hello
bsh ext list
bsh ext doctor

Start here:

Security note: extension capability authorization and operating-system isolation are separate controls. Enforcement differs by operating system and runtime. Consult the BSH extension platform and security policy for the current contract and limitations.

Model configuration

BOS supports OpenAI-compatible endpoints, Anthropic, NVIDIA NIM, Google AI and OpenRouter. Configure a default model in ~/.bos/conf/config.toml:

[global_model]
api_key = "your-api-key"
base_url = "https://api.openai.com/v1"
model = "gpt-4"

[llm.nvidia]
api_key = "nv-..."
base_url = "https://integrate.api.nvidia.com/v1"
model = "nvidia/your-model"

If the call and configuration file do not provide a key, the bindings read OPENAI_API_KEY. BSH manages providers in Settings → Models and stores sensitive credentials in its encrypted vault.

Documentation

Resource Description
BOS / BSH textbook In-depth guide to the runtime, desktop host and extension framework
Architecture Current component responsibilities and architecture
BSH 2.0 workspace acceptance Code-backed implementation gap, golden-path demo and end-to-end security acceptance
Rust user guide Embed and use BOS from Rust
Python user guide Use BOS from Python
JavaScript user guide Use BOS from Node.js and JavaScript
BSH extension platform Manifest, providers, lifecycle, capabilities, CLI and security
BSH Built-in Tools 2.0 LLM-oriented tool contracts, batch file operations, output budgets and benchmark plan
Contributor onboarding Set up a development environment
Settings · Terminal policy · Hooks Subsystem specifications
BSH release pipeline Installer artifacts, signing and release workflow
REX guide · Diagnostics Resource tooling and troubleshooting
Wiki · Changelog Guides and release history

Build, test and contribute

cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

Python and JavaScript binding tests:

cd crates/nbos  && maturin develop && pytest -m "not llm"
cd crates/jsbos && npm install && npx ava

If BOS is useful to you, consider starring the repository and sharing what you build with it. Feedback and real-world examples help guide the platform.

License

MIT OR Apache-2.0 · Releases

About

BOS — A Rust-native AI Agent Platform. One Runtime, Multiple Interfaces, One Extensible Agent Workspace. Build with Rust, Python, and JavaScript; develop and operate agents in BSH, the native GPUI workspace.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages