sandbaseai/sandbase-harness

English | 中文
AI-readable project metadata: llms.txt · installation guide
A local-first runtime for AI agents. Sessions, sandboxed tools, memory,
credentials, audit trails, and a built-in Console — all running on your
machine or in your own infrastructure.
Why
Agent SDKs handle the model loop. Production agents need more: persistent
sessions, tool governance, sandbox boundaries, credential handling, memory,
auditability, and a UI for humans to inspect what happened. managed-agents
is that runtime layer — not a visual workflow builder and not another model SDK.
| Need | What Harness provides |
| --- | --- |
| Run generated code safely | Local, Docker, Kubernetes, and self-hosted worker sandboxes |
| Inspect long-running agents | Persistent sessions, resumable event streams, audit, and replay |
| Control tool access | MCP toolsets, credential vaults, permission policies, and approvals |
| Operate any model | OpenAI, Anthropic, MiniMax, and OpenAI-compatible providers, including DeepSeek V4 |
| Keep infrastructure yours | Local-first SQLite and file storage with no required hosted control plane |
Features
- Claude Managed Agents-style /v1 API and local Console
- SQLite metadata by default for agents, sessions, environments, credential
vaults, memory stores, files, skills, and API keys — local file/skill bytes
in the workspace state directory
- Resumable Server-Sent Events for session replay and debugging
- One active model provider boundary configured through Settings V2
- Sandbox backends: local process, Docker (per-session containers), Kubernetes
(kubectl exec/cp), self-hosted worker queue
- MCP toolsets, permission policies, built-in tools, and skill packages
- TypeScript SDK at managed-agents/sdk
- Release gate: npm run release:check
Quick Start
Requirements: Node.js 22+, npm 10+, and a model provider API key (OpenAI,
Anthropic, MiniMax, or any OpenAI-compatible endpoint). Docker is optional and
only needed for Docker-backed sandboxes.
init writes a workspace into the directory you run it from: an agent, a skills
folder, and config.yaml, whose provider reference is the ${OPENAI_API_KEY}
environment variable. start serves the API and the Console on
.
Two steps finish the setup, both on **Settings > Setup** at
:
1. **The provider.** Paste your API key into the provider form and save. The page
then reports that the saved configuration is not active yet, so restart the
runtime — stop it with Ctrl+C and run the start command again, or use the
restart button. A saved setting only takes effect at startup. If your provider
is not in the list, choose the OpenAI-compatible vendor and set its base URL.
2. **The model.** In the **Agent models** panel, set the model ID your provider
actually serves — deepseek-chat for DeepSeek, for example. An agent carries
its own model ID, so the gpt-4o that init writes is not valid for every
provider, and a wrong ID fails the turn with model_not_found.
Send the first message from the Console: open **Sessions**, create a session for
the agent, and type into the composer. From a terminal it is one command:
chat sends that one message and exits once the turn settles; without
--message it keeps the session open and streams until you interrupt it.
--tool-approval allow
preauthorizes the tool calls the agent may make, which the init template
otherwise parks for approval and waits for a person to answer; see CLI.
The unscoped managed-agents name on npm is not this project. Until an
official scoped package is announced in this repository, 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.
When the terminal is ready, start the server on the forwarded port:
Open the forwarded **SandBase Harness Console** port, then configure a model in
**Settings > Setup**. Codespaces usage may be billed by GitHub; the local
quick start above remains free and keeps all runtime data on your machine.
Screenshots
| Console overview | Settings | API reference |
| --- | --- | --- |
| | | |
Use the Official SDK
The runtime answers its own /v1 API on that same port, and an official
Anthropic TypeScript SDK client drives it unchanged: point the client's
baseURL at the runtime, give it the runtime API key, and the quickstart in
examples/official-sdk runs a whole turn —
message, tool call, tool result, final reply — against it. That example is