English · 中文
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.
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.
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 |
One Runtime. Composable Workspaces. Collaborative Agents. Federated Capabilities. Independent Trust Boundaries.
BSH has two complementary roles.
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.
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.
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.
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.
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.
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.
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.
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.
BOS separates the shared execution foundation, local composition and cross-node collaboration.
Within one BSH node, the platform is organized around distinct responsibilities:
| 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 |
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.
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 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.
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.
- 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 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.
Choose the interface that fits your application.
pip install nbosfrom 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
npm install @open1s/jsbosimport { 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
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
git clone https://github.com/open1s/bos
cd bos
cargo build --release -p bsh
./target/release/bshBSH 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.
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.AppImageThe 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 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.
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 |
|---|---|
![]() |
![]() |
| Extension manager | Model and settings |
|---|---|
![]() |
![]() |
Replacement instructions: BSH screenshot guide.
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 doctorStart 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.
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.
| 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 |
cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all
RUSTDOCFLAGS="-D warnings" cargo doc --no-depsPython and JavaScript binding tests:
cd crates/nbos && maturin develop && pytest -m "not llm"
cd crates/jsbos && npm install && npx avaIf 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.
MIT OR Apache-2.0 · Releases




