What Is sandbase-harness? A Local-First AI Agent Runtime

sandbase-harness is a local-first AI agent runtime plugin in the DeepSeek Harness (DSH Plugin) ecosystem that turns the model loop into production-grade agent infrastructure: persistent sessions, sandboxed tools, memory, a credential vault, audit and replay, and a built-in console, all running on your own machine or infrastructure with data staying local by default. Based on the official README, this article covers what it is, its core features, installation and enabling, typical usage, and common troubleshooting.

What Is sandbase-harness?

sandbase-harness solves the problem that agent SDKs handle only the model loop while production agents need persistent sessions, tool governance, sandbox boundaries, credential handling, and auditability: it supplies that runtime layer as a local-first runtime with a console for humans to inspect what happened. The positioning and facts below all come from the official README (source):

sandbase-harness is developed in TypeScript by the sandbaseai team and open-sourced under Apache-2.0. It is positioned as a local-first agent runtime — not a visual workflow builder and not another model SDK. It exposes a Claude Managed Agents-style /v1 API and a local console, and supports OpenAI, Anthropic, MiniMax, and any OpenAI-compatible endpoint, including DeepSeek V4. It stores metadata in SQLite and keeps file and skill bytes on local storage by default, with no required hosted control plane; it needs Node.js 22+ and npm 10+. It runs standalone or as a DSH plugin, bridging to DSH over MCP stdio so native mcp__sandbase__* tools become callable from DSH.

What Are the Core Features of sandbase-harness?

The core capabilities of sandbase-harness are sandboxed execution, persistent sessions, tool governance, a credential vault, multi-model support, and local-first storage: long-running agents execute safely, stay controllable and auditable, and keep data on your machine. These capabilities all come from the official README (source):

• Sandboxed execution: four sandbox backends — local process, Docker (per-session containers), Kubernetes (kubectl exec/cp), and self-hosted worker queues — for safely running generated code.
• Persistent sessions and replay: SQLite-backed session metadata with resumable Server-Sent Events for replay, audit, and debugging; file and skill bytes live in the workspace state directory.
• Tool governance: MCP toolsets, permission policies, built-in tools, and skill packages, combined with approval workflows to control agent tool access.
• Credential vault: centralizes API keys and sensitive information with approval flows, so callers do not hold keys directly.
• Multi-model support: OpenAI, Anthropic, MiniMax, and OpenAI-compatible endpoints including DeepSeek V4, with one active model provider per workspace (Settings V2 boundary).
• Local-first storage: SQLite metadata plus local file storage with no hosted control plane, alongside a TypeScript SDK (managed-agents/sdk) and an Anthropic-SDK-compatible /v1 API.

How to Install and Enable sandbase-harness?

Installing sandbase-harness has two steps: add the plugin with the DSH CLI, then start the runtime and configure a model in the built-in console; it can also run standalone without DSH. The commands and facts below all come from the official README (source):

1. Install the plugin with DSH: run the install command in the DeepSeek Harness terminal:

dsh plugin --profile web add github:sandbaseai/sandbase-harness

Wait for the command to report a completed install, then restart dsh web; the runtime exposes mcp__sandbase__* tools to DSH over an MCP stdio bridge.

2. Start the runtime and console: point the bridge at the runtime URL and boot DSH:

export MANAGED_AGENTS_URL=http://127.0.0.1:3000
dsh web

Or run it standalone:

node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start

3. Configure a model provider: open http://127.0.0.1:3000/dashboard, paste an API key under Settings > Models, and you are running; sandbox, storage, and memory settings live in Settings V2 (form/JSON modes with automatic restart).

4. Update sandbase-harness: update the plugin with the DSH update command:

dsh plugin --profile web update sandbase-harness

5. Uninstall sandbase-harness: remove the plugin from the current profile:

dsh plugin --profile web remove sandbase-harness

Typical sandbase-harness Usage

Typical sandbase-harness usage is "create an agent and environment, start a session, then replay the event stream": define an agent and a sandbox, open a session to chat with the agent, and use the event stream to inspect what happened. (source) The steps below cover daily usage from creation to audit.

