trackmcp
Back to directory
sandbaseai

sandbase-harness

View on GitHub

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

642 stars TypeScriptOthers Updated Sep 3, 2026
agent-observabilityagent-runtimeai-agentsdeepseek-harnessmcp-servermodel-context-protocolagent-sandboxai-infrastructurelocal-firstself-hostedaudit-loggingmcp-gatewayagent-harnessharness-engineeringsandboxed-executiondsh-plugindevopsdockerkubernetesagent-plugin

Documentation

SandBase Harness

English | 中文

GitHub stars
Listed on deepseek-plugin.org
Release
Official MCP Registry
Discussions
CodeQL
License

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.

> Building with DeepSeek Harness? The independent DeepSeek Harness Handbook provides source-backed runtime guides, multilingual troubleshooting, and a regularly updated Agent-first resource map.

SandBase Harness architecture

> Looking for a lightweight bridge instead of a full runtime? SandBase CLI

> connects 25 AI client targets to 2,000+ models and APIs through a local stdio MCP bridge.

> If it fits your workflow, star SandBase CLI

> so other agent users can discover it.

> Need hosted model and media APIs instead? SandBase provides one interface for

> LLM, image, and video generation APIs,

> with the API quickstart covering keys and first calls.

bash
git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build
mkdir ../my-agents && cd ../my-agents
node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start
# open http://127.0.0.1:3000/dashboard

Choose SandBase Harness when you need more than a model loop:

NeedWhat Harness provides
Run generated code safelyLocal, Docker, Kubernetes, and self-hosted worker sandboxes
Inspect long-running agentsPersistent sessions, resumable event streams, audit, and replay
Control tool accessMCP toolsets, credential vaults, permission policies, and approvals
Operate any modelOpenAI, Anthropic, MiniMax, and OpenAI-compatible providers, including DeepSeek V4
Keep infrastructure yoursLocal-first SQLite and file storage with no required hosted control plane

If this runtime solves a real agent-infrastructure problem for you,

star the repository so other builders can find it.

Find SandBase Harness

The project is also discoverable through these independent ecosystem directories:

Recently verified community references:

Pending community review:

These listings are independent directories; the repository and its release metadata

remain the source of truth.

Try it in Codespaces

Open in GitHub Codespaces

The included development container installs dependencies and builds the runtime.

When the terminal is ready, start the server on the forwarded port:

bash
node dist/index.js start --host 0.0.0.0

Open the forwarded SandBase Harness Console port, then configure a model in

Settings > Models. Codespaces usage may be billed by GitHub; the local

quick start below remains free and keeps all runtime data on your machine.

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.

Features

  • Claude Managed Agents-style `/v1` API and local Console
  • SQLite-backed agents, sessions, environments, credential vaults, memory

stores, files, skills, and API keys — SQLite metadata by default

  • local file/skill bytes stored 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

  • Settings V2: one workspace model vendor, loop engine, storage, memory,

sandbox — with validation, form/JSON modes, and restart flow

  • MCP toolsets, permission policies, built-in tools, and skill packages
  • DeepSeek Harness bridge over MCP stdio for agents, sessions, streamed turns,

artifacts, and cancellation

  • TypeScript SDK at `managed-agents/sdk`
  • Release gate: `npm run release:check`

Screenshots

Console overviewSettingsAPI reference
!overview!settings!api-ref

Start with a use case

See the Showcase for three practical paths: an auditable

coding agent, DeepSeek Harness as an interactive front end, and controlled code

execution across Local, Docker, Kubernetes, and self-hosted sandboxes.

For client-specific setup, see the installation guide,

including the pinned Cline CLI command and the Docker MCP Bridge configuration.

Community use-case discussions:

Requirements

  • Node.js 22+
  • npm 10+
  • A model provider API key (OpenAI, Anthropic, MiniMax, or an OpenAI-compatible endpoint)
  • Docker (optional, for Docker-backed sandboxes)

DeepSeek Harness

Run this project as a DSH plugin instead of treating `dsh-plugin` as discovery

metadata only. Install the bundle into a DSH profile, start `managed-agents`,

then boot that profile:

