# sandbase-harness > Integrates a local-first AI Agent runtime into DSH, exposing agent, session, and artifact management capabilities via stdio MCP. ## Metadata - Author: [@sandbaseai](https://github.com/sandbaseai) - Repo: - GitHub: [sandbaseai/sandbase-harness](https://github.com/sandbaseai/sandbase-harness) - Stars: 613 - Language: TypeScript - License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html) - Homepage: - Topics: `agent-framework`, `agent-observability`, `agent-runtime`, `agent-sandbox`, `ai-agents`, `ai-infrastructure`, `deepseek`, `deepseek-harness`, `deepseek-v4`, `docker`, `dsh`, `dsh-plugin`, `local-first`, `mcp-server`, `model-context-protocol`, `openai-compatible`, `sandbox`, `self-hosted`, `typescript`, `workflow-automation` - Forks: 57 - Open Issues: 0 - Last push: 2026-08-17T05:39:59.000Z - Added: 2026-08-15T00:00:00.000Z ## Install ```bash dsh plugin --profile web add github:sandbaseai/sandbase-harness ``` ## Wiki ## One-sentence Positioning This plugin bridges the SandBase Harness local AI Agent runtime to DSH: through the stdio MCP protocol, enabling DSH to list Agents, create persistent sessions, stream messages, read artifacts, and stop running tasks just like using regular MCP tools. ## Core Capabilities - Registers a stdio MCP client named `sandbase` in DSH, automatically launching the `managed-agents-mcp` bridging process - Exposes 6 native MCP tools: `list_agents`, `create_session`, `run_session`, `get_session`, `list_artifacts`, `stop_session` - `run_session` waits for the streaming round to complete, returning assembled text and end event metadata in one go—no need to handle streams yourself - Supports OpenAI, Anthropic, and any OpenAI-compatible endpoints (including DeepSeek V4), with the runtime uniformly managing model vendor boundaries - Supports 4 sandbox backends: Local process, Docker container, Kubernetes Pod, self-hosted Worker queue—DSH is agnostic to the differences - Sessions, artifacts, Memory, skill packages, and API keys are all stored in local SQLite—no remote control plane dependency ## Technical Implementation - **Language**: TypeScript (Node.js ESM) - **Key Dependencies**: @modelcontextprotocol/sdk (MCP server), hono + @hono/node-server (HTTP API), ai + @ai-sdk/openai + @ai-sdk/anthropic (model calls), commander (CLI), zod (input validation) - **Architecture Pattern**: The `/v1` API exposed by the local CLI/HTTP runtime (`managed-agents start`) is encapsulated by a stdio MCP bridging process. DSH registers this bridge as an `mcp-sandbase-harness` node through a Cordis bundle. Communication between runtime and DSH uses HTTP + Bearer Token - **Entry Points**: `src/index.ts` (HTTP runtime entry), `src/mcp/index.ts` (stdio MCP bridge entry), packaged to npm bins `managed-agents` and `managed-agents-mcp` ## Use Cases When you want DSH to have a local Agent backend that "can run long-running tasks, preserve context, and invoke tools"—not just temporary one-off model conversations—this plugin integrates the existing SandBase Harness runtime. It's especially suited for scenarios requiring sandbox-isolated tool calls, post-hoc auditing and replay, or preserving artifacts and Memory across sessions. ## Prerequisites and Compatibility | Dependency | Minimum Version | Description | |---|---|---| | DSH | Not declared | Injected via `dsh.bundle.patch`, minimum DSH version not declared in package.json | | Node.js | >=22 | `package.json#engines.node`; bridge process uses stdio MCP, runtime based on Node 22+ built-in HTTP | | Platform | Cross-platform | Node process itself is cross-platform; runtime additionally depends on host's `docker` / `kubectl` CLI as optional (only needed when enabling corresponding sandbox) | | node:sqlite | Node 22 experimental / Node 25+ stable | Database layer depends on `node:sqlite`; note this module is experimental on older Node versions | | Docker | Optional | Host needs `docker` CLI when sandbox backend is set to `docker` | | kubectl | Optional | Host needs `kubectl` and cluster access when sandbox backend is set to `kubernetes` | ## Installation ```bash dsh plugin --profile web add github:sandbaseai/sandbase-harness ``` ## Configuration This plugin itself has no user-facing configurable parameters; it hardcodes registration of a stdio MCP client named `sandbase` in DSH through a Cordis patch. The bridge process `managed-agents-mcp` communicates with the underlying HTTP Runtime via environment variables at runtime: | Environment Variable | Description | Default | |---|---|---| | `MANAGED_AGENTS_URL` | Runtime HTTP address for the bridge process to connect to | `http://127.0.0.1:3000` | | `MANAGED_AGENTS_API_KEY` | Bearer Token passed when runtime has access authentication enabled; multiple Keys separated by commas | None (runtime runs in open mode if not configured) | | `MANAGED_AGENTS_CORS_ORIGINS` | Comma-separated list of allowed CORS origins | None | | `MANAGED_AGENTS_LOG_LEVEL` | Runtime log level (debug / info / warn / error) | `info` | | `MANAGED_AGENTS_LOG_FORMAT` | Set to `pretty` for readable development format | Normal format | | `MANAGED_AGENTS_HOME` | Override root path for runtime state directory | `.managed-agents/` under workspace | | `MANAGED_AGENTS_SECRET_KEY` | Master key for encrypting local credential store | Unencrypted when not set | ## FAQ **Q: Do I need to start any additional services after installing this plugin?** A: Yes. The plugin only registers the `managed-agents-mcp` bridge process in the DSH Web Profile. You must first start the underlying runtime in another terminal with `managed-agents start` (default listening at http://127.0.0.1:3000) so DSH can access Agents and sessions through MCP tools. **Q: What's the relationship between this plugin and DSH's built-in AI capabilities?** A: It's an independent local Agent runtime (based on SQLite + multiple sandbox backends), not a replacement for DSH's built-in models. DSH treats it as an external MCP service via the `mcp__sandbase__*` namespace, and it dispatches to OpenAI, Anthropic, or any OpenAI-compatible endpoint. **Q: Where are sessions, artifacts, and credentials stored?** A: All stored in the `.managed-agents/` directory under your workspace created during `managed-agents init` (SQLite file `data.db`, file bytes `files/`, skill packages `skills/`, sandbox snapshots `snapshots/`). The bridge process doesn't persist any credentials. **Q: Which model vendors are supported?** A: Configure an active model vendor boundary in Settings V2, covering OpenAI, Anthropic, and any OpenAI-compatible endpoints (README uses DeepSeek V4 as example). Agent YAML specifies concrete model IDs (e.g., `gpt-4o`, `claude-sonnet-4-20250514`, `openai/gpt-5.5`). **Q: Is Docker required?** A: No. The default Local sandbox executes commands as the current OS user without Docker dependency. You only need `docker` CLI or `kubectl` available when you switch the Environment's sandbox backend to docker or kubernetes in the Dashboard. **Q: How to uninstall?** A: First stop DSH, then execute `dsh plugin --profile web remove managed-agents` to remove both profile dependencies and bundle injection layers. Runtime workspace data won't be automatically deleted—you need to manually clean up the `.managed-agents/` directory. **Q: What to do if "MCP startup failed" appears at startup?** A: This means `managed-agents-mcp` is not in PATH. Rebuild from source (`npm ci && npm run build:runtime`) and run `npm link`, or check if the `mcp-sandbase-harness` node appears in DSH startup logs. ## Difficulty Level Advanced — requires independently maintaining a Node runtime in another terminal and having at least one model API Key ready; also requires understanding multiple concept groups like Settings V2, Environment, and Sandbox Provider. DSH itself is just the calling entry point. ## Known Issues and Limitations - **Local sandbox has no kernel-level isolation**: Local backend only does path constraints and environment variable whitelist; commands still execute as the current OS user—unsuitable for running untrusted code (BACKLOG.md:27-30) - **apps/console has unconsolidated module split**: Currently has two mutually non-rendering component inheritance lines; `npm run typecheck` doesn't cover Console, causing ~90 errors in Dashboard; test coverage is for unreleased branch (BACKLOG.md:46-59) - **Kubernetes sandbox live cluster tests skipped in CI**: Tests skip directly when no accessible cluster is available; there's currently no mechanism to force execution (BACKLOG.md:32-34) - **Streaming command output (streamingExec) declared but unimplemented**: Capability is declared and reported as "unsupported"; tool results still return as single values (BACKLOG.md:39-41) - **`managed-agents deploy` is a v1 placeholder**: Only prints deployment suggestions, doesn't actually push (src/cli/program.ts:85-99) - **Pod eviction only exposed as command failure**: Provision phase fails quickly on image/config errors, but runtime Pod eviction has no dedicated handling path (BACKLOG.md:35-37) - **Workspace state directory changed from 0.2.0**: Migrated from `~/.managed-agents/-/` to `/.managed-agents/`; old workspaces need manual state migration (CHANGELOG.md:39-47) --- This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [sandbase-harness](https://deepseek-plugin.org/plugins/sandbaseai/sandbase-harness) Wiki generated by AI (model: `MiniMax-M2.5`)