# SandBase Harness: a local-first runtime that puts agent sessions, sandboxes and audit in one process

> SandBase Harness is a self-hosted TypeScript runtime for AI agents that combines sandboxed execution, MCP tool access, a credential vault, audit and replay, and a local Console. It is for teams who want agent infrastructure on their own machines rather than a hosted control plane.

**sandbaseai/sandbase-harness** — Local-first, self-hosted AI agent runtime and MCP bridge with sandboxed sessions, memory, credentials, audit/replay, and a local Console.

- Repository: https://github.com/sandbaseai/sandbase-harness
- Website: https://github.com/sandbaseai/sandbase-harness/blob/main/docs/installation.md
- Stars: 673 · Forks: 74
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/sandbaseai-sandbase-harness

## What SandBase Harness is for, and who ends up running it

Most agent projects start as a loop: call a model, get a tool call, execute it, feed the result back. That loop is easy to write and hard to operate. Once an agent runs for hours, calls tools that touch a filesystem or a network, and holds API keys, the questions change. Where did this session's events go? Which tool did it call at 03:00, and with what arguments? Can I resume it after a crash? Who approved that command?

SandBase Harness is aimed at those questions. The README describes it as "a local-first runtime for AI agents" with sessions, sandboxed tools, memory, credentials, audit trails, and a built-in Console, all running on your machine or in your own infrastructure. The table in the README frames the target user by need rather than by role: run generated code safely, inspect long-running agents, control tool access, operate any model, keep infrastructure yours.

That last row is the real positioning. The README states that storage is "local-first SQLite and file storage with no required hosted control plane." For a team that cannot send prompts, tool outputs or credentials to a third-party service, that constraint decides the tool before features do. The trade-off is that you now own the process, the disk, and the upgrade path. Nothing in the repository suggests a managed fallback.

The package name is worth noting because it trips people up. The repository is sandbaseai/sandbase-harness, but package.json declares "name": "managed-agents" and the two binaries are managed-agents and managed-agents-mcp. If you search for a package called sandbase-harness you will not find the CLI under that name.

## Sessions, sandbox backends and the MCP boundary

The runtime is a TypeScript project. package.json sets "type": "module", requires Node ">=22", and exposes two entry points: dist/index.js for the runtime and dist/mcp/index.js for the MCP side. The SDK is exported separately at ./sdk, so an application can embed the runtime rather than shell out to the CLI.

Sessions are the unit of work. The README claims persistent sessions and resumable event streams, and lists audit and replay alongside them. Read together, that implies events are written somewhere durable as the session runs, and replay reads them back. The README does not document the event schema, retention, or how replay handles a session whose tools have changed since the events were recorded. Treat replay as an inspection tool until you have checked that yourself.

Sandboxing is presented as a choice of backends rather than one implementation: the README lists local, Docker, Kubernetes, and self-hosted worker sandboxes. That is a wide range, and the operational cost differs enormously between them. A local sandbox on a developer laptop and a Kubernetes worker sandbox are not comparable isolation boundaries. The repository ships a Dockerfile.mcp and a .devcontainer directory, which is consistent with container-based execution being a first-class path, but the README does not spell out the isolation guarantees of each backend.

Tool access runs through MCP. The README describes "MCP toolsets, credential vaults, permission policies, and approvals" as the control surface, and the project is listed in the Official MCP Registry. The MCP bridge is therefore not an add-on: it is how tools reach the agent. Credentials live in a vault rather than in environment variables handed to the model, and approvals are a separate gate from permissions. Where those gates are configured is not shown in the README excerpt.

Model support is deliberately broad: OpenAI, Anthropic, MiniMax, and OpenAI-compatible providers, including DeepSeek V4. Because the provider list includes the OpenAI-compatible category, most self-hosted inference servers that speak that API should be reachable, though the README does not name any specific one.

## Installing SandBase Harness from source and starting the Console

The README gives a source install pinned to the v0.3.8 tag, which is the release dated 2026-08-30. Node 22 or newer is required. There is no npm install of a published package in the README example; you clone, install dependencies, and build.

```bash
git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build
```

npm run build runs two steps, build:runtime (tsdown) and build:console (a Vite build of the Console app), so the first build takes longer than a typical TypeScript compile. If you only want the runtime, build:runtime is the narrower target.

The README then initializes a separate working directory for agent state rather than running inside the checkout. That separation matters: the runtime lives in one directory, your agent project in another.

```bash
mkdir ../my-agents && cd ../my-agents
node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start
```

after which the README says to open http://127.0.0.1:3000/dashboard. The init step is what creates the local SQLite and file storage in that directory. If you skip it and run start in an empty folder, the README does not say what happens, so run init first.

For a persistent install, package.json declares two binaries, managed-agents and managed-agents-mcp, so npm link or a global install from the checkout gives you the same commands without the relative dist path. The examples directory contains examples/basic and examples/deepseek-harness; the latter is wired into package.json under the dsh key as a bundle patch pointing at examples/deepseek-harness/cordis.yml.

## Where SandBase Harness is the wrong tool

The strongest argument against it is the one the README makes for it. A local-first runtime with SQLite and file storage is not a horizontally scaled service. If you need many concurrent agent sessions spread across machines, or you want someone else to page when the runtime dies, this design works against you. You would be building the control plane the project deliberately omits.

The sandbox backends deserve the same scrutiny. The README lists local, Docker, Kubernetes, and self-hosted worker sandboxes without stating what each one isolates. A local sandbox is a convenience boundary for generated code you mostly trust; it is not a security boundary against hostile code. If your threat model includes an agent running untrusted third-party code, choose the backend on the evidence of its isolation model, not on the presence of the word sandbox in a feature table. The README does not provide that evidence.

