What is borg (Rust agent runtime)?
borg is a supervised agent runtime for Rust, published by Joydle on GitHub. Application code declares a pipeline of agents (one model call or one deterministic step each) and borg runs it under a supervisor: cancelling the root reaches every nested agent, in-flight LLM call and tool, a panicking child is reported as an error without unwinding into its siblings, retryable failures restart with backoff, a budget is checked before every dispatch, and long runs resume from a checkpoint after a crash. The project site at joydle.github.io/borg describes the layers, composition node types, lifecycle features and guarantees, and plays a scripted run in the browser without calling a model.
The workspace contains seven crates that share one version and one release tag: borg (compositions, supervisor, tools, checkpoints, streaming), borg-macros (agent and tool derives, re-exported by borg), borg-loop (long-lived, resumable actor sessions), borg-tracing (a tracing span hierarchy), borg-mcp (stdio MCP servers as tools), borg-sandbox (a subprocess tool behind a pluggable backend) and borg-tools (file-operation tools and an approval helper). It runs on Tokio and requires Rust 1.88 or later.
borg is distributed from GitHub only. Every crate is marked publish = false, and the README states that the borg name on crates.io belongs to an unrelated crate, so the dependency is declared as a git dependency pinned to a release tag. API documentation is generated locally with cargo doc --open -p borg. The library ships no provider client: the application implements the AgentLlmClient trait once for the API it uses, and the bundled examples run on a built-in fake client without an API key.
The first public release is v1.0.0, published on November 7, 2026, with the note that borg is now open source. Its notes list the composition primitives, fallback ladders and circuit breakers, guardrails, budgets, tools with MCP and image support, checkpoints, human-in-the-loop suspend and resume, borg-loop, borg-tracing and the testing utilities, plus safe defaults for subprocesses, MCP servers and event logs. According to SECURITY.md, only the latest release line (1.0.x) receives fixes, and vulnerabilities are reported privately through GitHub Security Advisories.
borg is dual-licensed under MIT or Apache-2.0 at the user's option, and contributions are dual-licensed the same way. The project states that borg-sandbox is not isolation: its TokioBackend runs ordinary subprocesses with the caller's privileges, and running untrusted code requires a real isolation layer behind the SandboxBackend trait. Other agent frameworks listed on iThub include LangChain, Agno and the Rust-based ZeroClaw.
Key capabilities
- Install as a git dependency Borg is added to
Cargo.tomlasborg = { git = "https://github.com/joydle/borg.git", tag = "v1.0.0" }together withasync-trait = "0.1", because the derive macros expand to#[async_trait]. It is not published on crates.io. The minimum supported Rust version is 1.88 and the runtime is Tokio. - Ten composition node types Pipelines are built from
Single,Sequential,Parallel,Branch,Fallback,LoopUntil,Agent,FallbackLadder,HeartbeatandDeferred. Leaves are agents, and every other node supervises its children the same way. They are written with thedslbuilders (seq,par,branch,repeat,fallback) or thepipeline!macro, which makes a composition a typed value whose shape can be fingerprinted. - Supervision and cancellation Cancellation uses a cooperative token tree, so cancelling the root unwinds every nested call. A panicking child surfaces as
BorgError::ChildPanickedunder its own name and never unwinds into its siblings. The release profile intentionally leavespanic = "abort"unset because the supervisor relies oncatch_unwind. - Restarts, meltdown and circuit breakers Restarts use exponential backoff with jitter, capped by attempts or wall-clock time, and honour
Retry-After. Session-wide meltdown detection stops a restart storm, by default at 20 restarts in 60 seconds. Circuit breakers work per provider and agent on consecutive failures, or as a shared sliding window. - Fallback ladders and retry classification A fallback ladder tries models or compositions in order with a user-defined fall-through rule, and on exhaustion keeps every rung's failure. Provider failures are mapped to one taxonomy (
FailureClass) that includes context-length and credit errors. - Budgets Admission is checked before every dispatch, compositions can carry sub-budgets, and pricing is cache-aware with discounted cache reads. Tool calls draw on the same budget as model calls.
- Guardrails A
GuardrailEngineevaluates behavioural rules at every agent-loop boundary, such as loops, repeated tool calls and text-only turns, and returnsWarn,ThrottleorHaltverdicts that the executor enforces. Six rules are built in, includingMaxContinuationsRule,RepeatedToolCallRule,RunawayCostRuleandConsecutiveFailureRule, and custom rules can be added. - Checkpoints and resume
execute_resumablesaves snapshots to aCheckpointStoreafter eachLoopUntiliteration by default, after every step, or manually. After a crash the same call skips finished work, and a snapshot from a differently shaped pipeline is refused.InMemoryCheckpointStoreships; the store trait has three methods, so a database such as Postgres, Redis or S3 can back it. - Human-in-the-loop pause and resume An agent can request a human decision; the run suspends, its snapshot is persisted, and it resumes later with a
Decisionto approve, reject or edit.borg_tools::approval::request_approvalwraps this case. - Long-lived sessions with borg-loop
ActorAgentprovides a typed mailbox and checkpoints to anActorStore.StreamingActorAgentstreams each turn's events live, parks when a reply is done and resumes across restarts; dropping a turn handle mid-stream parks the actor with its snapshot intact.ActorStoreships in-memory, LRU-caching and resilient primary-plus-fallback implementations. - Tools and parallel tool calls The object-safe
Tooltrait and derive macros define tools with JSON input schemas, which reach the model in its provider's shape. Parallel tool calls are opt-in per context, with a choice between collecting all results and failing fast. - MCP servers as tools
borg-mcpturns any stdio MCP server into tools the agent loop calls like native ones. Servers start from a cleared environment, and each call has a timeout (60 seconds by default), honours cancellation and caps its result at 1 MiB by default. - Model providers Borg ships no provider client; the application implements
AgentLlmClientonce. The typedProvidercovers OpenRouter, Anthropic, OpenAI, Bedrock, Google and Together, withCustomfor other services. Agents can pass images on the same request as their tools. - Tracing and event recording
borg-tracingemits a span tree from session to composition, step, turn and tool, with tokens and time to first token, intotracing, so OTLP, Jaeger or JSON logs work through the application's subscriber. Spans and task-locals propagate into tasks that borg spawns.FileEventRecorderwrites JSONL event logs for replay. - Subprocess tool
borg-sandboxprovidesSubprocessTool, which requires a program allowlist and a workspace root, does not inherit the caller's environment, never acceptsPATHor similar variables from the model, and caps output (64 KiB per line, 1 MiB total by default) with a 30-second default timeout. On Unix a cancel or timeout kills the process group; on Windows only the direct child is killed. - Testing utilities The
testingfeature exposesFakeLlmClient,ScriptedAgentand an eval harness for regression tests. The project site lists eight guarantees, each with a regression test in the workspace.
Where borg (Rust agent runtime) fits
Multi-step code generation pipelines
The README and site show a pipeline that plans, fans out a coder, a test writer and a doc writer in parallel, then repeats a build and fix loop until a verdict token reads PASS (at most eight rounds) before a review or deploy step. Each step reads the handoff state of the previous one, and cancelling the pipeline stops every nested agent and in-flight LLM call. The borg examples, including showcase and dogfood, run these patterns on the fake client with cargo run -p borg --example dogfood --features testing.
Tool-using agent loops
An agent_loop node runs the tool-use loop up to a step cap, dispatching tools registered in a Registry serially or in parallel. Guardrail rules watch the loop for repeated tool calls, consecutive failures, text-only turns and runaway cost. The tool_loop and parallel_tools examples drive this loop deterministically with a scripted fake client.
Provider fallback and failure handling
Fallback ladders try a chain of models or compositions under a user-defined fall-through rule, while circuit breakers and restart policies handle failing providers. The ladders_and_context example combines a typed provider ladder, a fallback ladder over compositions and a request-scoped task-local carried into every parallel branch.
Crash-resumable runs
Long pipelines run through execute_resumable with a run identifier and a checkpoint store. After a process crash the same call loads the snapshot, checks that its fingerprint matches the pipeline's shape and skips finished steps; resume points are Sequential steps and LoopUntil iterations, while Parallel, Branch and Fallback nodes re-run whole.
Approval before side effects
An agent or actor can pause before an action such as a production deploy, persist its state and exit. When a person answers, the actor is restored and receives the Decision. The human_in_the_loop example shows the full flow.
Long-lived streaming chat sessions
A streaming actor acts as the main loop of a chat session: each turn streams text deltas live, run_session_loop drives the actor until it parks, and after a restart resume_streaming_actor brings the same session back from its snapshot. The streaming_session example runs with cargo run -p borg-loop --example streaming_session.
Reviews of borg (Rust agent runtime)
Be the first to share your experience with borg (Rust agent runtime).
Write a review
Loading review form…
Found borg (Rust agent runtime) useful? Upvote it todayYour vote helps other IT teams find it in the daily ranking.






