sandbaseai/sandbase-harness

SandBase Harness – A Local‑First Runtime for AI Agents

What it is – SandBase Harness is a self‑hosted runtime that lets you run AI agents (e.g., Claude‑style “managed agents”) safely on your own machine or infrastructure. It adds the missing production‑grade pieces that SDKs alone don’t provide: persistent sessions, sandboxed tool execution, credential vaults, audit trails, and a web console for inspection.

Key capabilities

Feature	What you get
API compatible with Claude Managed Agents	Exposes a /v1 HTTP API that mirrors the Claude Managed Agents contract, so existing Anthropic‑style SDKs work out‑of‑box.
Local‑first storage	All metadata (agents, sessions, environments, memory, files, API keys, etc.) is stored in a SQLite file inside the workspace – no external database required.
Sandbox back‑ends	Run generated code in isolated environments: plain local process, Docker containers (one per session), Kubernetes kubectl exec/cp, or a custom self‑hosted worker queue.
Tool governance	MCP‑style toolsets, permission policies, credential injection, and an approval gate that can auto‑approve or require human confirmation.
Session replay & debugging	Events are logged to an append‑only stream and can be streamed via Server‑Sent Events (SSE) for live debugging or later replay.
Model‑agnostic	Works with OpenAI, Anthropic, MiniMax, DeepSeek V4 and any OpenAI‑compatible endpoint.
Web console	A built‑in UI (http://127.0.0.1:3000) shows sessions, settings, API reference and lets you inspect agent turns in real time.
TypeScript SDK	managed‑agents/sdk provides typed client helpers for the runtime.

How to get started

1. Install Node 22+, npm 10+ (Docker optional).
2. Clone the repo, run npm ci && npm run build.
3. Initialise a workspace: node dist/index.js init.
4. Start the server: node dist/index.js start.
5. Open the console, add your model provider API key, pick a model, and create a session.
6. Send a message via the UI or the CLI, e.g.

   node dist/index.js chat agent_assistant --message "hello" --tool-approval allow
   

   The --tool-approval allow flag pre‑authorises any tool calls the agent wants to make.

Why it matters

• Safety – Code generated by agents runs in isolated containers, preventing accidental host compromise.
• Auditability – Every event (model request, tool call, credential use) is recorded and can be replayed.
• Control – Fine‑grained permission policies let you decide which tools an agent may use and under what conditions.
• Portability – Because everything lives in local files, you can move the workspace, back it up, or run it behind a firewall without a cloud control plane.

Where it fits SandBase Harness sits between a low‑level model SDK (which only sends prompts) and a full‑blown orchestration platform. It is ideal for developers building autonomous agents that need persistent state, tool use, and strict security, while still wanting to stay on‑premise.

Links from the repo

• Architecture diagram – docs/assets/sandbase-harness-architecture.svg
• API spec – docs/api.md
• Official TypeScript SDK – managed‑agents/sdk
• Compatibility matrix – Shows which parts of the Claude Managed Agents contract are fully supported, partially supported, or unsupported.
• Codespaces template – Quick one‑click cloud dev environment.

---

All details above are taken directly from the repository’s README; no additional features have been inferred.