bash
export MANAGED_AGENTS_URL=http://127.0.0.1:3000
# Preferred: install a local source checkout after `npm run build`.
dsh plugin --profile web add -w ../sandbase-harness
# Git URL fallback. Keep HTTPS; do not convert the spec to SSH.
# dsh plugin --profile web add git+https://github.com/sandbaseai/sandbase-harness.git
dsh web

If Plugin Hub reports `already installed: managed-agents` after a partial or

repeated install, update the Hub first, then remove only the displayed

`managed-agents` plugin entry and retry from the tagged HTTPS Git source:

bash
dsh plugin --profile web update dsh-plugin
dsh plugin --profile web remove managed-agents
dsh plugin --profile web add git+https://github.com/sandbaseai/sandbase-harness.git

This is a Plugin Hub duplicate-install path, not an npm installation path. If

the installed view shows a different target identifier, remove that exact

identifier instead. Keep the profile directory and its evidence until the

runtime starts successfully; see the reported recovery issue.

The profile installs the verified source checkout directly; it does not resolve

the unrelated unscoped npm package. A git-hosted install runs `prepare` only

when `dist/` is missing. Keep the HTTPS git spec; converting it to SSH fails on

Windows hosts without GitHub SSH access.

A git-hosted install needs one extra step for pnpm's build allowlist. The

first `dsh plugin --profile web add` fails with

`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED` and prints the exact key. Add that key

under `allowBuilds:` in the profile's `pnpm-workspace.yaml`, then re-run the

same add command; a plain package name does not match a git-hosted

resolution:

yaml
allowBuilds:
  "managed-agents@https://codeload.github.com/sandbaseai/sandbase-harness/tar.gz/": true

The second run builds `dist/` through `prepare`, creates the

`managed-agents` / `managed-agents-mcp` bins, and joins the bundle layer. The

patch starts the bundled MCP entry over

stdio. DSH can then list agents,

create and run sessions, inspect results and artifacts, and stop work through

native `mcp__sandbase__*` tools. See

`examples/deepseek-harness` for the full

tool list and authenticated-runtime configuration.

For a walkthrough that starts with DSH and adds this runtime as a real

third-party plugin, read the

DeepSeek Harness developer guide.

The Chinese edition

is available as well; both articles are maintained against the pinned

SandBase Harness v0.3.8 integration.

Pair the plugin with SandBase Skills to give the same DSH project a portable,

source-verifiable research workflow:

bash
npx --yes github:sandbaseai/sandbase-skills add multi-source-search
dsh web

This installs the complete Skill into `.dsh/skills/multi-source-search`, DSH's

project-scoped discovery directory. It runs from GitHub source and needs no

SandBase account when DSH already provides web/search tools.

For a complete, reproducible workflow that combines the evidence ledger with

sandboxed execution, credentials, audit, and replay, read

Build an Auditable Research Agent.

New to DSH profiles, plugin composition, tool policy, or session semantics? The

independent DeepSeek Harness Handbook

provides source-backed quickstarts, architecture maps, and troubleshooting for

