basis
An embeddable AI agent harness for Rust applications, multi-protocol serving, and developer workflows.
Basis bridges the gap between raw LLM agent runtimes and production applications. Built on Mentra, Basis packages the generic harness glueβworkspace discovery, context conventions, multi-protocol serving, durable execution, and safety boundariesβwithout imposing opinionated presentation, custom TUIs, or fixed domain pipelines.
Rent the loop, own the glue. The core has no opinions: task-specific behavior enters via prompts, templates, and workspace conventions, never via harness code.
Highlights
- π§© Embeddable Rust SDK β Library-first design (
basis) with no transport, protocol, or terminal dependencies in the core. Open aWorkspace, mint runs, stream typed events, and set execution bounds. - π Standard Protocol Serving β Native support for the Agent Client Protocol (ACP) over stdio and WebSockets (for Zed, JetBrains, and Web UIs) and the Agent-to-Agent (A2A v1.0) protocol for multi-agent delegation.
- π Durable Filesystem-Coordinated Tasks β Headless, asynchronous execution with persistent task handles, inboxes, and message correlation. Advances only while a process is attached (
fs2file locks)βno background daemons or resident schedulers required. - π§ Workspace Conventions & Discovery β Automatically discovers
AGENTS.md(andCLAUDE.md), hierarchical skills, prompt templates (.basis/templates/), declared tools, and Model Context Protocol (.mcp.json) servers. - π‘οΈ Execution Bounds & Approvals β Precise constraints on wall-clock deadlines, tool invocation counts, and token budgets. Customizable approval policies (
always,never,prompt, or custom trait implementations). - β‘ Clean Layered Architecture β Six focused crates split by dependency weight, allowing applications to compile only what they actually use.
Crate Architecture
Basis is organized into six crates split by dependency weight (ADR-0011):
| Crate | Purpose | Key Responsibilities |
|---|---|---|
basis |
Core SDK | Workspace discovery, run lifecycle, event streaming, bounds, and execution seams. No network, transport, or terminal dependencies. |
basis-host |
Host Kit | Adapter-neutral policy, approval gates, session management, and runtime pools (ADR-0025). |
basis-tasks |
Durable Tasks | Filesystem-coordinated task lifecycle, locks (fs2), inboxes, journals, and crash recovery (ADR-0017, ADR-0019). |
basis-acp |
ACP Adapter | Serves the Agent Client Protocol over stdio or WebSocket bridge for editors and UIs. |
basis-a2a |
A2A Server | Serves workspaces to remote agents over HTTP/JSON and JSON-RPC with workflows and file exchange (ADR-0028, ADR-0050). |
basis-cli |
CLI Binary | Unified command-line interface (basis) publishing all features for interactive and automated use. |
Quick Start
1. Install the CLI
Requires Rust 1.95 or newer:
2. Configure a Provider
Set the API key for your preferred provider:
# or:
For local or custom OpenAI-compatible endpoints (such as Ollama, vLLM, or LM Studio):
# optional: export BASIS_API_KEY="your-key"
3. Run a Prompt
Navigate to any repository and run:
[!NOTE]
basis "<prompt>"is shorthand forbasis spawn "<prompt>". Answers are sent tostdoutand streaming progress goes tostderr.
CLI & Durable Tasks
The CLI provides both direct prompt execution and asynchronous task management.
Prompts & Conversations
# Shorthand prompt execution
# Target a different workspace directory
# Read prompt from stdin
|
# Continue the conversation last worked on in this workspace
# Continue a specific historical session
Durable Task Lifecycle
At a shell, basis spawn drives the agent to completion. With --resumable, it creates a persistent task and prints its handle immediately. An agent advances only while a process is attached to itβthere are no background daemons:
# Create a durable task without driving it
# Attach to drive or observe its terminal result
# Follow progress without driving
# Enqueue follow-up messages into the task inbox
# Cancel a running task and its attached descendants
Bounds & Exit Codes
Enforce resource bounds across runs:
| Exit Code | Meaning |
|---|---|
0 |
Operation finished successfully. |
1 |
Run failed or could not start. |
2 |
Invalid CLI invocation. |
3 |
A bound tripped (--deadline, --tool-budget, --token-budget); committed work is retained. |
See the CLI Guide for full argument details and output specifications.
Protocol Servers
Basis can serve any workspace over standard protocols:
# Serve ACP over stdio (for Zed, JetBrains, or editors launching the process)
# Serve ACP over a local WebSocket bridge (for browser-based UIs)
# Serve A2A (Agent-to-Agent v1.0) over HTTP/JSON and JSON-RPC
- ACP defaults to asking the client for permission approvals before consequential actions.
- A2A supports multi-agent collaboration, delegation (
@<agent> <prompt>), task push notifications, file exchanges, and fine-grained workflow constraints (ADR-0050).
Embed in Rust
Add basis to your application's Cargo.toml:
[]
= "0.25.1"
= { = "1", = ["macros", "rt-multi-thread"] }
Minimal Execution Example
use ;
async
Multi-Turn Conversations & Event Streaming
A PreparedRun maintains its session across turns:
use ;
// Execute follow-up turn
let second_turn = run
.send_with_options
.await?;
println!;
Feature Flags
mcp(default): Model Context Protocol support (.mcp.jsondiscovery and client connections). Disable viadefault-features = falsefor environments requiring no MCP footprint.a2a(default): Agent-to-Agent client support (.basis/a2a.jsondiscovery and remote delegation).
See the Embedding Guide and Runnable Examples for advanced patterns including custom approvers, event taps, and shared runtime pools.
Workspace Conventions
Basis loads configuration and context files directly from the workspace:
| Path | Purpose |
|---|---|
AGENTS.md / CLAUDE.md |
Workspace instructions and system prompt context, discovered hierarchically up the directory tree. |
.basis/config.json |
Workspace configuration (pins provider, model, and effort). |
.basis/skills/.agents/skills/ |
On-demand skill definitions (SKILL.md) discovered and layered across workspace and user roots. |
.basis/templates/ |
Reusable prompt templates, invokable via /name <args> or exposed as ACP commands. |
.basis/tools.json |
Subprocess declared tools executing local commands with JSON input/output schemas. |
.basis/a2a.json |
Remote agent registry for delegation targets (@<agent> <prompt>). |
.mcp.json |
MCP server definitions (stdio, SSE, Streamable HTTP). |
Precedence
Settings are resolved in strict order:
CLI Flags / Builder Options > Workspace Config (.basis/config.json) > Global Config (~/.config/basis/config.json) > Environment Variables.
Important Environment Variables
BASIS_BASE_URLβ Custom endpoint URL for OpenAI-compatible providers.BASIS_API_KEYβ API key for custom endpoint configurations.BASIS_CONFIG_DIRβ Overrides the global configuration directory.BASIS_DATA_DIRβ Overrides where durable tasks and conversation states are stored.
See the Configuration Reference for complete details.
Security & Isolation
[!WARNING] Basis is an agent harness, not an OS sandbox. Basis runs with the full OS permissions of the host process or user account. While file tools enforce workspace scoping and deny sensitive paths (such as
.git/hooksand.git/config), shell commands can bypass these checks. For untrusted code or tasks, always run Basis inside a container or VM boundary.
Approval Policies
Consequential tool calls (shell execution, file writes, delegation) are governed by approval modes:
always(CLI default) β Consequential calls are executed automatically without prompts.promptβ Prompts interactively at the terminal (tty) before executing consequential calls.neverβ Automatically denies all consequential tool calls (read-only execution).
Use --no-shell to disable command execution while still permitting file writes. Refer to the Isolation Guide for containerized and rootless deployment configurations.
Documentation
- π CLI Guide β Comprehensive command syntax, lifecycle verbs, and JSON output specs.
- π οΈ Embedding Guide β Complete Rust SDK integration guide and patterns.
- βοΈ Configuration Reference β Directory conventions, schemas, and precedence.
- ποΈ Architecture Overview β Structural design, invariants, and component boundaries.
- π Architecture Decision Records (ADRs) β Numbered ledger of all accepted design decisions.
- π‘ Proposal β The founding thesis, problems, and core architectural bets.
- π Containerization Guide β OS sandboxing and production isolation patterns.
- π Changelog β Release notes and upgrade guides.
Contributing
We welcome contributions! Please see CONTRIBUTING.md for development workflows and testing requirements. All participants are expected to adhere to the Code of Conduct.
For security disclosures, please consult SECURITY.md.
License
This project is licensed under the MIT License.