The documentation is also uneven. The README is long on discovery links and short on operational detail: the excerpt does not cover the event schema, the credential vault's storage format, retention or rotation, or how permission policies and approvals are configured. There is an installation guide at docs/installation.md and an llms-install.md, and the README points to both, so the operational material may live there. Check before you commit.

Finally, version churn is real. Three releases landed between 2026-08-20 and 2026-08-30 (v0.3.6, v0.3.7, v0.3.8), with v0.3.6 and v0.3.7 published about half an hour apart. That is normal pre-1.0 activity, but it means pinning to a tag, as the README's own install command does, is the right habit. The README also warns that one third-party discovery page is stale at v0.3.4, which is a good reminder that directory listings lag the repository.

## How it differs from the SandBase CLI bridge

The README itself draws the nearest comparison, and it is worth taking at face value. SandBase CLI is described as "a lightweight bridge instead of a full runtime" that connects 25 AI client targets to 2,000+ models and APIs through a local stdio MCP bridge. SandBase Harness is the runtime: sessions, sandboxes, memory, credentials, audit, replay, Console.

The difference is architectural, not a matter of scale. A stdio MCP bridge is a translation layer. It takes a client's MCP requests and forwards them to a model or API, and when the process exits there is nothing left to inspect. The Harness keeps state: sessions persist, event streams can be resumed, and audit and replay exist as first-class features. If your problem is "my editor cannot talk to this model," the CLI is the smaller answer. If your problem is "I cannot tell what my agent did last night," the bridge has no answer at all.

There is a cost to that. The CLI installs as a bridge and stays out of the way. The Harness is a server with a Console on port 3000, a build step, and a data directory you now back up. Choosing the runtime means accepting an operational role. The README's own framing, "choose SandBase Harness when you need more than a model loop," is honest about that boundary.

## Licence, upgrades and what maintenance actually costs

The repository is licensed Apache-2.0, and the LICENSE file is included in the published files list. Apache-2.0 is permissive and includes an explicit patent grant, which matters if you are embedding the SDK at ./sdk in a commercial product. It also requires that you preserve notices and state changes. That is a description of the licence text, not legal advice; your counsel decides how it applies to your distribution.

Upgrade cost is dominated by the source build. Because the README installs from a git tag and runs npm ci plus npm run build, upgrading means fetching a new tag and rebuilding both the runtime and the Console. There is no documented migration path between versions in the README, and no documented rollback procedure. If session storage is SQLite and file based, a schema change between releases is the risk you are carrying. Test an upgrade against a copy of your data directory before you point it at the real one.

Maintenance status is easy to state from the facts. The repository is not archived, and the last push was on 2026-09-06, which is recent. Releases have been frequent through August 2026. The project is active, and it is also pre-1.0 at v0.3.8, so the API surface and the storage format are not yet promises.

The dependency surface is another cost. The runtime is TypeScript on Node 22+, with a Vite-built Console and a tsdown build, plus a Dockerfile.mcp for containerized MCP use. That is a normal modern Node toolchain, but it is a toolchain: you will be tracking Node versions and rebuilding the Console, not just pulling a binary.

## Conclusion

Adopt SandBase Harness if you need agent sessions you can inspect and replay, tool access gated through MCP with a credential vault, and storage that stays on your own disk. Do not adopt it if you want a hosted control plane, many concurrent sessions across machines, or a security boundary against hostile code that the README does not actually promise. Before committing, verify three things in the repository: the isolation model of whichever sandbox backend you pick, how permission policies and approvals are configured, and whether the event schema and credential storage format are documented well enough to survive an upgrade from v0.3.8. Pin the tag, as the README's install command does, and test the next release against a copy of your data directory.

## FAQ

### What is SandBase Harness?

It is a local-first, self-hosted runtime for AI agents, written in TypeScript, that combines persistent sessions, sandboxed tool execution, memory, a credential vault, audit and replay, and a local Console. The README describes it as running on your machine or in your own infrastructure, with SQLite and file storage and no required hosted control plane.

### How do I install SandBase Harness?

The README clones the repository at the v0.3.8 tag, runs npm ci and npm run build, then runs node dist/index.js init followed by node dist/index.js start in a separate agent directory. The Console is then at http://127.0.0.1:3000/dashboard. Node 22 or newer is required.

### Is SandBase Harness the same as SandBase CLI?

No. The README describes SandBase CLI as a lightweight local stdio MCP bridge connecting 25 AI client targets to 2,000+ models and APIs, while SandBase Harness is a full runtime with sessions, sandboxes, credentials, audit, replay and a Console.

### Which model providers does SandBase Harness support?

The README lists OpenAI, Anthropic, MiniMax, and OpenAI-compatible providers, including DeepSeek V4. Because OpenAI-compatible is one of the categories, providers that expose that API shape are covered by the same path.

### What sandbox backends can SandBase Harness use?

The README lists local, Docker, Kubernetes, and self-hosted worker sandboxes. It does not document the isolation guarantees of each backend, so pick one based on your own threat model rather than on the feature list alone.

### Under what licence is SandBase Harness released?

The repository is licensed Apache-2.0, and the LICENSE file is among the files the package publishes. Apache-2.0 is permissive and includes a patent grant, but how it applies to your distribution is a question for your own counsel.

## Sources

- [License: Apache-2.0](https://github.com/sandbaseai/sandbase-harness/blob/main/LICENSE)
- [Project website](https://github.com/sandbaseai/sandbase-harness/blob/main/docs/installation.md)
- [README](https://github.com/sandbaseai/sandbase-harness/blob/main/README.md)
- [Releases](https://github.com/sandbaseai/sandbase-harness/releases)
- [sandbaseai/sandbase-harness on GitHub](https://github.com/sandbaseai/sandbase-harness)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sandbaseai-sandbase-harness