SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI agentssandbase-harness

sandbase-harness

Self-hosted agent runtime with MCP tools, sandboxed execution, sessions, approvals, audit trails, and replay.

Open website

About this tool

Purpose

SandBase Harness is a local-first, self-hosted AI agent runtime and MCP bridge layer. It is aimed at developers who need to put AI agents into production: model SDKs handle the model loop, while production-grade agents also need persistent sessions, tool governance, sandbox boundaries, credential handling, memory, auditability, and a UI for humans to view the running process. This runtime is exactly what takes on this layer of responsibility. It is officially stated clearly that it is not a visual workflow builder, nor another model SDK.

Main capabilities

  • Compatible with the Claude Managed Agents-style /v1 API, and provides a local Console.
  • Uses SQLite by default to store metadata, covering agents, sessions, environments, credential vaults, memory stores, files, skills, and API keys; the byte content of files/skills is stored in the workspace state directory.
  • Supports resumable Server-Sent Events (SSE), used for session replay and debugging.
  • Configure a single active model provider boundary through Settings V2.
  • Sandbox backends: local processes, Docker (containers isolated per session), Kubernetes (kubectl exec/cp), self-hosted worker queues.
  • Supports MCP tool sets, permission policies, built-in tools, and skill packages.
  • Provides a TypeScript SDK in managed-agents/sdk.
  • Release gate command: npm run release:check.

Requirements and installation

Requires Node.js 22+, npm 10+, and a model provider API key (OpenAI, Anthropic, MiniMax, or any OpenAI-compatible endpoint). Docker is optional, and is only used when the Docker sandbox backend is needed.

The init command writes a workspace in the directory where you execute it: an agent, a skills folder, and config.yaml, in which provider references the ${OPENAI_API_KEY} environmentvariable. The start command is available at http://127.0.0.1:3000 to provide API and Console services.

Setup is in two steps, both at http://127.0.0.1:3000/dashboard in Settings > Setup:

  1. Provider: paste the API key into the provider form and save. The page will then indicate that the saved configuration has not yet taken effect and the runtime needs to be restarted—stop it with Ctrl+C and run the start command again, or use the restart button. Saved settings only take effect at startup. If the provider is not in the list, choose an OpenAI-compatible vendor and set its base URL.
  2. Model: in the Agent models panel, set the model ID that your provider actually offers—for example, DeepSeek uses deepseek-chat. Agents come with their own model IDs, so the gpt-4o written by init is not valid for all providers, and a wrong ID will cause that round of conversation to fail with model_not_found.

Sending the first message from the Console: open Sessions, create a session for the agent, and then type in the input box. From the terminal, just one command: chat sends that message and exits after that round ends; without --message, it keeps the session open and continues streaming output until you interrupt it. --tool-approval allow pre-authorizes tool calls the agent may initiate (the init template by default suspends tool calls pending manual approval); see the CLI documentation for details.

Note: the unscoped managed-agents name on npm is not this project. Before this repository officially publishes the official scoped package, please install only from the tagged GitHub source release shown above. Do not run npx managed-agents or npm install managed-agents.

Try it in Codespaces

The included development container installs dependencies and builds the runtime. Once the terminal is ready, start the server on the forwarded port, then open the forwarded SandBase Harness Console port and configure the model in Settings > Setup. Codespaces usage may be billed by GitHub; the local quick start above is still free and keeps all runtime data on your machine.

Using the official SDK

The runtime responds to its own /v1 API on the same port, and the official Anthropic The TypeScript SDK client can drive it without modification: point the client's baseURL at the runtime, provide the runtime API key, and the quickstart in examples/official-sdk can run a full round against the runtime (message, tool call, tool result, final reply). This example is executed by tests/conformance/official-sdk-quickstart.test.ts on every pull request, so the compatibility it describes is tested compatibility, not claimed compatibility. The same interface is specified in docs/api.md, and this repository's own TypeScript SDK is documented in the SDK section below.

CMA compatibility

The coverage of the published Claude Managed Agents contract is declared item by item in src/core/capabilities/matrix.ts: among the official SDK's route surface (110 method/path pairs as of SDK 0.131.0), 90 routes are mounted and 20 are rejected by name; no route is deferred. Partial and Unsupported entries always state the reason. The table below is generated by npm run docs:compat, and the contract honesty test fails when it is inconsistent with the matrix.

apply declarative usage

apply is the declarative form of the same API: a Markdown file whose frontmatter is the agent definition (the body below --- becomes the system prompt), a .yaml environment document, or a Markdown deployment manifest (the frontmatter carries name, agent, environment, schedule; the body becomes the initial user.message). The parsed id lands in managed-agents-lock.json next to the file, so re-running apply after editing updates the same resource rather than creating a duplicate—commit the lock file together with the manifest. Later files can reference earlier files by name, so apply coding-assistant.md environment.yaml deployment.md can associate the deployment with the lines created by the first two files.

Tool approval behavior

If a round of conversation requires a tool call that needs approval, it hangs rather than fails; chat asks before running, then lets the runtime continue the same round. --tool-approval allow decides all such calls in advance (scripts or CI tasks use this approach), while deny rejects them. When there is no terminal available to prompt, the default ask answers nothing and exits with a non-zero status, while listing the calls that are waiting, so scripts need to explicitly declare their policy rather than inherit the default policy. Custom tools are the exception: only your own client can produce their results, and chat states this and exits with a non-zero status.

API and authentication

The /v1 API follows the resource shape of Claude Managed Agents, so you can also point the Anthropic SDK at the local runtime. Open by default: authentication is active when at least one API key exists; the client sends Authorization: Bearer <key>.

Integrations and examples

  • DeepSeek Harness plugin—run this runtime as a DSH plugin via MCP stdio: installation, preflight, tool listing, and troubleshooting are in examples/deepseek-harness. DSH projects can also obtain portable skills from the GitHub source, for example npx --yes github:sandbaseai/sandbase-skills add multi-source-search installs to .dsh/skills/multi-source-search.
  • Agent Plugins 1.0 clients (Copilot CLI, VS Code) and the standalone MCP bridge container—see agent-plugin/PLUGIN.md.

Usage scenarios and configuration

  • Use cases—Showcase demonstrates auditable coding agents, DSH as an interactive frontend, and controlled code execution in Local, Docker, Kubernetes, and self-hosted sandboxes.
  • Agent configuration—YAML agent definitions, config.yaml, and workspace layout are in the usage guide; curl walkthroughs for each resource are in docs/api.md.

Machine-readable project metadata

  • Agent / MCP installationGuide
  • Agent Plugin marketplace list
  • DeepSeek Harness integration
  • Citation metadata

release:check runs type checking, tests, two builds, npm pack --dry-run, CLI init smoke test, and examples/basic startup smoke test. For the ecosystem catalog, community guides, and related projects, see docs/ecosystem.md. Community use case discussions include: migrating memory between Codex, Claude Code, and DSH; sandbox and filesystem protection for third-party plugins.

Limitations and Notes

  • Official materials do not provide specific fee or pricing information.
  • Official materials do not provide a platform support list (aside from Node.js 22+, npm 10+, and optional Docker).
  • Official materials do not provide performance metrics or effectiveness data.
  • Do not install the unscoped managed-agents package from npm; currently, installation is only supported from tagged GitHub source releases in this repository.

Related tools

Browse category