1. Create an agent: define an agent through the /v1/agents endpoint with a name, model, system prompt, and tools:

curl -X POST http://127.0.0.1:3000/v1/agents \
  -H "Content-Type: application/json" \
  -d '{"name":"Incident commander","model":"gpt-4o","system":"You are an on-call incident commander."}'

2. Create a sandbox environment: use a Docker-isolated environment for generated code:

curl -X POST http://127.0.0.1:3000/v1/environments \
  -H "Content-Type: application/json" \
  -d '{"name":"Docker sandbox","config":{"sandbox_provider":"docker","image":"node:22-slim"}}'

3. Start a session and send messages: create a session, then message the agent so it works inside the sandbox:

curl -X POST http://127.0.0.1:3000/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"agent":"agent_...","environment_id":"env_...","title":"Triage SENTRY-123"}'
curl -X POST http://127.0.0.1:3000/v1/sessions/SESSION_ID/messages \
  -H "Content-Type: application/json" \
  -d '{"content":"Investigate the alert."}'

4. Replay the session event stream: stream and resume sessions with resumable Server-Sent Events (Last-Event-ID enables resume):

curl -N http://127.0.0.1:3000/v1/sessions/SESSION_ID/events/stream \
  -H "Last-Event-ID: 42"

5. Manage the runtime from the CLI: managed-agents list shows agents, managed-agents chat <agent-id> --message "hello" chats directly, and managed-agents reload hot-reloads configuration.

sandbase-harness Troubleshooting

The four most common sandbase-harness issues, their typical symptoms, and how to Fix them: an unreachable console, failing Docker sandboxes, unresponsive model calls, and a git-install error, addressed respectively with host/port settings, Docker prerequisites, model keys, and the pnpm build allowlist. (source)

1. The console is unreachable: the symptom is that http://127.0.0.1:3000/dashboard does not open; the cause is usually a busy port or a 127.0.0.1-only binding; to fix it, start with --host 0.0.0.0 --port <new> or adjust the port in Settings V2.

2. Creating a Docker sandbox fails: the symptom is an error when creating a docker environment; the cause is Docker not installed or running, or the DSH process lacking access to the Docker daemon; to fix it, confirm docker info works and grant the process daemon access.

3. Model calls get no response: the symptom is the agent staying silent after a message; the cause is an invalid API key, an unconfigured provider, or more than one active provider per workspace; to fix it, verify the key under Settings > Models and keep one provider active.

4. Git install fails with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED: the symptom is the first dsh plugin --profile web add failing while printing an exact key; the cause is the pnpm build allowlist blocking the git dependency; to fix it, add the printed key under allowBuilds: in the profile's pnpm-workspace.yaml and re-run the same add command.

Use Cases and Notes

sandbase-harness fits agent workflows that need long-running, auditable, sandboxed execution while keeping data on your own machine; note that the runtime is open by default, so enable key authentication for production. (source)

Use cases: auditable coding agents, controlled code execution across local/Docker/Kubernetes/self-hosted sandboxes, automated tasks needing session replay and audit, and using DeepSeek Harness as an interactive front end for a full runtime. Notes:

1. The runtime is open by default; creating at least one API key activates authentication, and clients send Authorization: Bearer <key> — configure a key in production.
2. The unscoped managed-agents package on npm is not this project; install only from this repository's tagged GitHub source, and do not run npx managed-agents.
3. Docker and Kubernetes sandboxes have prerequisites (Docker daemon access, kubectl cluster access); the local-process sandbox is lightest but isolates least.
4. A git-hosted install may fail on the first add because of the pnpm build allowlist; add the printed key under allowBuilds: in pnpm-workspace.yaml and re-run — this is expected, not a failed install.

Project Links

sandbase-harness is an open-source project maintained by sandbaseai (Apache-2.0). Plugin details: sandbase-harness plugin details.

This page is an independent guide rewritten from the plugin's official README — for the authoritative documentation and the latest changes, defer to the source: sandbaseai/sandbase-harness. A plugin is third-party code that runs on your machine once installed; inclusion is not an endorsement — review the source before installing.