the runtime layers used by this integration. Read its [SandBase Harness bridge

guide](https://sandbaseai.github.io/deepseek-harness-handbook/sandbase-harness-bridge.html)

for the DSH-specific contract, then start with the local-browser

Install Doctor

for installation evidence, or use the

Failure Router

to identify the first broken runtime boundary.

Quick Start

bash
git clone --branch v0.3.8 --depth 1 https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness
npm ci
npm run build
mkdir ../my-agents && cd ../my-agents
node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start

Open `http://127.0.0.1:3000/dashboard`, go to Settings > Models, paste your

API key, and you're running.

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`.

The six-tool MCP bridge is published as a multi-architecture OCI image. Start

the Harness API, then add this stdio command to an MCP client:

Container package: GitHub Container Registry

bash
docker pull ghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8
docker run --rm -i \
  -e MANAGED_AGENTS_URL=http://host.docker.internal:3000 \
  ghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8

For an authenticated remote runtime, also pass `MANAGED_AGENTS_API_KEY`. The

container image contains only the MCP bridge; agent sessions and sandbox work

remain in the connected Harness runtime. Every release image is built from the

matching Git tag for `linux/amd64` and `linux/arm64`, includes OCI source and

MCP ownership metadata, and receives a GitHub build-provenance attestation.

Portable Agent Plugin

Copilot CLI, VS Code, and other Agent Plugins 1.0 clients can install the same

OCI-backed MCP bridge directly from this repository. Start the Harness API and

Docker first, then expose its URL to the plugin process:

bash
export MANAGED_AGENTS_URL=http://host.docker.internal:3000
# Optional when the runtime requires authentication:
export MANAGED_AGENTS_API_KEY=your-runtime-key

copilot plugin install sandbaseai/sandbase-harness:agent-plugin

The plugin passes these environment variables through to the pinned

`ghcr.io/sandbaseai/sandbase-harness-mcp:0.3.8` image. It does not store a key

in `plugin.json`, `mcp.json`, or the installed plugin files. On Linux, the

plugin's Docker command maps `host.docker.internal` through `host-gateway`.

For development from the latest `main` branch:

bash
git clone https://github.com/sandbaseai/sandbase-harness.git
cd sandbase-harness && npm ci && npm run build
cd .. && mkdir my-agents-dev && cd my-agents-dev
node ../sandbase-harness/dist/index.js init
node ../sandbase-harness/dist/index.js start

Workspace Layout

text
my-agents/
├── agents/                  # Seed agent definitions (YAML)
│   └── assistant.yaml
├── skills/                  # Seed skill packages
│   └── example-skill/
│       └── SKILL.md
└── .managed-agents/         # Runtime state (gitignored)
    ├── config.yaml          # Workspace configuration
    ├── data.db              # SQLite metadata
    ├── logs/runtime.log
    ├── files/               # Uploaded file bytes
    ├── skills/              # Uploaded skill packages
    ├── snapshots/           # Session workspace snapshots
    └── sandbox/             # Local session sandboxes

Configuration

`.managed-agents/config.yaml`:

yaml
model:
  provider: openai
  api_key: ${OPENAI_API_KEY}

storage:
  metadata: { provider: sqlite, options: {} }
  artifacts: { provider: local, options: { base_path: files } }

Agents pick concrete model IDs (`gpt-4o`, `claude-sonnet-4-20250514`,

`openai/gpt-5.5`). The workspace config only says how to reach the model

service.

For DeepSeek V4 Pro/Flash configuration, including maximum reasoning effort,

see DeepSeek V4.

For first-class MiniMax configuration, regional endpoints, and the supported

MiniMax-M3 and MiniMax-M2.7 model IDs, see MiniMax.

CLI

bash
managed-agents init
managed-agents start [--host 127.0.0.1] [--port 3000]
managed-agents list
managed-agents reload
managed-agents chat  --message "hello"
managed-agents template list | install  | create

API Examples

Create an agent:

bash
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.",
    "tools": [{ "type": "agent_toolset_20260401" }]
  }'

Create an environment (local sandbox):

bash
curl -X POST http://127.0.0.1:3000/v1/environments \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default local",
    "config": { "hosting_type": "local", "sandbox_provider": "local" }
  }'

Create a Docker-isolated environment:

bash
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",
      "resources": { "memory": "1g", "cpu": 1 }
    }
  }'

Start a session:

bash
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"
  }'

Send a message:

bash
curl -X POST http://127.0.0.1:3000/v1/sessions/SESSION_ID/messages \
  -H "Content-Type: application/json" \
  -d '{ "content": "Investigate the alert." }'

Resume the event stream:

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

SDK

typescript
import { ManagedAgentsClient } from 'managed-agents/sdk';

const client = new ManagedAgentsClient({
  baseUrl: 'http://127.0.0.1:3000',
});

const session = await client.sessions.create({
  agent: 'agent_...',
  environment_id: 'env_...',
});

for await (const event of client.sessions.chat(session.id, 'Hello')) {
  if (event.type === 'agent.message_chunk') {
    process.stdout.write(event.delta ?? '');
  }
}

The `/v1` API follows Claude Managed Agents resource shapes, so you can also

point the Anthropic SDK at the local runtime:

typescript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.MANAGED_AGENTS_API_KEY ?? 'local-dev-key',
  baseURL: 'http://127.0.0.1:3000',
});

const session = await client.beta.sessions.create({
  agent: 'agent_...',
  environment_id: 'env_...',
});

Authentication

Open by default. Authentication activates when at least one API key exists:

bash
# Static key via environment
export MANAGED_AGENTS_API_KEY=sk-local-example

# Or create a managed key
curl -X POST http://127.0.0.1:3000/v1/api-keys \
  -H "Content-Type: application/json" \
  -d '{ "name": "Local Console" }'

Clients send `Authorization: Bearer `.

Agent Definition

Agents are YAML files in `agents/`:

yaml
name: Incident commander
description: Triages alerts and coordinates response.
model: gpt-4o
system: |-
  You are an on-call incident commander.
mcp_servers:
  - name: sentry
    type: url
    url: https://mcp.sentry.dev/mcp
tools:
  - type: agent_toolset_20260401
    default_config:
      permission_policy: { type: always_ask }
    configs:
      - name: bash
        permission_policy: { type: always_ask }
  - type: mcp_toolset
    mcp_server_name: sentry
skills:
  - type: custom
    skill_id: skill_...
metadata:
  template: incident-commander

Development

bash
npm ci
npm run typecheck    # src + tests
npm test             # vitest
npm run build        # runtime + console + SDK
npm run release:check  # full local release gate

`release:check` runs typecheck, tests, both builds, `npm pack --dry-run`, CLI

init smoke, and `examples/basic` startup smoke.

SandBase Ecosystem

Agent Skills for research, social intelligence, marketing, and business

workflows across Codex, Claude Code, Cursor, Gemini CLI, and other clients.

Codex, Windsurf, Gemini CLI, OpenCode, and other MCP clients to 2,000+ AI

models and APIs with one onboarding command.

filter, install, and manage community DeepSeek Harness plugins from the native

Settings experience.

  • SandBase — hosted agent infrastructure, model access,

tools, and managed sandboxes.

Documentation

Community Guides

— a reproducible guide combining evidence ledgers, sandboxed execution,

credentials, audit, and replay with SandBase Harness.

by SSD Nodes — an independent VPS walkthrough covering installation, agent

configuration, MCP servers, sandbox modes, and reverse-proxy deployment. The

article demonstrates v0.3.2; use the current release command above for v0.3.8.

License

Apache-2.0

Frequently asked questions

What is sandbase-harness?

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

How do I install sandbase-harness?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is sandbase-harness open source?

Yes — it is hosted on GitHub at https://github.com/sandbaseai/sandbase-harness and has 642 stars.

Related MCP tools

desplega-aiagent-swarm

Your Company Agentic Operating System

741 TypeScript
ai-agentsagenticagentic-framework+15
metatool-aimetamcp

MCP Aggregator, Orchestrator, Middleware, Gateway in one docker

2,647 TypeScript
mcpmcp-servermcp-servers+12
mcpjungleMCPJungle

One place to manage & connect to all your MCP servers

1,243 Go
ai-agentsmodel-context-protocolinfrastructure+5
skyhook-ioradar

The missing open-source Kubernetes UI with a built-in MCP server for AI agents. See what's broken, why, and what changed. Issues, Topology, event timeline, Helm, GitOps, live service traffic, and cluster audits - all in one Go binary.

3,246 Go
argocdcloud-nativegitops+17
AVIDS2memorix

Open-source cross-agent memory layer for coding agents via MCP. Compatible with Claude Code, Codex, Cursor, Windsurf, Gemini CLI, Antigravity, OpenClaw, Hermes Agent, Oh-my-Pi, Pi, Copilot, Kiro, OpenCode, and Trae.

721 TypeScript
ai-codingclaude-codecopilot+17
KnockOutEZwigolo

The go-to web for your AI coding agent — local-first search, fetch, crawl & research over MCP. No API keys, no cloud, $0/query. Public beta.

4,906 TypeScript
mcpagentai+17

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP