SandBase Harness: a self-hosted runtime that wraps agents in sandboxes, credentials and audit
Local-first, self-hosted AI agent runtime and MCP bridge with sandboxed sessions, memory, credentials, audit/replay, and a local Console.
At a glance
- What is it?
- The project bundles session state, sandboxed tool execution, an MCP bridge and a local Console into one TypeScript runtime you run yourself. The README's install path is four commands long, and the interesting trade-off is that everything, including the audit trail, lives on your machine.
- Who is it for?
- Adopt SandBase Harness if you are running agents that execute generated code and you need the session state, tool permissions and audit trail to stay on infrastructure you control. Do not adopt it if you only need a thin stdio bridge to a model API, or if you want a managed control plane, since the README states there is no required hosted control plane and the storage is local SQLite and files.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap between a model loop and an agent you can operate
A model loop calls a model, gets text back, calls it again. That is enough for a demo and not enough for anything that runs unattended. The moment an agent writes a file, calls an internal API or holds an API key, you need four things the loop does not give you: a place for session state to survive a restart, a boundary around the code the agent generates, a way to decide which tools it may call, and a record of what it did. SandBase Harness is positioned as that layer. The README frames it as a runtime for agents where sessions, sandboxed tools, memory, credentials, audit trails and a Console all run on your machine or in your own infrastructure. The intended reader is an engineer who is already past the prototype stage and now has to answer questions about blast radius and reproducibility. The project is TypeScript, Apache-2.0, and ships a local Console at 127.0.0.1:3000/dashboard once started.
How the pieces fit: sessions, sandboxes, toolsets, vault
The README describes the runtime as covering four operational concerns rather than describing an internal call graph, so the architecture has to be read from what it exposes. Sessions are persistent and their event streams are resumable, which means the runtime keeps a durable record of a run rather than holding it in process memory. Sandboxed execution is offered across local, Docker, Kubernetes and self-hosted worker backends, so the boundary around generated code is a deployment choice rather than a fixed design. Tool access is mediated through MCP toolsets plus credential vaults and permission policies with approvals, which puts the runtime between the agent and whatever the tool actually does. Storage is local-first SQLite and file storage, and the README states there is no required hosted control plane. That last point is the one that shapes everything else: audit, replay and credentials are only as private as the machine they sit on, and there is no vendor-side copy to fall back on if the disk is lost. The repository also publishes an architecture diagram at docs/assets/sandbase-harness-architecture.svg, which is the place to look for the actual component wiring, since the README itself stays at the feature level.
Installing from a tagged release, not from main
The README's quickstart clones a specific tag rather than the default branch, which is worth copying deliberately. The commands are: git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git, then cd sandbase-harness, npm ci, npm run build. After that it creates a separate working directory for agent data with mkdir ../my-agents, changes into it, and runs node ../sandbase-harness/dist/index.js init followed by node ../sandbase-harness/dist/index.js start. The Console is then at http://127.0.0.1:3000/dashboard. Two details matter here. The init and start subcommands are run from the agent working directory, not from the checkout, so project state is separated from the runtime source. And npm ci rather than npm install means the lockfile is authoritative, which is the right default for a runtime that will hold credentials. The README points at docs/installation.md and llms-install.md for the full path; this review did not run any of these commands, so treat the sequence as documented behaviour rather than a verified transcript. Model providers listed are OpenAI, Anthropic, MiniMax and OpenAI-compatible endpoints, including DeepSeek V4.
Where the local-first design costs you
Local-first is a real constraint, not a slogan. The README states storage is SQLite and files with no required hosted control plane, which means the audit trail, the credential vault and the session history all live on the host you started. There is no documented multi-host replication story in the supplied material, so read the persistence section of the installation guide before assuming two machines can share one runtime state. The sandbox backends are also not equivalent. A local sandbox and a Kubernetes sandbox have very different isolation properties, and the README lists them side by side without claiming they are interchangeable. If your threat model assumes container or cluster isolation and you configure the local backend, you have the wrong boundary. The project is also the wrong tool when you do not need a runtime at all. The README itself draws this line: it points at SandBase CLI as a lightweight bridge for connecting client targets to models and APIs through a local stdio MCP bridge, and describes Harness as the choice when you need more than a model loop. If your agent is a single script that reads a prompt and prints a completion, the session store, vault and Console are overhead you will maintain and not use.
How it differs from a stdio MCP bridge
The nearest comparison the project itself offers is SandBase CLI, and the difference is architectural rather than a matter of features. A stdio MCP bridge is a transport: it takes a client's tool calls and forwards them to a model or API, and it holds no state between calls. Harness inverts that. It owns the session, persists the event stream, decides through permission policies and approvals whether a tool call proceeds, records the result for audit and replay, and executes the tool inside a sandbox rather than in the client process. The practical consequence is that a bridge cannot answer what an agent did last Tuesday, and Harness is built around being able to. The cost is that a bridge is a process you start and forget, while Harness is a service with a data directory, a build step, a Console and a sandbox backend to choose. The README also links a DeepSeek Harness Handbook for runtime guides and troubleshooting, which suggests the project expects configuration questions rather than a one-line install.
Release cadence and what upgrading actually involves
The recent release list shows v0.3.6 and v0.3.7 both dated 2026-08-20, roughly half an hour apart, and v0.3.8 on 2026-08-30. Two releases in one day usually means a fast fix after a tag, which is normal at this version number but worth knowing if you pin aggressively. The README's own quickstart pins v0.3.8 with a shallow clone, so the intended upgrade path is to change the tag, re-run npm ci and npm run build, then restart the runtime from your agent directory. Nothing in the supplied material describes a schema migration step for the SQLite store, so before upgrading across minor versions, check the release notes for that tag and back up the agent data directory. The project is pre-1.0, and the API and storage layout should be treated as moving. On licensing, the repository is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant and a patent termination clause. That is a summary of the licence identifier, not legal advice; if you are embedding the runtime in a product, read the LICENSE file and the NOTICE handling requirements yourself.
Who should run this, and what to check first
The fit is narrow and fairly clear. You are running agents that execute generated code or touch credentialed systems, you need the audit and replay record to stay on infrastructure you control, and you are willing to operate a service with a data directory and a sandbox backend. The mismatch is equally clear: single-prompt scripts, teams that want a managed control plane, and anyone who cannot decide which sandbox backend matches their isolation requirements. Verify three things before you commit. First, read docs/installation.md rather than a directory listing, because the README explicitly warns that one community page is stale at v0.3.4 and the current guide is the authority. Second, confirm which sandbox backend you will configure and that it gives the isolation you are claiming to your own reviewers. Third, open the Console at 127.0.0.1:3000/dashboard after init and confirm the audit and replay views show what your compliance story needs, because that is the feature the rest of the runtime exists to support.
Editorial conclusion
Adopt SandBase Harness if you are running agents that execute generated code and you need the session state, tool permissions and audit trail to stay on infrastructure you control. Do not adopt it if you only need a thin stdio bridge to a model API, or if you want a managed control plane, since the README states there is no required hosted control plane and the storage is local SQLite and files. Before committing, verify the sandbox backend you actually intend to use (local, Docker, Kubernetes or self-hosted worker) is the one your threat model assumes, and check the installation guide at docs/installation.md rather than a third-party directory listing, because the README notes at least one community page is stale at v0.3.4.
Community notes